# mosaic-framework — OpenClaw Plugin

Mechanically injects the Mosaic framework contract into every OpenClaw agent session and ACP coding worker spawn. Ensures no worker starts without the mandatory load order, hard gates, worktree rules, and completion gates.

## What It Does

### For OC native agents (main, mosaic, dyor, sage, pixels)
Hooks `before_agent_start` and injects via `appendSystemContext`:
- Mosaic global hard rules (compaction-resistant)
- Completion gates (code review ✓ | security review ✓ | tests GREEN ✓ | CI green ✓ | issue closed ✓ | docs updated ✓)
- Worker completion protocol (open PR → fire system event → EXIT — never merge)
- Worktree requirement (`~/src/<repo>-worktrees/<task-slug>`, never `/tmp`)

Also injects dynamic mission state via `prependContext` (re-read each turn from the agent's configured project root).

### For ACP coding workers (Codex, Claude Code)
Hooks `subagent_spawning` and writes `~/.codex/instructions.md` (or `~/.claude/CLAUDE.md`) **before the process starts**:
- Full runtime contract (mandatory load order, hard gates, mode declaration requirement)
- Global framework rules
- Worktree and completion gate requirements
- Worker reads its own `.mosaic/orchestrator/mission.json` from CWD — no cross-project contamination

## Installation

### Automatic (via mosaic install script)
```bash
mosaic install-oc-plugins
```

### Manual
```bash
# 1. Copy plugin to extensions directory (already done if cloned from mosaic-bootstrap)
cp -r ~/.config/mosaic/oc-plugins/mosaic-framework ~/.openclaw/extensions/

# 2. Register in OpenClaw config
openclaw config patch '{
  "plugins": {
    "allow": [...existing..., "mosaic-framework"],
    "load": { "paths": [...existing..., "~/.openclaw/extensions/mosaic-framework"] },
    "entries": {
      "mosaic-framework": {
        "enabled": true,
        "config": {
          "mosaicHome": "~/.config/mosaic",
          "projectRoots": ["~/src/<your-project>"],
          "requireMission": false,
          "acpAgentIds": ["codex", "claude"]
        }
      }
    }
  }
}'

# 3. Restart gateway
openclaw gateway restart
```

## Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `mosaicHome` | string | `~/.config/mosaic` | Path to Mosaic config home |
| `projectRoots` | string[] | `[]` | Project directories to scan for active missions (used in `before_agent_start` for native agents) |
| `requireMission` | boolean | `false` | If `true`, blocks ACP coding worker spawns when no active mission exists in any project root |
| `injectAgentIds` | string[] | all agents | Limit `before_agent_start` injection to specific agent IDs |
| `acpAgentIds` | string[] | `["codex", "claude"]` | ACP agent IDs that trigger runtime contract injection on spawn |

## Adding a New Project

When starting work on a new project, add its root to `projectRoots` in the plugin config:

```bash
openclaw config patch '{
  "plugins": {
    "entries": {
      "mosaic-framework": {
        "config": {
          "projectRoots": ["~/src/mosaic-stack", "~/src/sage-phr-ng", "~/src/new-project"]
        }
      }
    }
  }
}'
openclaw gateway restart
```

## Packaging

This plugin lives at `~/.config/mosaic/oc-plugins/mosaic-framework/` in the mosaic-bootstrap distribution. The `mosaic install-oc-plugins` command symlinks it into `~/.openclaw/extensions/` and registers it in `openclaw.json`.

## Architecture Notes

- `appendSystemContext` is cached by Anthropic's API (cheaper than per-turn injection) — used for static framework rules
- `prependContext` is fresh per-turn — used for dynamic mission state
- `subagent_spawning` fires synchronously before the external process starts — `~/.codex/instructions.md` is written before the Codex binary reads it
- Mission context is NOT injected in `subagent_spawning` — workers detect their own CWD mission (avoids cross-project contamination when multiple missions are active simultaneously)

## Files

```
mosaic-framework/
├── index.ts              # Plugin implementation
├── openclaw.plugin.json  # Plugin manifest
├── package.json          # Node package metadata
└── README.md             # This file
```