Planner Guru

Your focused planning agent that generates structured implementation plans as Markdown documents — producing step-by-step plans that developers can follow without ambiguity.

When to Use This Agent

Choose Planner Guru when:

• You need a quick, structured implementation plan for a feature or refactor
• Creating a plan document to share with team members
• Breaking down a complex task into a sequential checklist
• Generating a plan that other AI agents can execute

Consider alternatives when:

• You need detailed codebase analysis before planning — use a Plan Mode Guide
• You need actual implementation — use a developer agent
• You need architecture design — use an architect agent

Quick Start

Copy
# .claude/agents/planner.yml
name: Planner Guru
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
description: Focused planning agent that generates structured Markdown implementation plans

Example invocation:

claude "Generate an implementation plan for adding email notification support to our user registration flow"

Core Concepts

Plan Format

Copy
# Plan: [Feature Name]

## Summary
[1-2 sentence description of what this plan accomplishes]

## Steps

### Step 1: [Action]
- **File(s)**: `path/to/file.ts`
- **Changes**: [Specific modifications]
- **Verify**: [How to confirm this step worked]

### Step 2: [Action]
- **Depends on**: Step 1
- **File(s)**: `path/to/file.ts`
- **Changes**: [Specific modifications]
- **Verify**: [Verification method]

## Notes
- [Important considerations]
- [Potential risks]

Planning Principles

Principle	Description
Atomic Steps	Each step does one thing
Ordered	Steps respect dependencies
Verifiable	Each step has success criteria
Complete	No missing steps between start and finish
Specific	File paths, function names, not vague descriptions

Configuration

Parameter	Description	Default
plan_depth	Detail level (overview, standard, detailed)	standard
include_verification	Add verification steps	true
include_dependencies	Note step dependencies	true
max_steps	Maximum steps before suggesting split	15
format	Output format (markdown, checklist, json)	markdown

Best Practices

1. Read the relevant code before generating the plan. Understanding the existing codebase structure ensures the plan references real files, real function names, and real patterns. Plans generated without codebase context contain incorrect paths and assumptions.

2. Make each step independently verifiable. After completing step 3, the developer should be able to confirm it worked before moving to step 4. This catches issues early instead of at the end when debugging is harder.

3. Order steps by dependencies, then by complexity. Dependent steps must come after their prerequisites. Among independent steps, put simpler ones first to build momentum and catch setup issues early.

4. Include "what to change" at the code level. "Add a notification service" is too vague. "Create src/services/notificationService.ts with a sendEmail(userId, template, data) method that uses the existing emailClient from src/utils/email.ts" is actionable.

5. Flag assumptions that need verification. When the plan assumes something about the codebase ("the email utility already exists"), mark it as an assumption. The implementer should verify these before following the plan.

Common Issues

Plan assumes code structure that doesn't exist. Without reading the codebase, plans reference files, functions, and patterns that are different in reality. Always explore the code before generating steps.

Steps are too large to complete atomically. A step like "implement the notification system" combines multiple actions. Break it into: "create the service," "add the email template," "wire the service into the registration flow," and "add the database record."

Plan doesn't account for test changes. Production code changes need corresponding test updates. Include test modification steps explicitly — don't leave testing as an implicit afterthought.