From e16ff8af70b2f7cbecfd9647ae6b31011703c9ab Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 17 Feb 2026 14:05:39 -0600 Subject: [PATCH] add opencode runtime adapter and matrix fallback orchestration guidance --- README.md | 3 ++- bin/mosaic-doctor | 3 +++ bin/mosaic-link-runtime-assets | 6 ++++++ guides/orchestrator.md | 23 +++++++++++++++++++++-- runtime/opencode/AGENTS.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 60 insertions(+), 3 deletions(-) create mode 100644 runtime/opencode/AGENTS.md diff --git a/README.md b/README.md index f1e1972..a55c0cd 100644 --- a/README.md +++ b/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. diff --git a/bin/mosaic-doctor b/bin/mosaic-doctor index 06018c4..734a746 100755 --- a/bin/mosaic-doctor +++ b/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" diff --git a/bin/mosaic-link-runtime-assets b/bin/mosaic-link-runtime-assets index 61d1e8c..09cd418 100755 --- a/bin/mosaic-link-runtime-assets +++ b/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" diff --git a/guides/orchestrator.md b/guides/orchestrator.md index ddaa557..5b74e4c 100644 --- a/guides/orchestrator.md +++ b/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 diff --git a/runtime/opencode/AGENTS.md b/runtime/opencode/AGENTS.md new file mode 100644 index 0000000..dfcef4e --- /dev/null +++ b/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.