prp-plan

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.

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:

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:

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.

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.

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)