# Mosaic Agent Framework

Universal agent standards layer for Claude Code, Codex, and OpenCode.

One config, every runtime, same standards.

> **This repository is a generic framework baseline.** 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 -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh
```

### Windows (PowerShell)

```powershell
irm https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.ps1 | iex
```

### From Source (any platform)

```bash
git clone https://git.mosaicstack.dev/mosaic/bootstrap.git ~/src/mosaic-bootstrap
cd ~/src/mosaic-bootstrap && bash install.sh
```

If Node.js 18+ is available, the remote installer automatically uses the TypeScript wizard instead of the bash installer for a richer setup experience.

The installer will:

- Install the framework to `~/.config/mosaic/`
- Add `~/.config/mosaic/bin` to your PATH
- Sync runtime adapters and skills
- Install and configure sequential-thinking MCP (hard requirement)
- Run a health audit
- Detect existing installs and prompt to keep or overwrite local files
- Prompt you to run `mosaic init` to set up your agent identity

## First Run

After install, open a new terminal (or `source ~/.bashrc`) and run:

```bash
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), configures sequential-thinking MCP, and offers curated skill selection from 8 categories.

### Non-Interactive Mode

For CI or scripted installs:

```bash
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

```bash
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
```

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/E2E-DELIVERY.md ← Mandatory E2E software delivery procedure
├── guides/PRD.md          ← Mandatory PRD requirements gate before coding
├── guides/DOCUMENTATION.md ← Mandatory documentation standard and gates
├── bin/                   ← CLI tools (mosaic, mosaic-init, mosaic-doctor, etc.)
├── dist/                  ← Bundled wizard (mosaic-wizard.mjs)
├── guides/                ← Operational guides
├── tools/                 ← Tool suites: git, portainer, authentik, coolify, codex, etc.
├── runtime/               ← Runtime adapters + runtime-specific references
│   ├── claude/CLAUDE.md
│   ├── claude/RUNTIME.md
│   ├── opencode/AGENTS.md
│   ├── opencode/RUNTIME.md
│   ├── codex/instructions.md
│   ├── codex/RUNTIME.md
│   └── mcp/SEQUENTIAL-THINKING.json
├── skills/                ← Universal skills (synced from mosaic/agent-skills)
├── skills-local/          ← Local cross-runtime skills
└── templates/             ← SOUL.md template, project templates
```

### How AGENTS.md Gets Loaded

| Launch method       | Injection mechanism                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `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             |

Mosaic `AGENTS.md` enforces loading `guides/E2E-DELIVERY.md` before execution and
requires `guides/PRD.md` before coding and `guides/DOCUMENTATION.md` for code/API/auth/infra documentation gates.

## Management Commands

```bash
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 check       # Check release upgrade status (no changes)
mosaic upgrade             # Upgrade installed Mosaic release (keeps SOUL.md by default)
mosaic upgrade --dry-run   # Preview release upgrade without changes
mosaic upgrade --ref main  # Upgrade from a specific branch/tag/commit ref
mosaic upgrade --overwrite # Upgrade release and overwrite local files
mosaic upgrade project ... # Project file cleanup mode (see below)
```

## Upgrading Mosaic Release

Upgrade the installed framework in place:

```bash
# Default (safe): keep local SOUL.md, USER.md, TOOLS.md + memory
mosaic upgrade

# Check current/target release info without changing files
mosaic upgrade check

# Non-interactive
mosaic upgrade --yes

# Pull a specific ref
mosaic upgrade --ref main

# Force full overwrite (fresh install semantics)
mosaic upgrade --overwrite --yes
```

`mosaic upgrade` re-runs the remote installer and passes install mode controls (`keep`/`overwrite`).
This is the manual upgrade path today and is suitable for future app-driven update checks.

## Upgrading Projects

After centralizing AGENTS.md and SOUL.md, existing projects may have stale files:

```bash
# Preview what would change across all projects
mosaic upgrade project --all --dry-run

# Apply to all projects
mosaic upgrade project --all

# Apply to a specific project
mosaic upgrade project ~/src/my-project
```

Backward compatibility is preserved for historical usage:

```bash
mosaic upgrade --all          # still routes to project-upgrade
mosaic upgrade ~/src/my-repo  # still routes to project-upgrade
```

What it does per project:

| File        | Action                                                        |
| ----------- | ------------------------------------------------------------- |
| `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 |

Backups (`.mosaic-bak`) are created before any modification.

## Universal Skills

The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories (`~/.claude/skills`, `~/.codex/skills`, `~/.config/opencode/skills`).

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

## Runtime Compatibility

The installer pushes thin runtime adapters as regular files (not symlinks):

- `~/.claude/CLAUDE.md` — pointer to `~/.config/mosaic/AGENTS.md`
- `~/.claude/settings.json`, `hooks-config.json`, `context7-integration.md`
- `~/.config/opencode/AGENTS.md` — pointer to `~/.config/mosaic/AGENTS.md`
- `~/.codex/instructions.md` — pointer to `~/.config/mosaic/AGENTS.md`
- `~/.claude/settings.json`, `~/.codex/config.toml`, and `~/.config/opencode/config.json` include sequential-thinking MCP config

Re-sync manually:

```bash
~/.config/mosaic/bin/mosaic-link-runtime-assets
```

## MCP Registration

### How MCPs Are Configured in Claude Code

**MCPs must be registered via `claude mcp add` — not by hand-editing `~/.claude/settings.json`.**

`settings.json` controls hooks, model, plugins, and allowed commands. The `mcpServers` key in
`settings.json` is silently ignored by Claude Code's MCP loader. The correct file is `~/.claude.json`,
which is managed by the `claude mcp` CLI.

```bash
# Register a stdio MCP (user scope = all projects, persists across sessions)
claude mcp add --scope user <name> -- npx -y <package>

# Register an HTTP MCP (e.g. OpenBrain)
claude mcp add --scope user --transport http <name> <url> \
  --header "Authorization: Bearer <token>"

# List registered MCPs
claude mcp list
```

**Scope options:**

- `--scope user` — writes to `~/.claude.json`, available in all projects (recommended for shared tools)
- `--scope project` — writes to `.claude/settings.json` in the project root, committed to the repo
- `--scope local` — default, machine-local only, not committed

**Transport for HTTP MCPs must be `http`** — not `sse`. `type: "sse"` is a deprecated protocol
that silently fails to connect against FastMCP streamable HTTP servers.

### sequential-thinking MCP (Hard Requirement)

sequential-thinking MCP is required for Mosaic Stack. The installer registers it automatically.
To verify or re-register manually:

```bash
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
```

### OpenBrain Semantic Memory (Recommended)

OpenBrain is the shared cross-agent memory layer. Register once per machine:

```bash
claude mcp add --scope user --transport http openbrain https://your-openbrain-host/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
```

See [mosaic/openbrain](https://git.mosaicstack.dev/mosaic/openbrain) for setup and API docs.

## Bootstrap Any Repo

Attach any repository to the Mosaic standards layer:

```bash
mosaic bootstrap /path/to/repo
```

This creates `.mosaic/`, `scripts/agent/`, and an `AGENTS.md` if missing.

## Quality Rails

Apply and verify quality templates:

```bash
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo
```

Templates: `typescript-node`, `typescript-nextjs`, `monorepo`

## Health Audit

```bash
mosaic doctor                                          # Standard audit
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn      # Strict mode
```

## Wizard Development

The installation wizard is a TypeScript project in the root of this repo.

```bash
pnpm install              # Install dependencies
pnpm dev                  # Run wizard from source (tsx)
pnpm build                # Bundle to dist/mosaic-wizard.mjs
pnpm test                 # Run tests (30 tests, vitest)
pnpm typecheck            # TypeScript type checking
```

The wizard uses `@clack/prompts` for the interactive TUI and supports `--non-interactive` mode via `HeadlessPrompter` for CI and scripted installs. The bundled output (`dist/mosaic-wizard.mjs`) is committed to the repo so installs work without `node_modules`.

## Re-installing / Updating

Pull the latest and re-run the installer:

```bash
cd ~/src/mosaic-bootstrap && git pull && bash install.sh
```

If an existing install is detected, the installer prompts for:

- `keep` (recommended): preserve local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/`
- `overwrite`: replace everything in `~/.config/mosaic`

Or use the one-liner again — it always pulls the latest:

```bash
curl -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh
```
