Files

T

Hermes Agent e3a0ee87b3 framework: make tool discoverability, workspace placement and model tiering mechanical

An undocumented tool is, from inside an agent session, indistinguishable from a
tool that was never written. The framework shipped 26 git wrappers and named 6 of
them in its resident index docs — 23% discoverability, with pr-review.sh among the
missing. The observable consequence was an agent obeying Constitution gate 7 as
best it could see it, reaching for raw curl, sending GitHub's APPROVE to a Gitea
host, and getting HTTP 200 with the review silently filed PENDING. Three times.
That is not a discipline failure and no amount of prose fixes it.

Four changes, each converting a rule that decayed into a mechanism that cannot:

- check-tools-index.sh (new, CI-blocking): every tool in an enforced suite must be
  named in a resident index doc, and every tool an index names must exist. The git
  suite is enforced now; other suites report coverage without failing, so the
  ratchet tightens one reviewed PR at a time instead of landing as one sweep. The
  enforced list is framework-owned rather than a marker inside operator-owned
  TOOLS.md — a doc marker would let an operator silence the gate on exactly the
  host where it matters most. Carries --self-test, because a checker that only
  ever passes is indistinguishable from one that is not running.

- TOOLS-REFERENCE.md: complete 28-entry git index, plus the APPROVED/APPROVE
  dialect note that explains why pr-review.sh is not a formality.

- mosaic-worktree.sh + wrapper-guard.sh (upstreamed): the rule "big work goes on a
  work filesystem" already existed in prose, and 255 GB accumulated in $HOME across
  842 directories anyway, under five simultaneous placement conventions on one
  host. The helper therefore exposes no placement decision — given a branch name,
  every path is derived from `git worktree list --porcelain`. Worktrees rather than
  clones because enumerability is the only thing that makes reclaim safe, and
  reclaim is by evidence (clean tree + no unpushed commits), never by size or age.
  The guard blocks three mechanically-detectable mistakes and nothing else:
  a checkout into $HOME, a raw provider-API write to an endpoint that has a
  wrapper, and the literal APPROVE event. Reads pass untouched.

- STANDARDS.md: model tiering as a standard, named by capability class so it
  survives a model generation. Start cheapest, escalate on evidence, benchmark
  before demoting a task class, and keep the class->model binding in operator
  config with the DB-backed config service as the end state.

Registering the guard in runtime/claude/settings.json is the point of upstreaming
it: ~/.claude/settings.json is a framework-managed copy, so a hand-added hook there
is destroyed by the next upgrade. In the template it survives, and it reaches every
host instead of one.

2026-08-12 16:51:17 -05:00

AGENTS.md

feat(mosaic): P5 — overlay composer (compose-contract + *.local overlays) (#605 )

2026-06-22 02:16:05 +00: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

feat(pi): add persistent Mosaic /goal controller (#1152 )

2026-08-10 22:54:43 +00:00

SOUL.md

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

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

STANDARDS.md

framework: make tool discoverability, workspace placement and model tiering mechanical

2026-08-12 16:51:17 -05:00

TOOLS.md

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

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

USER.md

feat: integrate framework files into monorepo under packages/mosaic/framework/

2026-04-01 21:19:21 -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.)

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
For Pi, loads the framework-owned core and persistent-goal extensions from ~/.config/mosaic/runtime/pi/
Forwards all arguments to the runtime CLI

Inside mosaic pi, /goal set <statement> starts a bounded persistent goal loop. Use /goal status, /goal pause, /goal resume, or /goal cancel to control it. The extension remains part of Mosaic under ~/.config/mosaic/runtime/pi/goal-extension.ts; it is not installed in Pi's main extension directory.

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, goal-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 + Mosaic extensions
`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 --ref v1.0    # Install from a specific git ref

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