# Mosaic Agent Framework

`~/.config/mosaic` is the universal userspace standards layer (master) for all agent runtimes.

## Install Master Layer

From the standalone source repo:

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

## What It Provides

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

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

```bash
~/.config/mosaic/bin/mosaic-sync-skills
~/.config/mosaic/bin/mosaic-sync-skills --link-only
```

## Runtime Compatibility Sync

Installer syncs runtime overlays 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`

Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.

Run 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):

```bash
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
```

Clean empty legacy runtime directories:

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

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:

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

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

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

The controller reads/writes repo-local state in `.mosaic/orchestrator/` and emits
structured events to `.mosaic/orchestrator/events.ndjson` for Matrix bridge consumption.

If your runtime command differs, set:

```bash
export MOSAIC_WORKER_EXEC="codex -p"
# or
export MOSAIC_WORKER_EXEC="opencode -p"
```

## Bootstrap Any Repo (Slave Linkage)

Attach any repository/workspace to the master layer:

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