developmentL5 AutonomousCoding Agent Usage

Planner → Worker hierarchy

How to structure a two-tier agent architecture where a planner decomposes engineering tasks and workers execute them in parallel - the canonical L5 pattern for complex autonomous development.

·Multi-agent orchestration system (planner-worker hierarchy) is in production
·Agent fleet sustains 100+ concurrent agents on the codebase
·Agent fleet produces 1,000+ commits per week without manual dispatch

·Planner agents decompose epics into tasks and assign to worker agents autonomously
·Agent fleet self-recovers from failures without human escalation for 90%+ of error cases

Evidence

·Orchestration system dashboard showing planner-worker task flow
·Git history showing 1,000+ weekly commits attributed to agent fleet
·Agent fleet monitoring showing concurrent agent count and error recovery rate

What It Is

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.

Why It Matters

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)

Tip

The quality of the planner's task decomposition is the primary determinant of the system's output quality. Before optimizing workers, optimize the planner. A planner that consistently decomposes tasks into the right subtask granularity (small enough to be unambiguous, large enough to be meaningful) produces dramatically better results than a planner that produces either too-fine or too-coarse subtasks.

Getting Started

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.
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.
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.
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.
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.
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.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has successfully deployed unattended agents at L4 and wants to tackle the next level of complexity - tasks that are too large or complex for a single agent but genuinely high-value. He's been told the planner-worker architecture is the answer but isn't sure what it would look like in his codebase.

What Bob should do: Bob should start with the simplest possible application: a two-agent system for one specific task type. A good first candidate is "implement a feature from a detailed spec." The planner receives the spec and produces a list of implementation subtasks. One worker executes them sequentially (not in parallel yet - add parallelism once the sequential pipeline works). Bob should frame this as a 4-week engineering project with specific success criteria: 5 feature implementations completed end-to-end with quality equivalent to L4 parallel agent output. The goal is not a general orchestration system - it's one task type working reliably. General capability comes later.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah wants to build the business case for the L5 investment. The planner-worker system is complex to build, and she needs to demonstrate that the capability it enables is worth the engineering cost.

What Sarah should do: Sarah's business case should focus on task categories, not system architecture. Identify the top 5 task types that consume the most senior engineer time but could be handled by a planner-worker system (complex feature implementations from specs, large-scale refactors, dependency migrations). Estimate the current cost per task type (engineering hours × fully-loaded rate). The planner-worker system target: reduce that cost by 70-80% for suitable task types, since the engineer's role shifts from implementation to task specification and PR review. The ROI calculation is straightforward: if the system handles 20 tasks per month that previously required 4 hours of senior engineer time each, that's 80 engineer-hours per month recovered. At any reasonable hourly rate, the system pays for itself within its first quarter of operation.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been manually running the planner-worker pattern for months: he decomposes complex tasks into subtasks, assigns them to Claude Code instances in separate worktrees, monitors progress, and synthesizes the results. He knows this manual process is valuable but also knows he's the bottleneck - only one person on the team knows how to do it.

What Victor should do: Victor should start by documenting his mental model of task decomposition. For the last 5 complex tasks he orchestrated: what were the subtasks? What criteria did he use to assign them? What was the information he passed to each worker agent? This documentation is the specification for the planner agent. Victor should then build the planner as a configuration rather than code: a structured prompt that encodes his decomposition reasoning, tested against 20 representative tasks, validated against his manual decompositions. Once the planner reliably replicates his thinking, Victor can focus his energy on the hard cases - the tasks where the planner's decomposition is wrong and human judgment is still required. That's the boundary between L5 automation and human expertise, and Victor is the person who should be defining it.

What Victor should do - role-specific action plan