diff --git a/README.md b/README.md index 2b0d407..da399c2 100644 --- a/README.md +++ b/README.md @@ -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 # 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 ```