Mosaic Agent Framework

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

Install Master Layer

From the standalone source repo:

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:

~/.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:

~/.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):

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

Clean empty legacy runtime directories:

~/.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:

~/.config/mosaic/bin/mosaic-doctor
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn

Opt-out during install:

MOSAIC_SKIP_SKILLS_SYNC=1 bash ~/src/mosaic-bootstrap/install.sh

Usage

Inside any compatible repository:

~/.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:

~/.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:

~/.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:

~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo

Verify enforcement:

~/.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:

~/.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:

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:

~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo

Attach and apply quality rails in one step:

~/.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):

~/.config/mosaic/bin/mosaic-upgrade-slaves

Apply upgrades:

~/.config/mosaic/bin/mosaic-upgrade-slaves --apply