Documents the correct MCP registration flow: claude mcp add --scope user
writes to ~/.claude.json (not settings.json, which silently ignores
mcpServers). Covers scope semantics, http vs sse transport requirement
for FastMCP, sequential-thinking hard requirement, and OpenBrain setup.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude Code reads mcpServers from ~/.claude.json (global state file),
NOT from ~/.claude/settings.json. The settings.json mcpServers key is
silently ignored for MCP loading. Using claude mcp add --scope user
writes to the correct file.
Also document correct registration commands and scope semantics in
RUNTIME.md so agents and users know how to add MCPs that actually load.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Agents consistently ignore written instructions about memory routing
and default to writing local MEMORY.md files regardless of rules in
RUNTIME.md, CLAUDE.md, or MEMORY.md itself. Instructions alone are
insufficient — a technical gate is required.
Changes:
- Add tools/qa/prevent-memory-write.sh — PreToolUse hook that blocks
Write/Edit/MultiEdit to ~/.claude/projects/*/memory/*.md (exit 2)
- Register hook in runtime/claude/settings.json PreToolUse array
- Update runtime/claude/RUNTIME.md: replace soft "Memory Override"
note with hard-gate policy, what-goes-where table, and rationale
- Rewrite guides/MEMORY.md: OpenBrain as primary layer, blocked silos
table, project continuity files, how-the-hook-works section
The correct behavior is now the only possible behavior for Claude Code.
All agent learnings route to OpenBrain where every harness can read them.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
REST endpoints (GET/PATCH/DELETE /v1/thoughts/{id}, bulk DELETE/GET
with filters) and updated MCP tools list to include get, update,
delete, delete_where, list_thoughts — all live in v0.1.0.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- credentials.sh: add turbo-cache and openbrain cases (load_credentials openbrain
exports OPENBRAIN_URL + OPENBRAIN_TOKEN from credentials.json .openbrain.*)
- credentials.sh: update --help text and error messages to list new services
- TOOLS.md: mark Coolify as DEPRECATED (superseded by Portainer Docker Swarm)
- TOOLS.md: update Shared Credential Loader service list (turbo-cache, openbrain)
- TOOLS.md: add OpenBrain section — primary shared memory layer, REST API patterns,
Python client usage, MCP note, and mandatory usage table
credentials.sh is always overwritten on reinstall (not in PRESERVE_PATHS), so all
agents that run install.sh will automatically get openbrain credential support.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Show individual step names with OK/FAIL/RUN/SKIP/WAIT status
- Show error messages and exit codes for failed steps
- Convert epoch timestamps to ISO 8601
- Always fetch full pipeline detail (list endpoint lacks workflows)
- Fix started_at/finished_at field names (API uses started/finished)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add -a <instance> flag to all Authentik wrapper scripts, matching the
existing multi-instance pattern used by Woodpecker and Cloudflare.
credentials.json now supports per-instance Authentik config:
authentik.<instance>.url — instance URL
authentik.<instance>.token — API token (admin wrappers)
authentik.<instance>.test_user — username/password (Playwright/agent tests)
authentik.default — default instance name
Legacy flat structure (authentik.url) still works as fallback.
Token cache is now per-instance (~/.cache/mosaic/authentik-token-<name>).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Woodpecker tokens from credentials.json now always override env vars,
preventing stale .bashrc or env leakage from silently winning
- After loading, credentials are synced to ~/.woodpecker/<instance>.env
so the wp CLI wrapper stays current automatically
- Sync only writes when values differ to avoid unnecessary disk I/O
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Agents had no guidance on which Woodpecker instance serves which repos,
leading to repeated 401 failures and workaround attempts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add prdy-status.sh for quick one-liner PRD health check (short/json output)
- Inject PRD section count and assumption count into agent system prompt
so the agent knows PRD state at session start without running validate
- Add status subcommand to mosaic prdy routing and help text
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
POSIX ERE doesn't support non-greedy +? quantifier, so the pattern
([^/]+?)(\.git)?$ matched .git as part of the repo name instead of
stripping it. Split into two sed passes: strip .git first, then
extract owner/repo.
Fixes wp_detect_repo() and init-project.sh CICD_REPO_NAME.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Woodpecker v3 requires numeric repo IDs in API endpoints, not
owner/repo path segments. The old paths hit the SPA frontend
catch-all and return HTML, which downstream tools misinterpret
as auth failure (401).
- Add tools/woodpecker/_lib.sh with wp_resolve_repo_id() helper
that calls /api/repos/lookup/{owner}/{repo} to get numeric ID
- Update all 3 pipeline scripts to resolve repo ID before API calls
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add named instance support matching the existing cloudflare pattern:
- credentials.sh: woodpecker-<name> loads .woodpecker.<name>.{url,token}
- credentials.sh: bare woodpecker resolves via .woodpecker.default or
WOODPECKER_INSTANCE env, with legacy flat-key fallback
- All 3 pipeline tools accept -a <instance> flag to select instance
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
e2e-delivery.md → E2E-DELIVERY.md
orchestrator.md → ORCHESTRATOR.md
ci-cd-pipelines.md → CI-CD-PIPELINES.md
Agents on case-sensitive filesystems couldn't find these guides because
AGENTS.md referenced uppercase names but the files were lowercase.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
All launch paths (claude, codex, opencode, yolo variants) now write a
session.lock before exec'ing, so `mosaic coord status` can detect
running agent sessions. Stale locks from dead sessions are cleaned up
automatically on next launch.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Previously `mosaic coord status` only said "No active session" with no
indication of whether a mission existed. Now shows mission name, status,
milestones/tasks progress, and actionable next steps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Global AGENTS.md: task-type-to-model-tier mapping table with decision
rule — haiku for search/status, sonnet for standard coding/review,
opus only for complex architecture and security.
Claude RUNTIME.md: Task tool model parameter syntax with examples
and quick reference table.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- zone-list, record-list, record-create, record-update, record-delete
- Named instance support (-a flag) with configurable default
- Zone name-to-ID auto-resolution in shared _lib.sh
- Updated credentials loader with cloudflare/cloudflare-<name> services
- TOOLS.md and INFRASTRUCTURE.md guide documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Post-mortem from website agent session that manually built/pushed Docker
images instead of using existing Woodpecker CI pipelines. Root cause:
agent skipped E2E intake because the task "felt simple."
AGENTS.md hard gates 10-12:
- Manual docker build/push FORBIDDEN when CI pipelines exist
- MUST check for pipeline config before any build/deploy action
- Load order and intake are NOT conditional on task complexity
E2E-DELIVERY.md:
- Complexity trap warning on intake section
- Mandatory deployment surface check (step 3) with pipeline discovery
- Expanded forbidden anti-patterns with Build/Deploy section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Mission context was buried at the end of a 21K char system prompt and the
agent ignored it. Two fixes:
1. Mission block now emits FIRST in build_runtime_prompt() so it's the most
prominent instruction the agent sees
2. When an active mission exists and no user prompt is given, auto-inject
an initial user message triggering the agent to read mission state files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The session-start hook approach didn't work — Claude Code's TUI
overwrites stdout before the agent sees it, and the hook only fires
when the agent calls it as a tool.
Instead, inject mission context directly into the composed system
prompt via build_runtime_prompt(). When mission.json is active in
CWD, the agent gets mission name, ID, milestone progress, and
mandatory first-action instructions in its initial context.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
grep -c returns empty on no match, causing arithmetic to break
across lines. Use ${var:-0} fallback pattern.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
MEMORY.md was conditionally loaded so agents defaulted to their native
memory locations (e.g. ~/.claude/projects/*/memory/). This caused durable
learnings to be siloed per-runtime instead of shared across agents.
- Move MEMORY.md to mandatory load order in AGENTS.md (position 7)
- Add Memory Override section to all three runtime configs (Claude, Codex,
OpenCode) explicitly forbidding native memory silos for durable data
- Add memory/ directory with .gitkeep to bootstrap source
- Add mkdir -p for memory/ in install.sh post-sync step
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Mac/Linux curl one-liner and Windows PowerShell one-liner at the top
- First-run flow (mosaic init → mosaic claude)
- Architecture diagram showing AGENTS.md as single source of truth
- Injection mechanism table for all runtimes (launcher vs direct)
- All mosaic CLI commands documented
- mosaic upgrade workflow documented
- Removed outdated sections superseded by the mosaic launcher
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Detects and cleans up files that are now centralized:
- SOUL.md: removed (now global at ~/.config/mosaic/SOUL.md)
- CLAUDE.md: replaced with thin pointer to global AGENTS.md
- AGENTS.md: stale load-order sections stripped, project content preserved
Supports --dry-run, --all (scan ~/src/*), and per-project paths.
Creates .mosaic-bak backups before any modification.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Create ~/.config/mosaic/AGENTS.md as the canonical universal agent config
- Runtime adapters (CLAUDE.md, opencode/AGENTS.md, codex/instructions.md) are
now thin pointers that say "READ ~/.config/mosaic/AGENTS.md"
- mosaic claude: injects AGENTS.md via --append-system-prompt
- mosaic opencode/codex: copies AGENTS.md to runtime config path before launch
- mosaic-link-runtime-assets: pushes thin pointers for direct launch fallback
AGENTS.md is runtime-agnostic. All runtimes get the same standards.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
SOUL.md injection happens via ~/.claude/CLAUDE.md directive (pushed by
mosaic-link-runtime-assets), not CLI flags. The launcher now just does
pre-flight checks and launches the runtime directly.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Green ✓ for success, yellow ⚠ for warnings, red ✗ for errors
- Bold section headings (Installing, Post-install, PATH, Summary)
- Summary block with numbered next steps (source shell profile, mosaic init)
- Suppressed noisy sub-script output — only status lines shown
- Colors auto-disabled when not running in a terminal (piped output)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- install.sh: detects shell profile (zsh/bash/profile), adds PATH entry if missing
- install.ps1: adds to User PATH via SetEnvironmentVariable if missing
- Both are idempotent — show "already in PATH ✓" on re-run
- mosaic/mosaic.ps1: accept "help" and "version" as bare subcommands
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add SOUL.md.template with {{PLACEHOLDERS}} for interactive generation
- Add mosaic-init (bash + PS1) for interactive SOUL.md creation with flag overrides
- Add mosaic launcher (bash + PS1) — unified CLI for claude/opencode/codex with SOUL.md injection
- Add codex runtime adapter (runtime/codex/instructions.md)
- Update runtime adapters (claude, opencode) with SOUL.md read directive
- Update mosaic-link-runtime-assets to push codex adapter to ~/.codex/
- Update installers to prompt for mosaic init when SOUL.md is missing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- remote-install.sh: POSIX one-liner (curl | sh), downloads archive to tmpdir
- remote-install.ps1: Windows one-liner (irm | iex), fully native PowerShell
- install.ps1: Native Windows installer calling all .ps1 post-install scripts
- bin/mosaic-link-runtime-assets.ps1: Syncs runtime config files
- bin/mosaic-sync-skills.ps1: Clones skills, links via directory junctions
- bin/mosaic-migrate-local-skills.ps1: Migrates local skills to junctions
- bin/mosaic-doctor.ps1: Health audit for Windows environments
Directory junctions used instead of symlinks (no elevation required).
All junction operations fall back to file copy on failure.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
