Planner → Worker hierarchy

The planner-worker hierarchy is a specific multi-agent architecture pattern where responsibility is divided between two tiers. The planner agent operates at the task level: it receives a high-level engineering goal, analyzes the codebase, decomposes the goal into concrete subtasks with clear acceptance criteria, and assigns those subtasks to worker agents. Worker agents operate at the implementation level: they receive a specific, bounded subtask and execute it - writing code, running tests, fixing failures - until the subtask is complete or definitively fails.

The planner maintains overall context and coordinates: it tracks which subtasks are complete, detects when a worker needs additional information, recognizes when the original decomposition needs revision (because a subtask revealed unexpected complexity), and synthesizes the workers' outputs into a coherent whole. Workers are stateless and focused: they know only their subtask and the context the planner provides.

This architecture is "canonical" at L5 because it mirrors how effective engineering teams work: a tech lead (planner) breaks down a project and assigns pieces to developers (workers), maintains visibility into progress, unblocks problems, and integrates the final result. The planner-worker hierarchy is this pattern implemented in software, with agents in both roles.

The planner can run a more capable, larger model (e.g., Claude Opus) while workers run faster, cheaper models (e.g., Claude Haiku or Sonnet), since planning requires deep reasoning while execution requires speed. This cost optimization is a practical advantage of the two-tier architecture over a flat multi-agent system where all agents run the same model.

The planner-worker separation solves the fundamental tension in autonomous agent systems between depth and breadth:

• Depth vs. breadth - a single agent trying to implement a complex feature either goes deep (loses track of the overall goal) or stays broad (produces superficial implementations); the two-tier system assigns depth to workers and breadth to the planner
• Context management - the planner maintains the full task context; workers receive only what they need; this prevents context window overload while preserving task coherence
• Parallelism with coordination - workers execute in parallel while the planner coordinates; this delivers parallelism benefits without the consistency problems of uncoordinated parallel execution
• Graceful failure handling - when a worker fails, the planner can replan - decompose the failed subtask differently, provide additional context, or route to a different worker; the system recovers without human intervention for common failure modes
• Cost optimization - using different models at different tiers matches computational cost to task complexity; planning is expensive (uses the most capable model); routine implementation is cheaper (uses a faster model)

1. Define the planner's interface - The planner receives: a task description, codebase context (CLAUDE.md, architecture docs, relevant file summaries), and available tools (what workers can do). It produces: an ordered list of subtasks, each with a description, assigned agent type, required context, and success criteria. Start with this interface before implementing either tier.
2. Build the planner first, with static workers - Implement the planner agent and test it by having it decompose 10 representative tasks from your backlog. Evaluate the decompositions manually: are the subtasks the right size? Do they cover all aspects of the goal? Are the success criteria verifiable? Fix the planner before adding workers.
3. Implement a single worker type - Your first worker should be a general-purpose implementation worker: receives a subtask spec, writes the code, runs the tests, returns the result. A single Claude Code instance with your project's CLAUDE.md is a solid starting point.
4. Add the coordination loop - The planner needs to track worker states: pending, running, completed, failed. Implement a simple state machine. When a worker completes, the planner updates its task graph and dispatches the next available subtask. When a worker fails, the planner either retries or replans.
5. Instrument everything - Log every planner decision (why it decomposed a task this way), every worker invocation, every result, every failure, and every retry. This telemetry is how you'll debug coordination problems and improve the system over time.
6. Validate the end-to-end pipeline before scaling - Run the complete system on one specific task type (e.g., "implement a REST CRUD endpoint with tests") and validate it end-to-end. Measure: decomposition quality, worker success rate, full pipeline success rate, total time. Only scale worker count after the single-worker pipeline reliably succeeds.

Overloading the planner with execution details. The planner should reason about what needs to be done, not how to do it. If the planner's prompts contain implementation details (specific function signatures, exact test patterns), it starts doing worker-level thinking, which consumes context window space and degrades planning quality. Keep the planner at the "what" level; workers handle the "how."

Giving workers too much context. Workers perform best with focused context: the subtask specification, the relevant code files, and the project conventions. Passing the entire planner context to each worker dilutes the signal with irrelevant information. Implement a context filtering step in the planner-to-worker handoff: send only what the worker needs for this specific subtask.

No mechanism for worker-to-planner feedback. Workers encounter information the planner didn't have: unexpected dependencies, ambiguous requirements, conflicting conventions. Without a feedback channel, workers either make assumptions (introducing errors) or fail (requiring human intervention). Implement a structured feedback mechanism: workers can send "clarification needed" signals back to the planner with specific questions, and the planner can update the task context and re-dispatch.

Treating the hierarchy as immutable. The initial task decomposition is a hypothesis, not a plan. When worker results reveal that the decomposition was wrong (the subtasks don't add up to the goal, or there are dependencies the planner didn't see), the planner must be able to revise. A planner that can't replan is brittle; a planner that can revise its decomposition in response to worker feedback is robust.