bootstrap/README.md

# Mosaic Agent Framework

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

One config, every runtime, same standards.

## 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
bash ~/src/mosaic-bootstrap/install.sh
```

The installer will:
- Install the framework to `~/.config/mosaic/`
- Add `~/.config/mosaic/bin` to your PATH
- Sync runtime adapters and skills
- Run a health audit
- 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
```

This generates `~/.config/mosaic/SOUL.md` — your agent identity contract. It's loaded into every session regardless of runtime.

## 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                ← User identity (generated by mosaic init)
├── STANDARDS.md           ← Machine-wide standards
├── bin/                   ← CLI tools (mosaic, mosaic-init, mosaic-doctor, etc.)
├── guides/                ← Operational guides
├── rails/                 ← Quality rails, git scripts, portainer scripts
├── runtime/               ← Thin runtime adapters (fallback for direct launches)
│   ├── claude/CLAUDE.md
│   ├── opencode/AGENTS.md
│   └── codex/instructions.md
├── 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 AGENTS.md content |
| `mosaic codex` | Copies AGENTS.md to `~/.codex/instructions.md` before launch |
| `mosaic opencode` | Copies AGENTS.md to `~/.config/opencode/AGENTS.md` before launch |
| `claude` (direct) | `~/.claude/CLAUDE.md` thin pointer → "READ AGENTS.md" |
| `codex` (direct) | `~/.codex/instructions.md` thin pointer → "READ AGENTS.md" |
| `opencode` (direct) | `~/.config/opencode/AGENTS.md` thin pointer → "READ AGENTS.md" |

## Management Commands

```bash
mosaic help                # Show all commands
mosaic init                # Generate SOUL.md (agent identity)
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 [path]      # Clean up stale per-project files (see below)
mosaic upgrade --all       # Upgrade all projects in ~/src
mosaic upgrade --dry-run   # Preview without changes
```

## 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 --all --dry-run

# Apply to all projects
mosaic upgrade --all

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

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`

Re-sync manually:

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

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

## Re-installing / Updating

Pull the latest and re-run the installer:

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

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