| name | orchestrate |
| description | Use when handed a set/batch of iterations, plans, or work slices to carry out end to end in one run — multiple iteration/story IDs to execute, ordered by blocking edges, each with review, commit, and doc-status transitions, until the whole set is done. lazyspec or any DAG-backed backlog. |
Orchestrating Iterations
Overview
You are handed a batch of plans/work slices (e.g. iterations, deltas) and must drive them all to done in one run. This skill is the orchestration loop: resolve order from the dependency graph, then for each iteration run build → review → commit → advance, retrying review until green, until every unit is complete.
You are the orchestrator, not the implementer. Each iteration's build and each review run in their own subagent. If a work slice is very specific and detailed, you should use a model like sonnet, if it is more vague, consdier opus or fable. You own ordering, status transitions, commits, and the done check.
REQUIRED SUB-SKILLS: lazyspec:execute (the per-iter build loop), lazyspec:advance (status transitions), lazyspec:review (the gate). Build subagents pull testing, refactoring, type-driven-design per the iteration's nature.
Resolve order from edges, not the table
The list you were given is not the execution order. Order comes from the blocks/blocked-by relations on the actual docs.
- Read the real edges:
lazyspec list iteration --json and lazyspec show <ID> and lazyspec context. Do not trust the prompt's table ordering or the iteration numbers.
- Build the DAG and topologically sort. An iteration is eligible iff every iteration it is
blocked-by is already complete.
- Run sequentially in topo order — even when branches are independent. Iterations in a batch usually share files (router, app, store); parallel subagents collide and break "1 commit per iter". Take the cheaper deterministic path.
The per-iteration loop
For each eligible iteration, in topo order:
digraph loop {
rankdir=TB;
"Advance iter -> in progress\n(card -> in progress if apt)" [shape=box];
"Build subagent\nlazyspec:execute, TDD" [shape=box];
"Review subagent\nlazyspec:review vs AC" [shape=box];
"Green?" [shape=diamond];
"Commit (1 per iter)" [shape=box];
"Advance iter -> complete\nAdvance card -> review (if apt)" [shape=box];
"Recompute eligible set" [shape=box];
"Advance iter -> in progress\n(card -> in progress if apt)" -> "Build subagent\nlazyspec:execute, TDD";
"Build subagent\nlazyspec:execute, TDD" -> "Review subagent\nlazyspec:review vs AC";
"Review subagent\nlazyspec:review vs AC" -> "Green?";
"Green?" -> "Build subagent\nlazyspec:execute, TDD" [label="no — re-dispatch with feedback"];
"Green?" -> "Commit (1 per iter)" [label="yes"];
"Commit (1 per iter)" -> "Advance iter -> complete\nAdvance card -> review (if apt)";
"Advance iter -> complete\nAdvance card -> review (if apt)" -> "Recompute eligible set";
}
The review→build edge is the retry loop (often run inside a /goal loop): a failed review re-dispatches the build subagent with the review feedback, then re-reviews. Never commit or advance on a failing review. Only green exits the loop.
Status-transition contract
This is where orchestration goes wrong. Each transition has a specific target — do not collapse them.
| Unit | Start of iter | After green review + commit |
|---|
| Iteration doc | in progress | complete |
| Story / card | in progress (if appropriate) | review (if appropriate), NOT complete |
The card moves to review, not complete — completing a card is a human/downstream decision, and a card may own iterations outside this batch. Advance the card only when all of its in-batch iterations are done and review is its appropriate next status. If a card owns iterations not in this batch, leave it and note it.
Sequencing within the iter: commit first (after green review), then advance the iteration doc to complete, then advance the card to review. Let lazyspec:advance check the type's gates at each transition.
Commits
One commit per iteration, after its review is green — never before, never batched across iterations. Stage only that iteration's changes. If on the default branch, branch first before the first commit.
Done
Done iff every iteration doc in the batch is complete AND every in-batch card has advanced to its appropriate status (review unless noted). Verify with a final lazyspec list --status / lazyspec status and confirm one commit per iteration landed. Report the resolved order, the commits, per-iter review outcomes, and any sandbox blockers you had to stop on.
Common Mistakes
- Advancing cards to
complete. The card target is review. Completion is downstream.
- Ordering by the given table. Order comes from
blocked-by edges read off the docs.
- Committing or advancing on a red review. Retry the build subagent with feedback; only green exits.
- Batched or pre-review commits. One commit per iter, after green.
- Doing the build yourself. Build and review each run in their own subagent; you orchestrate.
- Completing a card whose iterations span batches. Leave it in progress and note it.
