# Mosaic Agent Framework

`~/.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: `~/.mosaic/STANDARDS.md`
- Shared operational guides: `~/.mosaic/guides/`
- Shared quality rails/scripts: `~/.mosaic/rails/`
- Runtime adapter docs: `~/.mosaic/adapters/`
- Shared wrapper commands: `~/.mosaic/bin/`
- Canonical skills directory: `~/.mosaic/skills`

## Universal Skills

The installer syncs skills from:

- `https://git.mosaicstack.dev/mosaic/agent-skills`

into:

- `~/.mosaic/skills`

Then links each skill into runtime directories:

- `~/.claude/skills`
- `~/.codex/skills`
- `~/.config/opencode/skills`

Manual commands:

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

## Runtime Compatibility Linking

Installer also links Claude-compatible paths back to Mosaic canonicals:

- `~/.claude/agent-guides` -> `~/.mosaic/guides`
- `~/.claude/scripts/{git,codex,bootstrap}` -> `~/.mosaic/rails/...`
- `~/.claude/templates` -> `~/.mosaic/templates/agent`

Run manually:

```bash
~/.mosaic/bin/mosaic-link-runtime-assets
```

Opt-out during install:

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

## Usage

Inside any compatible repository:

```bash
~/.mosaic/bin/mosaic-session-start
~/.mosaic/bin/mosaic-critical
~/.mosaic/bin/mosaic-session-end
```

Wrapper commands call local repo scripts under `scripts/agent/`.

## Bootstrap Any Repo (Slave Linkage)

Attach any repository/workspace to the master layer:

```bash
~/.mosaic/bin/mosaic-bootstrap-repo /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
~/.mosaic/bin/mosaic-upgrade-slaves
```

Apply upgrades:

```bash
~/.mosaic/bin/mosaic-upgrade-slaves --apply
```