task-graph

Task Graph

Turn an approved plan into a persisted DAG executed by parallel squad workers, where done is never a worker's self-report:

plan → task graph → parallel execution → engine-run gate → independent review → done | retry

The @taskgraph engine (deterministic Go code, not an LLM) owns all state. It refuses: dependency cycles, starting a task before its deps are done, and — the core rule — promoting a task to done without its validation gate passing AND a fresh reviewer worker issuing VERDICT: PASS. Executor and reviewer are always distinct workers.

When to use it (and when not)

Use it when the delivery has 5+ tasks with real independence — the parallelism must pay for the orchestration overhead. For 1–4 tasks, or strictly serial work, dispatch <agent_call> workers directly or just do the work yourself.

The plan must already be agreed with the user. Do not invent a graph mid-conversation for work the user asked you to do directly.

The plan schema

<tool_call name="@taskgraph" args='{"cmd":"run","args":{"graph":{
  "name": "feature-x",
  "require_review": true,
  "phases": [{"id":"F1","title":"Server"},{"id":"F2","title":"Client"}],
  "tasks": [
    {"id":"T1","phase":"F1","title":"Add /foo endpoint","agent":"coder",
     "prompt":"Implement GET /foo in server/handler.go returning ...",
     "validation":[{"run":"go test ./server/...","expect":"all tests pass, includes a /foo case"}]},
    {"id":"T2","phase":"F2","title":"CLI client for /foo","deps":["T1"],
     "prompt":"Add the /foo client call. Server contract: #T1",
     "validation":[{"run":"go build ./...","expect":"builds clean"},
                   {"run":"go test ./cli/...","expect":"green"}]}
  ]}}}' />

Rules that matter:

• deps may only reference tasks declared earlier in the list (this also rules out cycles).
• prompt is what the executor worker receives — make it self-contained; workers do not see this conversation. #<depID> in a prompt is replaced with that dependency's output.
• validation[].run commands are executed by the engine (sandboxed, unsafe-command gated) — never by the executor. expect is prose for the reviewer. A bare string instead of the array is allowed (prose-only contract, reviewer verifies by inspection).
• agent defaults to coder; any squad worker type works. max_attempts defaults to 3.
• require_review (graph or per task) defaults to true. Waive it only for trivial mechanical tasks, and say so in the delivery summary.