Lesson 3 of 7 · Individual agent
The Planner agent
In software development we're often making architectural decisions and want to figure out how something can be done before implementing anything. Those structural decisions are exactly what the Planner helps with. The Planner understands the current code and gives structured ways of how something can be done, including edge cases, risks, open questions, and how the implementation can be validated. The Planner never writes code — the Planner only describes what needs to happen.
When to use the Planner
- Researching the codebase and discovering existing project standards before proposing anything.
- Identifying the exact affected files and symbols — and verifying those paths and names are real.
- Breaking a fuzzy requirement into ordered, atomic implementation steps (one action per file per step).
- Surfacing edge cases, boundary conditions, risks, and open questions you hadn't thought of.
- Evaluating multiple approaches to a refactor or migration before anyone commits to one.
How to use the Planner
- Describe the concrete requirement or task — not just "make it better".
- Name the files or areas of the codebase you think are involved.
- State constraints: technology, existing patterns, backward compatibility.
- Describe what the end result should look like, and list any open questions.
- Review the plan the Planner returns — the plan should include a summary, standards discovered, verified files/symbols, ordered steps, edge cases, risks, and a validation strategy.
"I need to add role-based access control to our Express API. Currently all routes are open. I want admin, editor, and viewer roles. The routes are in src/routes/ and the auth middleware is in src/middleware/auth.ts. How should I approach this? What are the edge cases?"
Where the Planner fits in the Orchestrator: the Planner runs as Stage 1. The Orchestrator verifies the Planner's plan (checking file paths and symbols are real) before presenting the plan for your approval and passing the plan downstream to the Designer and Coder.
Things to avoid
- Using the Planner when you already know exactly what to change — go to the Coder instead.
- Vague prompts with no actionable requirement, like "make the app better".
- Asking the Planner to write code — the Planner will refuse and only describe what should be done.
Test your knowledge
You want to evaluate three different ways to migrate a monolith to microservices before writing anything. Which agent?
Source: documentation.md, "Planner".