graphyloop-waves

Wave dispatch (contract-first fan-out)

Multi-layer work fails two ways: built serially it takes the sum of its lanes, and fanned out without a frozen contract it produces three incompatible versions of the same table. This skill is the third option.

When to activate

• The request names two or more of: schema/data, API/server, UI/pages, import/export pipeline.
• Words like "system", "app", "platform", "management", "dashboard + data".
• NOT for a one-file change, a rename, or a single endpoint — fan-out only adds integration cost there.

The pipeline

Wave 0  context pack + contract   ONE agent, alone: ctx-<slug>.md, then contract-<slug>.md
Wave 1  builders      data ∥ backend ∥ frontend ∥ tests   (ONE tool-call block)
Wave 2  integration   drop mocks, real calls, env wiring, boot the happy path
Wave 3  verify        test ∥ typecheck/lint ∥ security ∥ performance ∥ review
Wave 4  deploy        preflight → preview → GATED production

Wall clock = Wave 0 + slowest builder + integration + slowest verifier. Never the sum.

Procedure

1. Plan, do not improvise. Call plan_feature / graphyloop_plan_feature with the user's request verbatim as goal. It returns waves, tasks, per-lane owns globs, acceptance checks and dependsOn.
   • shape: no-fanout → stop. This is inline or single-builder work.
2. Context pack, then freeze the contract (Wave 0). One batched read pass (parallel reads/greps) writes .opencode/chadi/ctx-<slug>.md next to the contract: per lane, path:line, the current code excerpt, and the pattern file to copy. Lanes start editing from it instead of rediscovering. Then one agent writes .opencode/chadi/contract-<slug>.md:
   • entities: columns, types, nullability, foreign keys, indexes
   • every route: method, path, request shape, response JSON, error codes
   • components/pages: props and route paths
   • test scenarios that define done (happy path + 2 edge cases per entity)
   • the env keys the feature needs No implementation code in this wave. If the contract is wrong later, stop and fix the contract — never let a lane drift from it silently.
3. Dispatch by dependency, not by optimism. Pass plan.tasks to task_distribute. Dispatch ONLY the ids in dispatchNow. blocked entries name what they are waiting on.
4. Fan out a whole wave in ONE tool-call block. Every prompt carries: the contract and ctx pack paths, that lane's exclusive file list, its acceptance check, and the turn-economy footer verbatim. Builder lanes (wave 1) get: Read the ctx pack and contract first, in ONE turn. Batch 2+ reads/searches into one parallel call; read with line ranges; never re-read a file; first edit by turn 5; do not run project-wide lint/test/build — the driver does. The wave-0 lane that writes the ctx pack and contract gets: Batch 2+ reads/searches into one parallel call; read with line ranges; never re-read a file; write the ctx pack and contract before anything else. Integration, verify and deploy lanes (they run tests and builds) get: Read the ctx pack and contract first, in ONE turn. Batch 2+ reads/searches into one parallel call; read with line ranges; never re-read a file.
5. Record every result. task_record returns what the result unblocked — that is the trigger for the next wave. After a restart or compaction, swarm_state reports readyTasks, blockedTasks and per-wave counts.
6. Integration is one wave, not a habit. Only Wave 2 may touch two lanes at once. Everywhere else, file ownership is exclusive.