193 lines
4.7 KiB
Markdown
193 lines
4.7 KiB
Markdown
# 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/`.
|
|
|
|
## 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
|
|
```
|