fred
efb3c3a10c
Three guides that existed only as one host's working copy, promoted to framework templates so every estate gets them. A working copy under ~/.mosaic binds one host; only a template here binds all of them. SEAT-IDENTITY.md (new) documents how a seat's git credential is actually resolved after #1311: identity from MOSAIC_GIT_IDENTITY, then mosaic.gitIdentity, then the stdin username; host mapped to a store prefix; then ONE of two stores chosen by whether the seat directory exists, with no precedence and no fallback between them. A seat with a directory and an empty slot fails closed rather than reaching the service store, and that is the point. It also corrects how to find the helper. credential.helper commonly names an absolute path, so `command -v git-credential-mosaic` answers a different question than the one git asks, and the two stop agreeing the moment the PATH copy is removed. Git also tries EVERY configured helper in order, so a fail-closed helper in front silently hands the request to whatever is configured behind it. The guide says to read the whole list. FLEET-COMMS.md (new) documents agent-send.sh: the class table, the addressing preamble, and the exit codes — including that rc=2 means the text reached the pane as an unsubmitted draft, so retrying double-sends it. Confirm with capture-pane instead. It also says to measure the fleet rather than trust roster.yaml, which on a live host was simultaneously naming a socket that did not exist, listing seats that were not running, and omitting seats that were. CODE-REVIEW.md gains an Evidence Discipline section: a green is not a result until you have shown it could go red, measurement and explanation are separate sentences, verify by content on the ref that ships rather than by ancestry of a local sha, and confidence is part of a finding. Plus four shell-measurement rules earned on #1311, each of which produced a wrong conclusion first — `cmd | tail; echo rc=$?` reports tail's status, a missed glob under pipefail exits 2 and kills the run under set -e, nonzero-with-no-output is an environment question before it is a code question, and `git -C` in a non-repo directory answers from the enclosing repo. The estate-specific repository exception that lived in the working copy is not carried here. The template says an estate may document one, scoped to a named repository and never precedent for a second. Both new guides are added to the two routing tables that agents read.
Mosaic Agent Framework
Universal agent standards layer for Claude Code, Codex, OpenCode, and Pi.
One config, every runtime, same standards.
This is the framework component of mosaic-stack. No personal data, credentials, user-specific preferences, or machine-specific paths should be committed. All personalization happens at install time via
mosaic initor by editing files in~/.config/mosaic/after installation.
Quick Install
Mac / Linux
curl -fsSL https://mosaicstack.dev/install.sh | bash
Or use the direct URL:
bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
Windows (PowerShell)
# PowerShell installer coming soon — use WSL + the bash installer above.
From Source (any platform)
git clone [email protected]:mosaicstack/stack.git ~/src/stack
cd ~/src/stack && bash tools/install.sh
The installer:
- Downloads the framework from the monorepo archive
- Installs it to
~/.config/mosaic/ - Installs
@mosaicstack/mosaicglobally via npm (unifiedmosaicCLI — TUI, gateway client, wizard) - Adds
~/.config/mosaic/binto your PATH - Syncs runtime adapters and skills
- Runs a health audit
- Detects existing installs and preserves local files (SOUL.md, USER.md, etc.)
Install lanes
| Lane | Command | Use when | Source |
|---|---|---|---|
| Stable | bash tools/install.sh |
You want the released framework and CLI | npm @mosaicstack/mosaic@latest + main |
| Prerelease integration | bash tools/install.sh --next |
You want the permanent next integration lane |
Fast npm @mosaicstack/mosaic@next + @mosaicstack/gateway@next; source fallback at next |
| Contributor/source build | bash tools/install.sh --dev --ref X |
You are validating a branch before release | Build-from-source at the requested git ref |
--next is fast-by-default from the Gitea npm next dist-tag and falls back to a source build at the permanent next branch if the dist-tag is missing or unreachable. Explicit --ref or MOSAIC_REF wins and uses the source path.
First Run
After install, open a new terminal (or source ~/.bashrc) and run:
mosaic init
If Node.js 18+ is installed, this launches an interactive wizard with two modes:
- Quick Start (~2 min): agent name + communication style, sensible defaults for everything else
- Advanced: full customization of identity, user profile, tools, runtimes, and skills
The wizard configures three files loaded into every agent session:
SOUL.md— agent identity contract (name, style, guardrails)USER.md— your user profile (name, timezone, accessibility, preferences)TOOLS.md— machine-level tool reference (git providers, credentials, CLI patterns)
It also detects installed runtimes (Claude, Codex, OpenCode, Pi), configures sequential-thinking MCP, and offers curated skill selection from 8 categories.
Non-Interactive Mode
For CI or scripted installs:
mosaic init --non-interactive --name "Mosaic Agent" --style direct --user-name "Your Name" --timezone "UTC"
All flags: --name, --role, --style, --user-name, --pronouns, --timezone, --mosaic-home, --source-dir.
Legacy Fallback
If Node.js is unavailable, mosaic init falls back to the bash-based mosaic-init script.
Launching Agent Sessions
mosaic pi # Launch Pi with full Mosaic injection (recommended)
mosaic claude # Launch Claude Code with full Mosaic injection
mosaic codex # Launch Codex with full Mosaic injection
mosaic opencode # Launch OpenCode with full Mosaic injection
mosaic yolo claude # Launch Claude in dangerous-permissions mode
mosaic yolo pi # Launch Pi in yolo mode
The launcher:
- Verifies
~/.config/mosaicexists - Verifies
SOUL.mdexists (auto-runsmosaic initif missing) - Injects
AGENTS.mdinto the runtime - Forwards all arguments to the runtime CLI
You can still launch runtimes directly (claude, codex, etc.) — thin runtime adapters will tell the agent to read ~/.config/mosaic/AGENTS.md.
Architecture
~/.config/mosaic/
├── AGENTS.md ← THE source of truth (all standards, all runtimes)
├── SOUL.md ← Agent identity (generated by mosaic init)
├── USER.md ← User profile and accessibility (generated by mosaic init)
├── TOOLS.md ← Machine-level tool reference (generated by mosaic init)
├── STANDARDS.md ← Machine-wide standards
├── guides/ ← Operational guides (E2E delivery, PRD, docs, etc.)
├── tools/ ← Tool suites: git, orchestrator, prdy, quality, etc.
│ └── _scripts/ ← Framework helper scripts (sync skills, doctor, runtime links)
├── runtime/ ← Runtime adapters + runtime-specific references
│ ├── claude/ ← CLAUDE.md, RUNTIME.md, settings.json, hooks
│ ├── codex/ ← instructions.md, RUNTIME.md
│ ├── opencode/ ← AGENTS.md, RUNTIME.md
│ ├── pi/ ← RUNTIME.md, mosaic-extension.ts
│ └── mcp/ ← MCP server configs
├── skills/ ← Universal skills (synced from mosaic/agent-skills)
├── skills-local/ ← Local cross-runtime skills
├── memory/ ← Persistent agent memory (preserved across upgrades)
└── templates/ ← SOUL.md template, project templates
How AGENTS.md Gets Loaded
| Launch method | Injection mechanism |
|---|---|
mosaic pi |
--append-system-prompt with composed runtime contract + skills + extension |
mosaic claude |
--append-system-prompt with composed runtime contract (AGENTS.md + runtime reference) |
mosaic codex |
Writes composed runtime contract to ~/.codex/instructions.md before launch |
mosaic opencode |
Writes composed runtime contract to ~/.config/opencode/AGENTS.md before launch |
claude (direct) |
~/.claude/CLAUDE.md thin pointer → load AGENTS + runtime reference |
codex (direct) |
~/.codex/instructions.md thin pointer → load AGENTS + runtime reference |
opencode (direct) |
~/.config/opencode/AGENTS.md thin pointer → load AGENTS + runtime reference |
Management Commands
mosaic help # Show all commands
mosaic init # Interactive wizard (or legacy init)
mosaic doctor # Health audit — detect drift and missing files
mosaic sync # Sync skills from canonical source
mosaic bootstrap <path> # Bootstrap a repo with Mosaic standards
mosaic upgrade # Upgrade installed Mosaic release
mosaic upgrade check # Check upgrade status (no changes)
Upgrading
Run the installer again — it handles upgrades automatically:
curl -fsSL https://mosaicstack.dev/install.sh | bash
Or use the direct URL:
bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
Or from a local checkout:
cd ~/src/stack && git pull && bash tools/install.sh
The installer preserves local SOUL.md, USER.md, TOOLS.md, and memory/ by default.
Flags
bash tools/install.sh --check # Version check only
bash tools/install.sh --framework # Framework only (skip npm CLI)
bash tools/install.sh --cli # npm CLI only (skip framework)
bash tools/install.sh --next # Prerelease lane: npm @next, source fallback
bash tools/install.sh --dev # Contributor lane: source build at --ref/main
bash tools/install.sh --ref v1.0 # Install from a specific git ref (--ref wins over --next)
The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
Universal Skills
The installer syncs skills from mosaic/agent-skills into ~/.config/mosaic/skills/. Install, wizard finalization, and mosaic update automatically reconcile every canonical skill into Claude Code's ~/.claude/skills/ directory.
mosaic sync # Full canonical catalog sync
~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only
mosaic skill list # Show registered, missing, dangling, and foreign entries
mosaic skill register <name> # Register or repair one canonical Claude link
mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
Skill names are direct children using [A-Za-z0-9][A-Za-z0-9._-]*, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use /reload-skills or start a new session.
M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosaic root through its launcher configuration. Codex parity remains follow-up scope and continues to use the existing full skill-sync linker.
Health Audit
mosaic doctor # Standard audit
~/.config/mosaic/tools/_scripts/mosaic-doctor --fail-on-warn # Strict mode
MCP Registration
sequential-thinking MCP (Hard Requirement)
sequential-thinking MCP is required for Mosaic Stack. The installer registers it automatically. To verify or re-register manually:
~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking
~/.config/mosaic/tools/_scripts/mosaic-ensure-sequential-thinking --check
Claude Code MCP Registration
MCPs must be registered via claude mcp add — not by hand-editing ~/.claude/settings.json.
claude mcp add --scope user <name> -- npx -y <package>
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
claude mcp list