Skip to content

Orchestrate & Workflow

When a plan is ready to build, orchestrate turns it into a kickoff. It reads 05-tracking.md and the ID registry and derives:

  • a work-package matrix (one row per WP-NN with deps, owner, output),
  • freeze gates — each G-<NAME> with the work package that owns it and its sign-off check,
  • a wave plan — a topological sort over deps and gates (gates are sequential; post-gate work packages fan out in parallel),
  • self-contained per-task briefs — a fresh agent can execute one with only its brief.

All of it lands in 09-orchestration.md, the human-readable handoff.

Add --emit-workflow and orchestrate also writes the executable twinartifact/orchestrate.workflow.js, a Claude Code Workflow that runs the build wave by wave:

  • waves → parallel fan-out of one agent per work package,
  • freeze gates → barriers with adversarial sign-off before crossing,
  • per-task Definition of Done → a schema-validated return.

The script returns the reports; it writes nothing to the plan folder. The orchestrating session reconciles afterward — ticking the tracking checkboxes, closing tasks, committing, merging in wave order. That keeps the human in the loop at every gate: a failed gate halts the run and reports back.

Terminal window
groundwork orchestrate --emit-workflow

The dependency graph the board draws is the same one the Workflow executes — 09-orchestration.md stays the readable source of truth, and the .workflow.js is the runnable form of the same data.