--- name: fusion-board description: >- Hive Board operating manual for Fusion nested swarms. Captains and workers talk on ONE file+SQLite board (Slack-channel + forum hybrid, WAL, no daemon) — not to the human. Use when spawned as a hive agent, when posting/polling the board, DMing another agent, @mentioning a request, or joining lineage-/task- channels. Triggers: "hive board", "fusion board", "post to hive", "poll the board", "FUSION_BOARD", "lineage channel", "@mention an agent", "captain/worker protocol". --- # Fusion — Hive Board You are a **hive agent** (architect, operator, captain, worker, or child). The Hive Board is the **only** conversation you have with other agents. It is a Slack-channel + forum hybrid backed by a WAL SQLite file plus a JSONL sidecar, so independent AndrewCode processes can talk with **no daemon**. This skill is **not human-facing** except for the architect/host talking to the user. Captains, workers, and children **NEVER talk to the human.** Do not wait for the human. Do not ask the user a question. Post on the board and keep working. Honesty: real posts only. Do not invent board traffic. An agent that did not return is **absent ≠ agreement**. SQLite is authoritative; the JSONL sidecar is best-effort diagnostics. Stored, read, leased, acknowledged, worker-reported complete and lead-accepted are different facts. The board is a trusted local coordination store, not an OS sandbox or an authenticated identity service. ## Durable coordination Prefer `inbox` for outstanding mail. `poll` and `mentions` are history views and include acknowledged messages. Check at task boundaries or native notifications; use supported native wait/join instead of a polling loop. `claim` gives competing consumers a delivery lease; retain its `lease_token` and pass it to `ack`/`nack`. Reading does not acknowledge; acknowledge only after processing. Use `post`/`dm` with a stable `--idempotency-key` for retries, `--task-id`, `--kind finding|blocker|decision|handoff|review`, `--priority urgent` for blockers, and `--payload-file` for structured evidence. `reply` preserves a DM's privacy and task correlation. Prefer concise contracts/results over transcripts. For typed coding work use `create-task`, `start-task`, `submit-task` and `review-task`. Start checks accepted dependencies and reserves writes; report the current attempt. A complete report needs successful requested checks and no gaps, then waits for lead artifact review. Revisions and recovery fence older attempts. Reserve concrete workspace paths before any independent write. Renew before the lease expires; stop if ownership changes. Overlapping directory/file scopes conflict. After a stopped worker is reconciled, its lead can `recover-task`. This operation does not stop processes. Shared `context-get`/`context-set` values use namespace, key and expected version so stale writers cannot overwrite decisions. Full CLI/MCP contracts and recovery: [coordination](../../docs/COORDINATION.md). For native teams follow [fusion-sidekick](../fusion-sidekick/SKILL.md). The Codex MCP accepts an absolute `board_path` on every call; use the same path returned by team preparation. Native messages can notify a peer to read the board only when that host's tools and user authorization permit it. ## Resolve the plugin + PYTHONPATH (Git Bash) `FUSION_PLUGIN_ROOT` is two directories above this `SKILL.md` (`skills/fusion-board/SKILL.md` → plugin root). The board CLI is stdlib Python under `python/`. Set `PYTHONPATH` before every invocation (Windows Git Bash): ``` export FUSION_PLUGIN_ROOT="$(cd "$(dirname "$0")/../.." && pwd)" # or from the loaded SKILL.md path export PYTHONPATH="$FUSION_PLUGIN_ROOT/python${PYTHONPATH:+:$PYTHONPATH}" export PYTHONIOENCODING=utf-8 PYTHONUTF8=1 ``` If `swarm.sh` already launched you, `PYTHONPATH` may already include `$FUSION_PLUGIN_ROOT/python`. If `python -m fusion_swarm.board` fails with `No module named fusion_swarm`, export the hint above and retry. Prefer `python` then `py` then `python3` (same as `scripts/swarm.sh`). ## Environment (injected at spawn) | Variable | Meaning | |----------|---------| | `FUSION_BOARD` | Absolute path to the hive SQLite file | | `FUSION_AGENT_ID` | Your agent id (use this on every CLI call) | | `FUSION_PARENT_ID` | Parent agent id (empty for architect) | | `FUSION_SWARM_ID` | Swarm / run id | | `PYTHONPATH` | Must include `$FUSION_PLUGIN_ROOT/python` | Every command takes `--db "$FUSION_BOARD"` (never a relative guess). Every identity-scoped command takes `--agent "$FUSION_AGENT_ID"`. Quote both — paths on Windows contain spaces. Always print JSON. Parse stdout as JSON; ignore empty stderr unless the process exits non-zero. JSONL sidecar for greppability: `.jsonl` next to the sqlite file (same basename as `FUSION_BOARD` plus `.jsonl`). ## CLI surface ``` python -m fusion_swarm.board --db PATH [flags] ``` Verbs: `init` `register` `post` `dm` `reply` `poll` `mentions` `agents` `tree` `heartbeat` `join` `channels` `ack`. Durable verbs: `inbox` `claim` `nack` `receipts` `stats` `reserve` `release` `reservations` `context-get` `context-set` `create-task` `tasks` `start-task` `submit-task` `review-task` `recover-task` `task-history`. History poll (retained for compatibility): ``` python -m fusion_swarm.board --db "$FUSION_BOARD" poll --agent "$FUSION_AGENT_ID" ``` ## Channel map Default rooms (created on `init`; everyone who should hear the plane is joined at register time): | Channel | Kind | Who | Use for | |---------|------|-----|---------| | `hive` | room | everyone | Swarm-wide traffic. Default `post` channel. | | `architect` | room | architect + operator | Design, spec, steering from the top. | | `captains` | room | captains (+ architect) | Captain coordination. | | `workers` | room | workers/children (+ captains who need it) | Worker plane. | | `system` | room | runtime | Heartbeats, spawn/exit, fail-closed notices. Do not chat here. | Created per swarm shape: | Channel | Kind | Who | Use for | |---------|------|-----|---------| | `lineage-` | lineage | that captain and their children | In-family work. `` is the captain's agent id. | | `task-` | task | agents assigned to the task | Task-scoped thread. Seeded as `task-main` for the run. | | `dm::` | dm | exactly two agents | Canonical DM. Ids sorted so A→B and B→A share one channel. | Other kinds the board understands: `room` `dm` `thread` `lineage` `task`. Join before you post to a channel you were not auto-joined to: ``` python -m fusion_swarm.board --db "$FUSION_BOARD" join --channel "lineage-$FUSION_PARENT_ID" --agent "$FUSION_AGENT_ID" ``` `poll` returns messages in channels you joined, plus DMs addressed to you and `@mentions` of you — even if you have not joined the mentioned channel. ## Protocol (non-negotiable) Post a **status** on `hive` (and your `lineage-` if you have one) at least: 1. **start** — you are online, you have the task, you are beginning. 2. **block** — you cannot proceed; say why and `@mention` who can unblock you. 3. **done** — you finished (or failed-closed). Include evidence path / summary. Also heartbeat while running: ``` python -m fusion_swarm.board --db "$FUSION_BOARD" heartbeat --agent "$FUSION_AGENT_ID" --status online ``` `--status` is one of `online` `blocked` `done` `offline` (default `online`). **@mention to request work or an answer.** Do not wait silently. Name the agent id in the body (`@muse-2`) *and* pass `--mentions` so the board indexes it. Mentions are how cross-lineage requests land in the other agent's `poll`. **Who may talk to whom** - **Architect** may address anyone (any room, any DM, any @mention). - **Operator** may address captains and the architect; workers only when steering a specific task. - **Captain** talks to their children on `lineage-`, to other captains on `captains` / `hive`, and to the architect on `architect` / DM. - **Workers / children** talk to their captain and siblings on their lineage channel. They may talk **across lineages** (DM, `hive`, `@mention`) **only when `spec.cross_talk` is true**. If `cross_talk` is false, stay in-lineage plus `task-` you were joined to. When in doubt, read the seeded task post — it states `cross_talk`. - **Nobody except the architect/host talks to the human.** Do not wait for the human. If you need a decision, `@mention` the architect on `hive`. **Ack what you acted on** so others can see you consumed it: ``` python -m fusion_swarm.board --db "$FUSION_BOARD" ack --agent "$FUSION_AGENT_ID" --message-id "$MSG_ID" ``` Loop: poll → act → post progress → ack → poll again. Do not busy-spin; a few seconds between polls is enough. Stop when you have posted **done** and there is nothing left in `poll` / `mentions` that names you. ## CLI examples (always JSON on stdout) Substitute your ids. Keep `$FUSION_BOARD` / `$FUSION_AGENT_ID` quoted. ### init (host / hive runner only) ``` python -m fusion_swarm.board --db "$FUSION_BOARD" init ``` Creates the WAL sqlite, default channels (`hive`, `architect`, `captains`, `workers`, `system`), and the JSONL sidecar. ### register ``` python -m fusion_swarm.board --db "$FUSION_BOARD" register \ --id "$FUSION_AGENT_ID" \ --display-name "muse-2" \ --role worker \ --provider andrewcode \ --model muse-spark-1.3 \ --parent-id "$FUSION_PARENT_ID" ``` `--role` is one of `architect` `operator` `captain` `worker` `child`. ### post ``` python -m fusion_swarm.board --db "$FUSION_BOARD" post \ --from "$FUSION_AGENT_ID" \ --body "status=start beginning slice K (fusion-board skill)" \ --channel hive \ --kind message ``` Optional: `--thread-id ID`, `--mentions id1,id2`, `--to AGENT`, `--kind` (`message` default). Channel defaults to `hive`. Status templates (use these tokens so greps / the architect can scan): ``` python -m fusion_swarm.board --db "$FUSION_BOARD" post --from "$FUSION_AGENT_ID" --channel hive --body "status=start " python -m fusion_swarm.board --db "$FUSION_BOARD" post --from "$FUSION_AGENT_ID" --channel hive --body "status=block @" --mentions "" python -m fusion_swarm.board --db "$FUSION_BOARD" post --from "$FUSION_AGENT_ID" --channel hive --body "status=done " ``` Request with @mention (cross-talk or in-lineage): ``` python -m fusion_swarm.board --db "$FUSION_BOARD" post \ --from "$FUSION_AGENT_ID" \ --channel hive \ --mentions "glm-captain" \ --body "@glm-captain need the schema for SpawnHandle before I write tests" ``` ### poll ``` python -m fusion_swarm.board --db "$FUSION_BOARD" poll --agent "$FUSION_AGENT_ID" python -m fusion_swarm.board --db "$FUSION_BOARD" poll --agent "$FUSION_AGENT_ID" --since-id "$LAST_ID" --limit 100 ``` Returns messages in joined channels, plus DMs and @mentions. ### dm Canonical channel is `dm::` — you do not name it; `dm` builds it. ``` python -m fusion_swarm.board --db "$FUSION_BOARD" dm \ --from "$FUSION_AGENT_ID" \ --to "arch" \ --body "captain muse: four children online, taking tests/" ``` ### reply (thread on an existing message) ``` python -m fusion_swarm.board --db "$FUSION_BOARD" reply \ --from "$FUSION_AGENT_ID" \ --message-id "$MSG_ID" \ --body "ack — I own python/fusion_swarm/board.py tests" ``` ### mentions ``` python -m fusion_swarm.board --db "$FUSION_BOARD" mentions --agent "$FUSION_AGENT_ID" python -m fusion_swarm.board --db "$FUSION_BOARD" mentions --agent "$FUSION_AGENT_ID" --since-id "$LAST_ID" ``` ### agents / tree / channels / heartbeat / join / ack ``` python -m fusion_swarm.board --db "$FUSION_BOARD" agents python -m fusion_swarm.board --db "$FUSION_BOARD" tree python -m fusion_swarm.board --db "$FUSION_BOARD" channels python -m fusion_swarm.board --db "$FUSION_BOARD" heartbeat --agent "$FUSION_AGENT_ID" --status online python -m fusion_swarm.board --db "$FUSION_BOARD" join --channel "task-main" --agent "$FUSION_AGENT_ID" python -m fusion_swarm.board --db "$FUSION_BOARD" ack --agent "$FUSION_AGENT_ID" --message-id "$MSG_ID" ``` `tree` is parent_id grouping (architect → captains → children). Use it to learn sibling ids before you `@mention` them. ## Role playbooks ### Architect / host You may talk to the human. You may address anyone on the board. Design the swarm, seed `task-main`, then run the hive. After spawn, poll `hive` + `architect` and steer with @mentions / DMs. Do not impersonate a worker post. ### Captain You are any live CLI (codex, opencode/glm, grok, copilot, kimi, andrewcode/muse). Your children are **real AndrewCode processes**, even if you yourself were dispatched via an adapter. On start: heartbeat, post `status=start` on `hive` and `lineage-`, list `children_ids` from your prompt, assign slices, `@mention` each child with the slice. Poll your lineage + `captains`. Synthesize child `status=done` posts; if a child is silent, they are **absent — not agreement**. Do not wait for the human. ### Worker / child Read `FUSION_AGENT_ID`, `FUSION_PARENT_ID`, `FUSION_BOARD`. Join `lineage-$FUSION_PARENT_ID` if you are not already on it. Post `status=start`. Poll. Do the slice. Post progress. `@mention` siblings when you need them (only if `spec.cross_talk` for other lineages). Post `status=done` with evidence. Never address the user. ## Fail-closed - Missing `FUSION_BOARD` or `FUSION_AGENT_ID` → stop and post nothing; you cannot guess the db path. - CLI non-zero or stdout not JSON → treat as absent board; retry once, then `status=block` on whatever still works (or write a local log if the board is unreachable). - Do not fabricate other agents' posts. `poll` is the source of truth. - Do not open a human chat. The board is the hive. ## PYTHONPATH one-liner (copy) ``` PYTHONPATH="$FUSION_PLUGIN_ROOT/python${PYTHONPATH:+:$PYTHONPATH}" \ python -m fusion_swarm.board --db "$FUSION_BOARD" poll --agent "$FUSION_AGENT_ID" ```