add opencode runtime adapter and matrix fallback orchestration guidance

README.md

@@ -50,9 +50,10 @@ Manual commands:
 
 ## Runtime Compatibility Sync
 
-Installer syncs Claude runtime overlays as regular files (not symlinks):
+Installer syncs runtime overlays as regular files (not symlinks):
 
 - `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.mosaic/runtime/claude/...`
+- `~/.config/opencode/AGENTS.md` <- `~/.mosaic/runtime/opencode/AGENTS.md`
 
 Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
 

bin/mosaic-doctor

@@ -136,6 +136,9 @@ for rf in CLAUDE.md settings.json hooks-config.json context7-integration.md; do
   check_runtime_file_copy "$MOSAIC_HOME/runtime/claude/$rf" "$HOME/.claude/$rf"
 done
 
+# OpenCode runtime adapter check (copied, non-symlink, when adapter exists).
+check_runtime_file_copy "$MOSAIC_HOME/runtime/opencode/AGENTS.md" "$HOME/.config/opencode/AGENTS.md"
+
 # Legacy migration surfaces should no longer contain symlink trees.
 legacy_paths=(
   "$HOME/.claude/agent-guides"

bin/mosaic-link-runtime-assets

@@ -80,5 +80,11 @@ for runtime_file in \
   copy_file_managed "$src" "$HOME/.claude/$runtime_file"
 done
 
+# OpenCode runtime adapter (optional, copied when present).
+opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md"
+if [[ -f "$opencode_adapter" ]]; then
+  copy_file_managed "$opencode_adapter" "$HOME/.config/opencode/AGENTS.md"
+fi
+
 echo "[mosaic-link] Runtime assets synced (non-symlink mode)"
 echo "[mosaic-link] Canonical source: $MOSAIC_HOME"

guides/orchestrator.md

@@ -27,7 +27,7 @@ The orchestrator **cold-starts** on any project with just a review report locati
 **The orchestrator ONLY:**
 - Reads/writes `docs/tasks.md`
 - Reads/writes `docs/orchestrator-learnings.json`
-- Spawns workers via the Task tool for ALL code changes
+- Delegates ALL code changes to workers (native subagent tool when available, otherwise Mosaic matrix rail)
 - Parses worker JSON results
 - Commits task tracking updates (tasks.md, learnings)
 - Outputs status reports and handoff messages
@@ -40,6 +40,23 @@ Spawn a worker instead. No exceptions. No "quick fixes."
 - Wait for at least one worker to complete before spawning more
 - This optimizes token usage and reduces context pressure
 
+## Delegation Mode Selection
+
+Choose one delegation mode at session start:
+
+1. **Native subagent mode** (preferred when runtime supports it)
+2. **Matrix rail mode** (fallback when native subagents/background tasks are unavailable)
+
+Matrix rail mode commands:
+
+```bash
+~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
+~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+```
+
+In Matrix rail mode, keep `docs/tasks.md` as canonical project tracking and use
+`.mosaic/orchestrator/` for deterministic worker dispatch state.
+
 ---
 
 ## Bootstrap Templates
@@ -251,7 +268,9 @@ git push
    - All done? → Report success, run final retrospective, STOP
    - Some blocked? → Report deadlock, STOP
 5. Update tasks.md: status=in-progress, agent={identifier}, started_at={now}
-6. Spawn worker agent (Task tool) with task details
+6. Delegate worker task:
+   - native mode: spawn worker agent via runtime subagent/task primitive
+   - matrix mode: enqueue/consume task in `.mosaic/orchestrator/tasks.json` and run `mosaic-orchestrator-matrix-cycle`
 7. Wait for worker completion
 8. Parse worker result (JSON)
 9. **Variance check**: Calculate (actual - estimate) / estimate × 100

runtime/opencode/AGENTS.md

@@ -0,0 +1,28 @@
+# Mosaic Runtime Adapter — OpenCode
+
+Load and apply in this order:
+1. `~/.mosaic/STANDARDS.md`
+2. repo-local `AGENTS.md` (and `SOUL.md` when present)
+
+This file is an OpenCode adapter layer. It does not replace project guidance.
+
+## Orchestrator Capability Contract
+
+- OpenCode sessions may not expose a native subagent/background task primitive in all deployments.
+- When native subagent delegation is unavailable, use Mosaic's deterministic orchestrator rail:
+  - `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
+- Keep repo task tracking in `docs/tasks.md` as the canonical human-readable state.
+- Keep machine transport/controller state in `.mosaic/orchestrator/`.
+
+## Fallback Delegation Mode (No Native Subagents)
+
+1. Bootstrap repo if needed:
+   - `~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
+2. Configure `.mosaic/orchestrator/config.json`:
+   - set `"enabled": true`
+   - set `"worker.command_template"` to your OpenCode worker command
+3. Queue work items in `.mosaic/orchestrator/tasks.json` (or via Matrix command ingestion).
+4. Run deterministic ticks:
+   - `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
+
+This preserves rails enforcement (`quality_gates`) even without runtime-native subagent features.