Skip to main content
Agent Type: Read-Only Task PlannerTools: Read, Glob, Grep

​
Overview

The Planner agent performs read-only exploration of the codebase to break down complex tasks into structured implementation plans. It identifies all files that need changes, lists dependencies, estimates complexity, and presents a plan for approval before any implementation begins.

​
When to Use

Use the Planner agent when:

Multi-File Changes

Task touches more than 5 files

Architecture Decisions

Requires architectural changes or design choices

Unclear Requirements

Requirements are ambiguous or need clarification

Complex Work

Expecting more than 10 tool calls during implementation

​
Configuration

---
name: planner
description: Break down complex tasks into implementation plans before writing code. Use when task touches >5 files, requires architecture decisions, or has unclear requirements.
tools: ["Read", "Glob", "Grep"]
---

​
Available Tools

​
Read
tool
Read files to understand current implementation
​
Glob
tool
Find files matching patterns
​
Grep
tool
Search for code patterns and references
The Planner agent is read-only. It cannot make changes to the codebase. Use it for exploration and planning only.

​
Workflow

The Planner follows a systematic 6-step workflow:
1

Understand the Goal

Parse the task description and clarify the objective
2

Explore Relevant Code

Use read-only tools to explore the codebase and understand current implementation
3

Identify Files to Change

List all files that need modifications, additions, or deletions
4

List Dependencies and Ordering

Determine what depends on what and the order of changes
5

Estimate Complexity

Assess the size and risk level of the task
6

Present Plan for Approval

Output a structured plan and wait for user approval before proceeding

​
Output Format

The Planner outputs a structured plan in the following format: 
## Plan: [Task Name]

### Goal
[One sentence describing what will be accomplished]

### Files to Modify
1. path/to/file.ts - [what changes will be made]
2. path/to/another.ts - [what changes will be made]

### Approach
[Step by step implementation approach]
1. First, do X because...
2. Then, update Y to...
3. Finally, add Z for...

### Risks
- [Potential issues or breaking changes]
- [Performance considerations]
- [Backward compatibility concerns]

### Questions
- [Clarifications needed from the user]
- [Technical decisions that need input]

​
Example Usage

Task: Refactor the authentication API to use JWT tokens

Output:
## Plan: Refactor Authentication to JWT

### Goal
Replace session-based auth with JWT tokens for better scalability

### Files to Modify
1. src/auth/middleware.ts - Replace session checks with JWT validation
2. src/auth/login.ts - Generate JWT instead of creating session
3. src/auth/types.ts - Add JWT payload interface
4. src/config/auth.ts - Add JWT secret and expiry config
5. tests/auth/*.test.ts - Update all auth tests

### Approach
1. Add JWT config (secret, expiry) to auth config
2. Update login endpoint to generate JWT on success
3. Replace session middleware with JWT validation
4. Update types to reflect new auth flow
5. Update tests to use JWT instead of sessions

### Risks
- Breaking change - all clients need updates
- Need migration strategy for existing sessions
- JWT secret management critical for security

### Questions
- Should we support both methods during migration?
- What's the token expiry time?
- Do we need refresh tokens?

​
Rules and Constraints

The Planner adheres to strict rules:
The Planner performs read-only exploration only. It never modifies, creates, or deletes files.
The Planner always presents the plan and waits for explicit approval before any implementation begins.
When requirements are unclear, the Planner asks questions rather than making assumptions.

​
Best Practices

Be Specific

Provide detailed task descriptions. Include context about why the change is needed.

Review Thoroughly

Review the plan carefully before approving. Check files list and approach.

Answer Questions

Address all questions in the Questions section before implementation starts.

Refine as Needed

Don’t hesitate to ask the Planner to revise if something seems off.

​
Integration with Other Agents

The Planner works well with other agents:
Use Planner for initial exploration, then hand off to Orchestrator for multi-phase implementation, and finally Reviewer for quality checks.

​
Common Scenarios

​
Scenario 1: New Feature

User: Add user profile page with avatar upload
Planner: Explores codebase, identifies routing, components, API endpoints
Output: Detailed plan with 8 files to modify, step-by-step approach
User: Approves plan
Next: Hand off to Orchestrator or implement directly

​
Scenario 2: Refactoring

User: Refactor database queries to use TypeORM
Planner: Finds all query files, checks dependencies
Output: Plan with 15 files, migration strategy, risks
User: Asks about backward compatibility
Planner: Revises plan with compatibility layer
User: Approves

​
Scenario 3: Unclear Requirements

User: Make the app faster
Planner: Explores performance bottlenecks
Output: Plan with 3 optimization areas, questions about priorities
User: Focus on API response time
Planner: Revises plan to target API optimizations only

​
Limitations

The Planner has these limitations:
  • Read-only: Cannot make any changes
  • No execution: Cannot run tests or verify hypotheses
  • No write operations: Cannot create example files or prototypes
For implementation and testing, use the Orchestrator or Debugger agents.

​
Tips for Better Plans

1

Provide Context

Explain why the change is needed, not just what to change
2

Share Constraints

Mention any technical constraints, deadlines, or backward compatibility needs
3

Reference Examples

Point to similar features in the codebase that should be followed
4

Clarify Scope

Be clear about what’s in scope and what’s not

​
Next Steps

Orchestrator

Multi-phase implementation after planning

Scout

Confidence-gated exploration alternative

Build docs developers (and LLMs) love

Get started for freeTalk to us