Lesson 2 of 7
Running a task through the Orchestrator
The Orchestrator is the entry point for feature-sized work — too broad for one direct coding prompt, or involving design decisions, and you want the framework to keep it structured end to end.
The five (+1) stages
| Stage | Who runs it | Produces |
|---|---|---|
| 1. Planning | Planner | Implementation plan: steps, file assignments, edge cases, risks |
| 2. Designing | Designer (skipped if no UI work) | Component hierarchy, layout, interaction states, accessibility |
| 3. Implementing | Coder | Code changes + build verification |
| 4. Testing | Unit Tester | New/updated tests + pass/fail results |
| 5. Reviewing | Code Reviewer | Severity-rated findings + APPROVED/REQUEST CHANGES |
| 6. Report | Orchestrator itself | Consolidated summary of everything above |
Source: documentation.md, "Stream 1: Working with the Entire SDLC using the Orchestrator".
The key mechanic: stage gates
After each of stages 1–5, the Orchestrator pauses and shows you the output. You choose: approve, ask for changes and re-run that stage, or abort. It never silently marches to the next stage without your say-so.
--yolo and every gate is skipped — the whole pipeline runs unattended, stage 1 to 6.Design (stage 2) only fires if the Planner's output names actual UI work — views, components, templates, styles, routes. Pure backend/logic changes skip straight from Plan to Implement.
Retries are automatic, escalation is manual
If the build fails after Implement, the Coder gets up to two retries before the Orchestrator escalates to you. Same pattern for Test (failing tests bounce back to the Coder, then re-test) and Review (blocking findings bounce back to the Coder, then re-review) — two cycles each before it stops and asks a human.
What good input looks like
The more concrete your starting prompt, the better the plan the pipeline is built on. Include: the feature idea, current vs. desired behaviour, constraints (stack, patterns, deadlines), the files/areas involved, and acceptance criteria.
"I have a task management app with a kanban board. I want to add a right-click context menu on each card that lets users change priority, assign to a team member, and move to a different column. The app uses React and TypeScript, and the board component is in src/components/Board.tsx. Acceptance criteria: the menu appears on right-click, has the three options listed, and each option updates the card state correctly."
Source: documentation.md, example start prompt.
When NOT to use the Orchestrator
- One-line fixes or quick refactors you already know how to do — go to the Coder directly.
- Vague prompts with no clear outcome.
- Pure information questions (it can answer, but it's overkill).
- Work needing only one SDLC stage — call that single agent instead.
Test your knowledge
Your plan involves only a backend rate-limiting change, no UI. What happens to Stage 2 (Design)?
Reference: Agent Selection Cheat Sheet.