Move old docs into _old_structure dir. Create blank GETTING_STARTED.md document

2026-08-10 14:53:21 -05:00
parent 1655b1579a
commit cd4409abc3
273 changed files with 278 additions and 247 deletions
@@ -0,0 +1,63 @@
+# WP3: plugins/mosaic-framework — OC Rails Injection Plugin
+
+## Context
+
+Port the OpenClaw framework plugin from ~/src/mosaic-stack/oc-plugins/mosaic-framework/ to `plugins/mosaic-framework` in this monorepo. This plugin injects Mosaic framework contracts (rails, completion gates, worktree requirements) into every OpenClaw agent session.
+
+**This is SEPARATE from plugins/macp:**
+
+- `mosaic-framework` = passive enforcement — injects rails into all OC sessions
+- `macp` = active runtime — provides ACP backend for MACP task execution
+
+## Source Files
+
+**Source:** `~/src/mosaic-stack/oc-plugins/mosaic-framework/`
+
+- `index.ts` — plugin hooks (before_agent_start, subagent_spawning)
+- `openclaw.plugin.json` — plugin manifest
+- `package.json`
+
+## What It Does
+
+### For OC native agents (before_agent_start hook):
+
+- Injects Mosaic global hard rules via `appendSystemContext`
+- Completion gates: code review ✓ | security review ✓ | tests GREEN ✓ | CI green ✓
+- Worker completion protocol: open PR → fire system event → EXIT — never merge
+- Worktree requirement: `~/src/{repo}-worktrees/{task-slug}`, never `/tmp`
+- Injects dynamic mission state via `prependContext` (reads from project's `.mosaic/orchestrator/mission.json`)
+
+### For ACP coding workers (subagent_spawning hook):
+
+- Writes `~/.codex/instructions.md` or `~/.claude/CLAUDE.md` BEFORE the process starts
+- Full runtime contract: mandatory load order, hard gates, mode declaration
+- Global framework rules + worktree + completion gate requirements
+
+## Implementation
+
+Port the TypeScript source, updating hardcoded paths to be configurable. The OC plugin SDK imports should reference the installed OpenClaw location dynamically (not hardcoded `/home/jarvis/` paths like the OLD version).
+
+**Structure:**
+
+```
+plugins/mosaic-framework/
+├── src/
+│   └── index.ts
+├── openclaw.plugin.json
+├── package.json
+└── tsconfig.json
+```
+
+## Key Constraint
+
+The plugin SDK imports in the OLD version use absolute paths:
+
+```typescript
+import type { OpenClawPluginApi } from '/home/jarvis/.npm-global/lib/node_modules/openclaw/dist/plugin-sdk/index.js';
+```
+
+This must be resolved dynamically or via a peer dependency. Check how `plugins/macp` handles this in the new repo and follow the same pattern.
+
+## Tests
+
+Minimal — plugin hooks are integration-tested against OC runtime. Unit test the context string builders and config resolution.