Files

T

fargo 1556982dbc skills: single install path — canonical skills ship with the framework

Phase D2 of plan 2026-08-19: single package, single install, single command.

The framework installer already treats skills/** as a shipped, manifest-owned
framework subtree, so the folded skills now install into
$MOSAIC_HOME/skills with the rest of the framework — no second repository,
no separate sync step:

- mosaic-sync-skills (bash + powershell): the fetch machinery is gone (clone,
  pull, dirty-state migration, rsync from sources/agent-skills). The script
  now only links installed skills into runtime homes. --link-only is a compat
  no-op; --no-link exits having nothing to do.
- catalog.ts: the sources/agent-skills fallback is dead and removed.
- install.sh, launch.ts, defaults/README.md, README.md, skills/README.md:
  references to the second repo rewritten to describe the shipped path.

Verified: clean install into a fresh MOSAIC_HOME produces 102 skills with no
sources/ directory; the linker then links the selected skills into the four
runtime homes with no git involvement.

2026-08-19 14:39:28 -05:00

AGENTS.md

guides: add SEAT-IDENTITY and FLEET-COMMS; harden CODE-REVIEW evidence rules

2026-08-18 18:15:50 -05:00

CONSTITUTION.md

docs(framework): P3.1 fast-follow — governance wording + gate scope + bare-launch note (#577 )

2026-06-21 18:56:50 +00:00

README.md

skills: single install path — canonical skills ship with the framework

2026-08-19 14:39:28 -05:00

SOUL.md

feat(framework): P1+P2 — public sanitization + blocking CI gate (#572 )

2026-06-21 02:40:11 +00:00

STANDARDS.md

fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960 )

2026-08-11 18:22:15 -05:00

TOOLS.md

fix(fleet): enforce exact comms authority (#787 )

2026-07-16 00:32:23 +00:00

USER.md

fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960 )

2026-08-11 18:22:15 -05:00

wake-watch-list.schema.json

fix(wake): #925 framework-ship canon fallback-wake (systemd timer + schema bound + A10 install/validate) — F7 out of the box (#931 )

2026-07-26 13:44:51 +00:00

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

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/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.)

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/mosaic exists
Verifies SOUL.md exists (auto-runs mosaic init if missing)
Injects AGENTS.md into 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 (shipped with the framework package)
├── 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

Canonical skills ship inside the framework package itself; the installer installs them into ~/.config/mosaic/skills/ together with the rest of the framework (there is no separate skills repository). Install, wizard finalization, and mosaic update automatically link every canonical skill into Claude Code's ~/.claude/skills/ directory.

mosaic sync                                                   # Relink the full canonical catalog
~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only (same as default)
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