prp-plan

Transform "$ARGUMENTS" into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.

Core Principle: PLAN ONLY - no code written. Create a context-rich document that enables one-pass implementation success.

Execution Order: CODEBASE FIRST, RESEARCH SECOND. Solutions must fit existing patterns before introducing new ones.

Agent Strategy: Use specialized agents for intelligence gathering:

• prp-core:codebase-explorer — finds WHERE code lives and extracts implementation patterns
• prp-core:codebase-analyst — analyzes HOW integration points work and traces data flow
• prp-core:web-researcher — strategic web research with citations and gap analysis

Launch codebase agents in parallel first, then research agent second.

CLAUDE.md rules: @CLAUDE.md

Directory Discovery (run these to understand project structure):

• List root contents: ls -la
• Find main source directories: ls -la */ 2>/dev/null | head -50
• Identify project type from config files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)

IMPORTANT: Do NOT assume src/ exists. Common alternatives include:

• app/ (Next.js, Rails, Laravel)
• lib/ (Ruby gems, Elixir)
• packages/ (monorepos)
• cmd/, internal/, pkg/ (Go)
• Root-level source files (Python, scripts)

Discover the actual structure before proceeding.

Mode Select

Before planning, check intent:

• Link / connect two existing plans — the request is to wire a back/forward reference between plans (e.g. "link plan A to plan B", "this plan builds on that one", update-references <plan> <related> [back|forward]). → Follow workflows/update-references.md and stop. Do NOT run the planning phases below.
• Create / update a plan (the default) — anything that describes a feature, hands over a PRD, or otherwise asks for an implementation plan. → Continue with Phase 0 below.

---

Phase 0: DETECT - Input Type Resolution

Determine input type:

Input Pattern	Type	Action
Ends with .prd.md	PRD file	Parse PRD, select next phase
Ends with .md and contains "Implementation Phases"	PRD file	Parse PRD, select next phase
File path that exists	Document	Read and extract feature description
Free-form text	Description	Use directly as feature input
Empty/blank	Conversation	Use conversation context as input

If PRD File Detected:

1. Read the PRD file

2. Parse the Implementation Phases table - find rows with Status: pending

3. Check dependencies - only select phases whose dependencies are complete

4. Select the next actionable phase:

   • First pending phase with all dependencies complete
   • If multiple candidates with same dependencies, note parallelism opportunity

5. Extract phase context:

   PHASE: {phase number and name}
   GOAL: {from phase details}
   SCOPE: {from phase details}
   SUCCESS SIGNAL: {from phase details}
   PRD CONTEXT: {problem statement, user, hypothesis from PRD}
   

6. Report selection to user:

   PRD: {prd file path}
   Selected Phase: #{number} - {name}
   
   {If parallel phases available:}
   Note: Phase {X} can also run in parallel (in separate worktree).
   
   Proceeding with Phase #{number}...
   

If Free-form or Conversation Context:

• Proceed directly to Phase 1 with the input as feature description

PHASE_0_CHECKPOINT:

• Input type determined
• If PRD: next phase selected and dependencies verified
• Feature description ready for Phase 1

---

Phase 1: PARSE - Feature Understanding

EXTRACT from input:

• Core problem being solved
• User value and business impact
• Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX
• Complexity: LOW | MEDIUM | HIGH
• Affected systems list

FORMULATE user story:

As a <user type>
I want to <action/goal>
So that <benefit/value>

PHASE_1_CHECKPOINT:

• Problem statement is specific and testable
• User story follows correct format
• Complexity assessment has rationale
• Affected systems identified

GATE: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.

---

Phase 2: EXPLORE - Codebase Intelligence

CRITICAL: Launch two specialized agents in parallel using multiple Task tool calls in a single message. Read references/agent-prompts.md now (mandatory) — it is the exact prompt text for every subagent launch in Phases 2, 3, and 5.

• Agent 1: prp-core:codebase-explorer — finds WHERE code lives and extracts implementation patterns. Launch with the Phase 2 codebase-explorer prompt.
• Agent 2: prp-core:codebase-analyst — analyzes HOW integration points work and traces data flow. Launch with the Phase 2 codebase-analyst prompt.

Merge Agent Results

Combine findings from both agents into a unified discovery table:

Category	File:Lines	Pattern Description	Code Snippet
NAMING	src/features/X/service.ts:10-15	camelCase functions	export function createThing()
ERRORS	src/features/X/errors.ts:5-20	Custom error classes	class ThingNotFoundError
LOGGING	src/core/logging/index.ts:1-10	getLogger pattern	const logger = getLogger("domain")
TESTS	src/features/X/tests/service.test.ts:1-30	describe/it blocks	describe("service", () => {
TYPES	src/features/X/models.ts:1-20	Drizzle inference	type Thing = typeof things.$inferSelect
FLOW	src/features/X/service.ts:40-60	Data transformation	input → validate → persist → respond

PHASE_2_CHECKPOINT:

• Both agents (prp-core:codebase-explorer and prp-core:codebase-analyst) launched in parallel and completed
• At least 3 similar implementations found with file:line refs
• Code snippets are ACTUAL (copy-pasted from codebase, not invented)
• Integration points mapped with data flow traces
• Dependencies cataloged with versions from package.json

---

Phase 3: RESEARCH - External Documentation

ONLY AFTER Phase 2 is complete - solutions must fit existing codebase patterns first.

Launch prp-core:web-researcher with the Phase 3 web-researcher prompt from references/agent-prompts.md, filling in the feature description and the dependency versions found in Phase 2.

FORMAT the agent's findings into plan references:

- [Library Docs v{version}](https://url#specific-section)
  - KEY_INSIGHT: {what we learned that affects implementation}
  - APPLIES_TO: {which task/file this affects}
  - GOTCHA: {potential pitfall and how to avoid}

PHASE_3_CHECKPOINT:

• prp-core:web-researcher agent launched and completed
• Documentation versions match package.json
• URLs include specific section anchors (not just homepage)
• Gotchas documented with mitigation strategies
• No conflicting patterns between external docs and existing codebase

---

Phase 4: DESIGN - UX Transformation

CREATE ASCII diagrams showing user experience before and after, then DOCUMENT interaction changes. Read templates/ux-diagram-format.md now (mandatory) — it is the exact BEFORE/AFTER diagram shape and interaction-changes table to produce.

PHASE_4_CHECKPOINT:

• Before state accurately reflects current system behavior
• After state shows ALL new capabilities
• Data flows are traceable from input to output
• User value is explicit and measurable

---

Phase 5: ARCHITECT - Strategic Design

For complex features with multiple integration points, use prp-core:codebase-analyst to trace how existing architecture works at the integration points identified in Phase 2 — launch with the Phase 5 architecture deep-dive prompt from references/agent-prompts.md.

Then ANALYZE deeply (use extended thinking if needed):

• ARCHITECTURE_FIT: How does this integrate with the existing architecture?
• EXECUTION_ORDER: What must happen first → second → third?
• FAILURE_MODES: Edge cases, race conditions, error scenarios?
• PERFORMANCE: Will this scale? Database queries optimized?
• SECURITY: Attack vectors? Data exposure risks? Auth/authz?
• MAINTAINABILITY: Will future devs understand this code?

DECIDE and document:

APPROACH_CHOSEN: [description]
RATIONALE: [why this over alternatives - reference codebase patterns]

ALTERNATIVES_REJECTED:

- [Alternative 1]: Rejected because [specific reason]
- [Alternative 2]: Rejected because [specific reason]

NOT_BUILDING (explicit scope limits):

- [Item 1 - explicitly out of scope and why]
- [Item 2 - explicitly out of scope and why]

PHASE_5_CHECKPOINT:

• Approach aligns with existing architecture and patterns
• Dependencies ordered correctly (types → repository → service → routes)
• Edge cases identified with specific mitigation strategies
• Scope boundaries are explicit and justified

---

Phase 6: GENERATE - Implementation Plan File

OUTPUT_PATH: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md

Create directory if needed: mkdir -p .claude/PRPs/plans

PLAN_STRUCTURE: Read templates/plan-template.md now (mandatory) — it is the exact plan document to fill and save. Keep every section heading; fill every {placeholder} with real, project-specific content (the template's remaining snippets and table entries are illustrative examples from one TypeScript project, not content to keep). Before writing the plan's Step-by-Step Tasks section, read references/task-block-format.md (mandatory) for the task-block field detail and worked examples; before filling its Validation Commands section, read references/validation-commands.md (mandatory) for the per-language commands to embed.

**OUTPUT_FILE**: `.claude/PRPs/plans/{kebab-case-feature-name}.plan.md`

If input was from PRD file, also update the PRD:

1. Update phase status in the Implementation Phases table:

   • Change the phase's Status from pending to in-progress
   • Add the plan file path to the PRP Plan column

2. Edit the PRD file with these changes

REPORT_TO_USER (display after creating plan): Read templates/report-format.md now (mandatory) and display the "Plan Created" report in exactly that structure.

**FINAL_VALIDATION before saving plan:**

CONTEXT_COMPLETENESS:

• All patterns from prp-core:codebase-explorer and prp-core:codebase-analyst documented with file:line references
• External docs versioned to match package.json
• Integration points mapped with specific file paths
• Gotchas captured with mitigation strategies
• Every task has at least one executable validation command

IMPLEMENTATION_READINESS:

• Tasks ordered by dependency (can execute top-to-bottom)
• Each task is atomic and independently testable
• No placeholders - all content is specific and actionable
• Pattern references include actual code snippets (copy-pasted, not invented)

PATTERN_FAITHFULNESS:

• Every new file mirrors existing codebase style exactly
• No unnecessary abstractions introduced
• Naming follows discovered conventions
• Error/logging patterns match existing
• Test structure matches existing tests

VALIDATION_COVERAGE:

• Every task has executable validation command
• All 6 validation levels defined where applicable
• Edge cases enumerated with test plans

UX_CLARITY:

• Before/After ASCII diagrams are detailed and accurate
• Data flows are traceable
• User value is explicit and measurable

NO_PRIOR_KNOWLEDGE_TEST: Could an agent unfamiliar with this codebase implement using ONLY the plan?

<success_criteria> CONTEXT_COMPLETE: All patterns, gotchas, integration points documented from actual codebase via prp-core:codebase-explorer and prp-core:codebase-analyst agents IMPLEMENTATION_READY: Tasks executable top-to-bottom without questions, research, or clarification PATTERN_FAITHFUL: Every new file mirrors existing codebase style exactly VALIDATION_DEFINED: Every task has executable verification command UX_DOCUMENTED: Before/After transformation is visually clear with data flows ONE_PASS_TARGET: Confidence score 8+ indicates high likelihood of first-attempt success </success_criteria>

Resources

• references/agent-prompts.md — exact subagent prompts for Phases 2, 3, and 5 (mandatory read at Phase 2)
• templates/plan-template.md — the plan document to fill and save (mandatory read in Phase 6)
• templates/ux-diagram-format.md — the BEFORE/AFTER ASCII diagram shape and interaction-changes table (mandatory read in Phase 4)
• templates/report-format.md — the "Plan Created" report displayed to the user (mandatory read in Output)
• references/task-block-format.md — task-block field detail and worked examples (mandatory read in Phase 6, before writing Step-by-Step Tasks)
• references/validation-commands.md — per-language validation command catalog (mandatory read in Phase 6, before filling Validation Commands)
• workflows/update-references.md — the update-references mode (read only when Mode Select routes there)