mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README with one-liner install, mosaic CLI, and upgrade docs

Browse Source 
- Mac/Linux curl one-liner and Windows PowerShell one-liner at the top
- First-run flow (mosaic init → mosaic claude)
- Architecture diagram showing AGENTS.md as single source of truth
- Injection mechanism table for all runtimes (launcher vs direct)
- All mosaic CLI commands documented
- mosaic upgrade workflow documented
- Removed outdated sections superseded by the mosaic launcher

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
2026-02-19 13:38:23 -06:00
parent 56b644e6d3
commit f577ccd61d
1 changed files with 142 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
README.md
View File

@@ -1,211 +1,193 @@
# Mosaic Agent Framework
`~/.config/mosaic` is the universal userspace standards layer (master) for all agent runtimes.
Universal agent standards layer for Claude Code, Codex, and OpenCode.
## Install Master Layer
One config, every runtime, same standards.
From the standalone source repo:
## 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
```
## What It Provides
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
- Shared standards document: `~/.config/mosaic/STANDARDS.md`
- Shared operational guides: `~/.config/mosaic/guides/`
- Shared quality rails/scripts: `~/.config/mosaic/rails/`
- Shared runtime-neutral presets/profiles: `~/.config/mosaic/profiles/`
- Runtime adapter docs: `~/.config/mosaic/adapters/`
- Runtime overlays: `~/.config/mosaic/runtime/`
- Shared wrapper commands: `~/.config/mosaic/bin/`
- Canonical skills directory: `~/.config/mosaic/skills`
- Local cross-runtime skills: `~/.config/mosaic/skills-local`
## 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:
- `https://git.mosaicstack.dev/mosaic/agent-skills`
into:
- `~/.config/mosaic/skills`
Then links each skill into runtime directories:
- `~/.claude/skills`
- `~/.codex/skills`
- `~/.config/opencode/skills`
Local skills under `~/.config/mosaic/skills-local` are also linked into runtimes.
Manual commands:
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
~/.config/mosaic/bin/mosaic-sync-skills
~/.config/mosaic/bin/mosaic-sync-skills --link-only
mosaic sync # Full sync (clone + link)
~/.config/mosaic/bin/mosaic-sync-skills --link-only # Re-link only
```
## Runtime Compatibility Sync
## Runtime Compatibility
Installer syncs runtime overlays as regular files (not symlinks):
The installer pushes thin runtime adapters as regular files (not symlinks):
- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.config/mosaic/runtime/claude/...`
- `~/.config/opencode/AGENTS.md` <- `~/.config/mosaic/runtime/opencode/AGENTS.md`
- `~/.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`
Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
Run manually:
Re-sync manually:
```bash
~/.config/mosaic/bin/mosaic-link-runtime-assets
~/.config/mosaic/bin/mosaic-migrate-local-skills --apply
```
Prune migrated legacy backups from runtime folders (dry-run by default):
## Bootstrap Any Repo
Attach any repository to the Mosaic standards layer:
```bash
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
mosaic bootstrap /path/to/repo
```
Clean empty legacy runtime directories:
This creates `.mosaic/`, `scripts/agent/`, and an `AGENTS.md` if missing.
```bash
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --apply
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --all-empty --apply
```
## Quality Rails
Audit runtime drift:
```bash
~/.config/mosaic/bin/mosaic-doctor
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn
```
Opt-out during install:
```bash
MOSAIC_SKIP_SKILLS_SYNC=1 bash ~/src/mosaic-bootstrap/install.sh
```
## Usage
Inside any compatible repository:
```bash
~/.config/mosaic/bin/mosaic-session-start
~/.config/mosaic/bin/mosaic-critical
~/.config/mosaic/bin/mosaic-session-end
```
Wrapper commands call local repo scripts under `scripts/agent/`.
## Central Project Control
Manage multiple repos from one place:
```bash
~/.config/mosaic/bin/mosaic-projects init
~/.config/mosaic/bin/mosaic-projects add ~/src/syncagent ~/src/uscllc-website
~/.config/mosaic/bin/mosaic-projects list
~/.config/mosaic/bin/mosaic-projects bootstrap --all
```
Run orchestration across registered repos:
```bash
~/.config/mosaic/bin/mosaic-projects orchestrate drain --all --worker-cmd "codex -p"
~/.config/mosaic/bin/mosaic-projects orchestrate start --all --worker-cmd "opencode -p"
~/.config/mosaic/bin/mosaic-projects orchestrate status --all
```
## Quality Rails (Generalized)
Mosaic includes vendored quality-rails templates and scripts at:
- `~/.config/mosaic/rails/quality/`
Apply to a repo:
Apply and verify quality templates:
```bash
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
```
Verify enforcement:
```bash
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo
```
Templates currently supported:
Templates: `typescript-node`, `typescript-nextjs`, `monorepo`
- `typescript-node`
- `typescript-nextjs`
- `monorepo`
## Matrix Orchestrator Rail
Mosaic includes a runtime-agnostic orchestrator rail at:
- `~/.config/mosaic/rails/orchestrator-matrix/`
Run from a bootstrapped repo:
## Health Audit
```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --once
~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply
~/.config/mosaic/bin/mosaic-orchestrator-drain
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
mosaic doctor # Standard audit
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn # Strict mode
```
The controller reads/writes repo-local state in `.mosaic/orchestrator/` and emits
structured events to `.mosaic/orchestrator/events.ndjson` for Matrix bridge consumption.
## Re-installing / Updating
If your runtime command differs, set:
Pull the latest and re-run the installer:
```bash
export MOSAIC_WORKER_EXEC="codex -p"
# or
export MOSAIC_WORKER_EXEC="opencode -p"
cd ~/src/mosaic-bootstrap && git pull && bash install.sh
```
## Bootstrap Any Repo (Slave Linkage)
Attach any repository/workspace to the master layer:
Or use the one-liner again — it always pulls the latest:
```bash
~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo
```
Attach and apply quality rails in one step:
```bash
~/.config/mosaic/bin/mosaic-bootstrap-repo --quality-template typescript-node /path/to/repo
```
This creates/updates:
- `.mosaic/` (repo-specific hook/config surface)
- `scripts/agent/` (portable lifecycle scripts)
- `AGENTS.md` (if missing)
## Upgrade Existing Slave Repos
Preview upgrades (dry-run):
```bash
~/.config/mosaic/bin/mosaic-upgrade-slaves
```
Apply upgrades:
```bash
~/.config/mosaic/bin/mosaic-upgrade-slaves --apply
curl -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh
```