bootstrap/oc-plugins/mosaic-framework/README.md

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)

mosaic install-oc-plugins

Manual

# 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:

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