opencode-muse-agents

# opencode-muse-agents

Run subagents that survive crashes, respect capacity, and return results you can trust. This plugin ports Muse Code's coordination core to OpenCode: every spawn, steer, message, and verdict is a validated ledger record, not a live-session hope.

- Durable children: each worker is a committed record with lineage, worktree, and completion contract; lifecycle runs through 8 control statuses (`src/child.ts: CONTROL_STATUS`).
- Ledger mailbox: messages append first, then admit; delivery uses a closed set of 9 policies (`src/mailbox.ts: DELIVERY_POLICIES`); unknown combos fail closed.
- Admission control: spawns pass resolve, capacity, and depth gates mapped from 12 Agent RPC verbs (`src/verbs.ts: AGENT_VERBS`); rejections are keyed errors, never prose.
- Bounded results: worker envelopes cap summary at 512 chars and text at 32 KiB (`src/envelope.ts: SUMMARY_MAX_CHARS`, `RESULT_TEXT_MAX_BYTES`); over-cap input is rejected, never truncated.

## Install

npm plugin (recommended):

```sh
npm i opencode-muse-agents
```

```json
{ "plugin": ["opencode-muse-agents"] }
```

Copy-install (no npm):

```sh
cp -r bundle/agents bundle/tools bundle/plugins bundle/skills bundle/commands .opencode/
scripts/merge-fragment.sh ./opencode.json
```

`scripts/merge-fragment.sh [TARGET]` deep-merges `bundle/opencode.fragment.json` (agents, `subagent_depth: 2`, skill permissions) into your `opencode.json`, backs up the target first, and is a no-op on re-run. Details in `bundle/README.md`.

## Quickstart (60 seconds)

1. `/spark-plan <goal>` — decompose into worker-sized units with inputs, worktree, budget, and evidence.
2. `/spark-start` — coordinator admits each worker via `spark_submit`, fans out, steers by mailbox notes only.
3. `/spark-review <output>` — reviewer gates every result; integrate only accepted work in your session.

Retry rule: same `commandId` to reconcile, never a new one. Workers never redelegate.

Coordinator loop:

```mermaid
flowchart TD
    Plan["spark-plan decomposes goal"]
    Submit["spark_submit admits spawn"]
    Fanout["task fan-out runs workers"]
    Send["spark_send steers by notes"]
    Worker["spark-worker executes unit"]
    Result["spark_result validates envelope"]
    Review["spark-reviewer gates result"]
    Integrate["integrate accepted work"]
    Plan --> Submit
    Submit --> Fanout
    Fanout --> Worker
    Send --> Worke