stack/packages/mosaic/framework/defaults/README.md

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 init or by editing files in ~/.config/mosaic/ after installation.

Quick Install

Mac / Linux

bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-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 git@git.mosaicstack.dev:mosaic/mosaic-stack.git ~/src/mosaic-stack
cd ~/src/mosaic-stack && bash tools/install.sh

The installer:

• Downloads the framework from the monorepo archive
• Installs it to ~/.config/mosaic/
• Installs @mosaicstack/mosaic globally via npm (unified mosaic CLI — TUI, gateway client, wizard)
• Adds ~/.config/mosaic/bin to your PATH
• Syncs runtime adapters and skills
• Runs a health audit
• Detects existing installs and preserves local files (SOUL.md, USER.md, etc.)

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 Jarvis --style direct --user-name Jason --timezone America/Chicago

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:

1. Verifies ~/.config/mosaic exists
2. Verifies SOUL.md exists (auto-runs mosaic init if missing)
3. Injects AGENTS.md into the runtime
4. 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.)
├── bin/                   ← CLI tools (mosaic launcher, mosaic-init, mosaic-doctor, etc.)
├── tools/                 ← Tool suites: git, orchestrator, prdy, quality, etc.
├── 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:

bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)

Or from a local checkout:

cd ~/src/mosaic-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 --ref v1.0    # Install from a specific git ref

Universal Skills

The installer syncs skills from mosaic/agent-skills into ~/.config/mosaic/skills/, then links each skill into runtime directories.

mosaic sync                                    # Full sync (clone + link)
~/.config/mosaic/bin/mosaic-sync-skills --link-only   # Re-link only

Health Audit

mosaic doctor                                          # Standard audit
~/.config/mosaic/bin/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/bin/mosaic-ensure-sequential-thinking
~/.config/mosaic/bin/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