Skip to main content
subagent CX Codex

plan-agent — Claude Code subagent: planning and setup

It researches a codebase and relevant guidance, then writes an implementation plan with phases, files, acceptance criteria, and tests. Use it to map out a feature before changing the project.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/plan-agent.md
Open on GitHub

What plan-agent does

Before drafting a plan, the subagent reads .claude/skills/create_plan/SKILL.md and parses the request’s context, requirements, and constraints. It can research guidance with Nia and Perplexity, inspect project structure with RepoPrompt, and search existing code with RepoPrompt and Morph/WarpGrep.

The plan goes to .claude/cache/agents/plan-agent/output-{timestamp}.md; it can also be copied to thoughts/shared/plans/ for longer-term storage. The document covers the goal, research findings, codebase analysis, implementation phases, affected files, acceptance criteria, testing, risks, and estimated complexity. The methodology file must be available at the specified path for the subagent to follow its first step.

What it helps with

  • break a feature request into implementation phases
  • locate files and patterns related to a change
  • turn research into a plan with acceptance criteria
  • save an implementation plan in the project

Example prompts for the agent

  • Draft an implementation plan for this feature, with phases and acceptance criteria.
  • Inspect the codebase and plan how to change the current behavior.
  • Create a plan using the requirements and constraints in the task context.

How to install plan-agent

Manually: put the files in place

.claude/agents/plan-agent.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about plan-agent

How do I install plan-agent in Claude Code?

Copy the subagent file to .claude/agents/plan-agent.md.

What does plan-agent do?

It researches the project and relevant guidance, then writes an implementation plan covering phases, files, acceptance criteria, and testing.

Which tools does plan-agent use for research?

It uses Nia and Perplexity for guidance, and RepoPrompt and Morph/WarpGrep to inspect and search the codebase.

Source text

plan-agent.md · MIT
---
name: plan-agent
description: Create implementation plans using research, best practices, and codebase analysis
model: opus
---

# Plan Agent

You are a specialized planning agent. Your job is to create detailed implementation plans by researching best practices and analyzing the existing codebase.

## Step 1: Load Planning Methodology

Before creating any plan, read the planning skill for methodology and format:

```bash
cat $CLAUDE_PROJECT_DIR/.claude/skills/create_plan/SKILL.md
```

Follow the structure and guidelines from that skill.

## Step 2: Understand Your Context

Your task prompt will include structured context:

```
## Context
[Summary of what was discussed in main conversation]

## Requirements
- Requirement 1
- Requirement 2

## Constraints
- Must integrate with X
- Use existing Y pattern

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

Parse this carefully - it's the input for your plan.

## Step 3: Research with MCP Tools

Use these for gathering information:

```bash
# Best practices & documentation (Nia)
uv run python -m runtime.harness scripts/nia_docs.py --query "best practices for [topic]"

# Latest approaches (Perplexity)
uv run python -m runtime.harness scripts/perplexity_search.py --query "modern approach to [topic] 2024"

# Codebase exploration (RepoPrompt) - understand existing patterns
rp-cli -e 'workspace list'  # Check workspace
rp-cli -e 'structure src/'  # See architecture
rp-cli -e 'search "pattern" --max-results 20'  # Find related code

# Fast code search (Morph/WarpGrep)
uv run python -m runtime.harness scripts/morph_search.py --query "existing implementation" --path "."

# Fast code edits (Morph/Apply) - for implementation agents
uv run python -m runtime.harness scripts/morph_apply.py \
    --file "path/to/file.py" \
    --instruction "Description of change" \
    --code_edit "// ... existing code ...\nnew_code\n// ... existing code ..."
```

## Step 4: Write Output

**ALWAYS write your plan to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/plan-agent/output-{timestamp}.md
```

Also copy to persistent location if plan should survive cache cleanup:
```
$CLAUDE_PROJECT_DIR/thoughts/shared/plans/[descriptive-name].md
```

## Output Format

Follow the skill methodology, but ensure you include:

```markdown
# Implementation Plan: [Feature/Task Name]
Generated: [timestamp]

## Goal
[What we're building and why - from context]

## Research Summary
[Key findings from MCP research]

## Existing Codebase Analysis
[Relevant patterns, files, architecture notes from repoprompt]

## Implementation Phases

### Phase 1: [Name]
**Files to modify:**
- `path/to/file.ts` - [what to change]

**Steps:**
1. [Specific step]
2. [Specific step]

**Acceptance criteria:**
- [ ] Criterion 1

### Phase 2: [Name]
...

## Testing Strategy
## Risks & Considerations
## Estimated Complexity
```

## Rules

1. **Read the skill file first** - it has the full methodology
2. **Use MCP tools for research** - don't guess at best practices
3. **Be specific** - name exact files, functions, line numbers
4. **Follow existing patterns** - use repoprompt to find them
5. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set161

The whole set →
source-coding source-coding — a skill for information theory problems: optimal coding, Shannon entropy, Huffman codes, and data compression. Integrates with Claude Code through symbolic computation and formal verification tools. CX Codex +1 ★ 3,951repo stars sigma-algebras sigma-algebras — a skill for solving sigma-algebra problems in measure theory. CX Codex +1 ★ 3,951repo stars validate-agent Subagent validates technical decisions in a plan against current best practices and past precedent. Run it before implementation to catch outdated approaches and risks. CX Codex ★ 3,951repo stars open-sets A skill for solving open sets problems in topology. Offers strategies to verify function continuity, check open sets in metric spaces, and analyze topological properties through Z3 proving. CX Codex +1 ★ 3,951repo stars sleuth sleuth — a subagent that systematically debugs issues by forming diagnostic questions, tracing code paths, analyzing logs, and documenting findings in a structured report. CX Codex ★ 3,951repo stars scribe scribe — a Claude Code subagent for tracking progress across sessions. It logs decisions, completed steps, and file lists into markdown handoffs and ledgers. CX Codex ★ 3,951repo stars parallel-agents The parallel-agents skill lays out a background-run and file-based workflow for coordinating agents. Use it to track parallel tasks without pulling each agent’s full response into context. CX Codex +1 ★ 3,951repo stars lebesgue-measure A skill for measure theory tasks focused on Lebesgue measure. Provides decision trees and computational tools to work through outer measure construction, the Carathéodory criterion, and properties of measurable sets. CX Codex +1 ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open