Jason Woltje
24496cea01
- oc-plugins/mosaic-framework/ — plugin that mechanically injects Mosaic
framework rails into every OpenClaw agent session and ACP worker spawn
- before_agent_start: appendSystemContext (static rules, cached) +
prependContext (dynamic mission state per agent project root)
- subagent_spawning: writes ~/.codex/instructions.md before Codex binary
starts; no mission context (workers detect own CWD mission)
- Optional gate: requireMission blocks ACP spawns with no active mission
Install: mosaic install-oc-plugins --project-root ~/src/<repo>
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# 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
|
|
```
|