/prp-plan

<objective> 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. </objective>

<context> 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. </context>

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:

Read the PRD file
Parse the Implementation Phases table - find rows with Status: pending
Check dependencies - only select phases whose dependencies are complete
Select the next actionable phase:
- First pending phase with all dependencies complete
- If multiple candidates with same dependencies, note parallelism opportunity

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}

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.

Agent 1: `prp-core:codebase-explorer`

Finds WHERE code lives and extracts implementation patterns.

Use Task tool with subagent_type="prp-core:codebase-explorer":

Find all code relevant to implementing: [feature description].

LOCATE:
1. Similar implementations - analogous features with file:line references
2. Naming conventions - actual examples of function/class/file naming
3. Error handling patterns - how errors are created, thrown, caught
4. Logging patterns - logger usage, message formats
5. Type definitions - relevant interfaces and types
6. Test patterns - test file structure, assertion styles, test file locations
7. Configuration - relevant config files and settings
8. Dependencies - relevant libraries already in use

Categorize findings by purpose (implementation, tests, config, types, docs).
Return ACTUAL code snippets from codebase, not generic examples.

Agent 2: `prp-core:codebase-analyst`

Analyzes HOW integration points work and traces data flow.

Use Task tool with subagent_type="prp-core:codebase-analyst":

Analyze the implementation details relevant to: [feature description].

TRACE:
1. Entry points - where new code will connect to existing code
2. Data flow - how data moves through related components
3. State changes - side effects in related functions
4. Contracts - interfaces and expectations between components
5. Patterns in use - design patterns and architectural decisions

Document what exists with precise file:line references. No suggestions or improvements.

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.

Use Task tool with subagent_type="prp-core:web-researcher":

Research external documentation relevant to implementing: [feature description].

FIND:
1. Official documentation for involved libraries (match versions from package.json: [list relevant deps and versions])
2. Known gotchas, breaking changes, deprecations for these versions
3. Security considerations and best practices
4. Performance optimization patterns

VERSION CONSTRAINTS:
- [library]: v{version} (from package.json)
- [library]: v{version}

Return findings with:
- Direct links to specific doc sections (not just homepages)
- Key insights that affect implementation
- Gotchas with mitigation strategies
- Any conflicts between docs and existing codebase patterns 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:

╔═══════════════════════════════════════════════════════════════════════════════╗
║                              BEFORE STATE                                      ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║
║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║
║   │  Component  │         │   Current   │         │   Current   │            ║
║   └─────────────┘         └─────────────┘         └─────────────┘            ║
║                                                                               ║
║   USER_FLOW: [describe current step-by-step experience]                       ║
║   PAIN_POINT: [what's missing, broken, or inefficient]                        ║
║   DATA_FLOW: [how data moves through the system currently]                    ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

╔═══════════════════════════════════════════════════════════════════════════════╗
║                               AFTER STATE                                      ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║
║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║
║   │  Component  │         │    NEW      │         │    NEW      │            ║
║   └─────────────┘         └─────────────┘         └─────────────┘            ║
║                                   │                                           ║
║                                   ▼                                           ║
║                          ┌─────────────┐                                      ║
║                          │ NEW_FEATURE │  ◄── [new capability added]          ║
║                          └─────────────┘                                      ║
║                                                                               ║
║   USER_FLOW: [describe new step-by-step experience]                           ║
║   VALUE_ADD: [what user gains from this change]                               ║
║   DATA_FLOW: [how data moves through the system after]                        ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

DOCUMENT interaction changes:

Location	Before	After	User_Action	Impact
`/route`	State A	State B	Click X	Can now Y
`Component.tsx`	Missing feature	Has feature	Input Z	Gets result W

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:

Use Task tool with subagent_type="prp-core:codebase-analyst":

Analyze the architecture around these integration points for: [feature description].

INTEGRATION POINTS (from Phase 2):
- [entry point 1 from explorer/analyst findings]
- [entry point 2]

ANALYZE:
1. How data flows through each integration point
2. What contracts exist between components
3. What side effects occur at each stage
4. What error handling patterns are in place

Document what exists with precise file:line references. No suggestions.

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 (the template to fill and save):

# Feature: {Feature Name}

## Summary

{One paragraph: What we're building and high-level approach}

## User Story

As a {user type}
I want to {action}
So that {benefit}

## Problem Statement

{Specific problem this solves - must be testable}

## Solution Statement

{How we're solving it - architecture overview}

## Metadata

| Field            | Value                                             |
| ---------------- | ------------------------------------------------- |
| Type             | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |
| Complexity       | LOW / MEDIUM / HIGH                               |
| Systems Affected | {comma-separated list}                            |
| Dependencies     | {external libs/services with versions}            |
| Estimated Tasks  | {count}                                           |

---

## UX Design

### Before State

{ASCII diagram - current user experience with data flows}


### After State

{ASCII diagram - new user experience with data flows}


### Interaction Changes
| Location | Before | After | User Impact |
|----------|--------|-------|-------------|
| {path/component} | {old behavior} | {new behavior} | {what changes for user} |

---

## Mandatory Reading

**CRITICAL: Implementation agent MUST read these files before starting any task:**

| Priority | File | Lines | Why Read This |
|----------|------|-------|---------------|
| P0 | `path/to/critical.ts` | 10-50 | Pattern to MIRROR exactly |
| P1 | `path/to/types.ts` | 1-30 | Types to IMPORT |
| P2 | `path/to/test.ts` | all | Test pattern to FOLLOW |

**External Documentation:**
| Source | Section | Why Needed |
|--------|---------|------------|
| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |

---

## Patterns to Mirror

**NAMING_CONVENTION:**
```typescript
// SOURCE: src/features/example/service.ts:10-15
// COPY THIS PATTERN:
{actual code snippet from codebase}

ERROR_HANDLING:

// SOURCE: src/features/example/errors.ts:5-20
// COPY THIS PATTERN:
{actual code snippet from codebase}

LOGGING_PATTERN:

// SOURCE: src/features/example/service.ts:25-30
// COPY THIS PATTERN:
{actual code snippet from codebase}

REPOSITORY_PATTERN:

// SOURCE: src/features/example/repository.ts:10-40
// COPY THIS PATTERN:
{actual code snippet from codebase}

SERVICE_PATTERN:

// SOURCE: src/features/example/service.ts:40-80
// COPY THIS PATTERN:
{actual code snippet from codebase}

TEST_STRUCTURE:

// SOURCE: src/features/example/tests/service.test.ts:1-25
// COPY THIS PATTERN:
{actual code snippet from codebase}

Files to Change

File	Action	Justification
`src/features/new/models.ts`	CREATE	Type definitions - re-export from schema
`src/features/new/schemas.ts`	CREATE	Zod validation schemas
`src/features/new/errors.ts`	CREATE	Feature-specific errors
`src/features/new/repository.ts`	CREATE	Database operations
`src/features/new/service.ts`	CREATE	Business logic
`src/features/new/index.ts`	CREATE	Public API exports
`src/core/database/schema.ts`	UPDATE	Add table definition

NOT Building (Scope Limits)

Explicit exclusions to prevent scope creep:

{Item 1 - explicitly out of scope and why}
{Item 2 - explicitly out of scope and why}

Step-by-Step Tasks

Execute in order. Each task is atomic and independently verifiable.

Task 1: CREATE `src/core/database/schema.ts` (update)

ACTION: ADD table definition to schema
IMPLEMENT: {specific columns, types, constraints}
MIRROR: src/core/database/schema.ts:XX-YY - follow existing table pattern
IMPORTS: import { pgTable, text, timestamp } from "drizzle-orm/pg-core"
GOTCHA: {known issue to avoid, e.g., "use uuid for id, not serial"}
VALIDATE: npx tsc --noEmit - types must compile

Task 2: CREATE `src/features/new/models.ts`

ACTION: CREATE type definitions file
IMPLEMENT: Re-export table, define inferred types
MIRROR: src/features/projects/models.ts:1-10
IMPORTS: import { things } from "@/core/database/schema"
TYPES: type Thing = typeof things.$inferSelect
GOTCHA: Use $inferSelect for read types, $inferInsert for write
VALIDATE: npx tsc --noEmit

Task 3: CREATE `src/features/new/schemas.ts`

ACTION: CREATE Zod validation schemas
IMPLEMENT: CreateThingSchema, UpdateThingSchema
MIRROR: src/features/projects/schemas.ts:1-30
IMPORTS: import { z } from "zod/v4" (note: zod/v4 not zod)
GOTCHA: z.record requires two args in v4
VALIDATE: npx tsc --noEmit

Task 4: CREATE `src/features/new/errors.ts`

ACTION: CREATE feature-specific error classes
IMPLEMENT: ThingNotFoundError, ThingAccessDeniedError
MIRROR: src/features/projects/errors.ts:1-40
PATTERN: Extend base Error, include code and statusCode
VALIDATE: npx tsc --noEmit

Task 5: CREATE `src/features/new/repository.ts`

ACTION: CREATE database operations
IMPLEMENT: findById, findByUserId, create, update, delete
MIRROR: src/features/projects/repository.ts:1-60
IMPORTS: import { db } from "@/core/database/client"
GOTCHA: Use results[0] pattern, not .first() - check noUncheckedIndexedAccess
VALIDATE: npx tsc --noEmit

Task 6: CREATE `src/features/new/service.ts`

ACTION: CREATE business logic layer
IMPLEMENT: createThing, getThing, updateThing, deleteThing
MIRROR: src/features/projects/service.ts:1-80
PATTERN: Use repository, add logging, throw custom errors
IMPORTS: import { getLogger } from "@/core/logging"
VALIDATE: {type-check-cmd} && {lint-cmd}

Task 7: CREATE `{source-dir}/features/new/index.ts`

ACTION: CREATE public API exports
IMPLEMENT: Export types, schemas, errors, service functions
MIRROR: {source-dir}/features/{example}/index.ts:1-20
PATTERN: Named exports only, hide repository (internal)
VALIDATE: {type-check-cmd}

Task 8: CREATE `{source-dir}/features/new/tests/service.test.ts`

ACTION: CREATE unit tests for service
IMPLEMENT: Test each service function, happy path + error cases
MIRROR: {source-dir}/features/{example}/tests/service.test.ts:1-100
PATTERN: Use project's test framework (jest, vitest, bun:test, pytest, etc.)
VALIDATE: {test-cmd} {path-to-tests}

Testing Strategy

Unit Tests to Write

Test File	Test Cases	Validates
`src/features/new/tests/schemas.test.ts`	valid input, invalid input	Zod schemas
`src/features/new/tests/errors.test.ts`	error properties	Error classes
`src/features/new/tests/service.test.ts`	CRUD ops, access control	Business logic

Edge Cases Checklist

Validation Commands

IMPORTANT: Replace these placeholders with actual commands from the project's package.json/config.

Level 1: STATIC_ANALYSIS

{runner} run lint && {runner} run type-check
# Examples: npm run lint, pnpm lint, ruff check . && mypy ., cargo clippy

EXPECT: Exit 0, no errors or warnings

Level 2: UNIT_TESTS

{runner} test {path/to/feature/tests}
# Examples: npm test, pytest tests/, cargo test, go test ./...

EXPECT: All tests pass, coverage >= 80%

Level 3: FULL_SUITE

{runner} test && {runner} run build
# Examples: npm test && npm run build, cargo test && cargo build

EXPECT: All tests pass, build succeeds

Level 4: DATABASE_VALIDATION (if schema changes)

Use Supabase MCP to verify:

Table created with correct columns
RLS policies applied
Indexes created

Level 5: BROWSER_VALIDATION (if UI changes)

Use Browser MCP to verify:

UI renders correctly
User flows work end-to-end
Error states display properly

Level 6: MANUAL_VALIDATION

{Step-by-step manual testing specific to this feature}

Acceptance Criteria

All specified functionality implemented per user story
Level 1-3 validation commands pass with exit 0
Unit tests cover >= 80% of new code
Code mirrors existing patterns exactly (naming, structure, logging)
No regressions in existing tests
UX matches "After State" diagram

Completion Checklist

All tasks completed in dependency order
Each task validated immediately after completion
Level 1: Static analysis (lint + type-check) passes
Level 2: Unit tests pass
Level 3: Full test suite + build succeeds
Level 4: Database validation passes (if applicable)
Level 5: Browser validation passes (if applicable)
All acceptance criteria met

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
{Risk description}	LOW/MED/HIGH	LOW/MED/HIGH	{Specific prevention/handling strategy}

Notes

{Additional context, design decisions, trade-offs, future considerations}


</process>

<output>
**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):

```markdown
## Plan Created

**File**: `.claude/PRPs/plans/{feature-name}.plan.md`

{If from PRD:}
**Source PRD**: `{prd-file-path}`
**Phase**: #{number} - {phase name}
**PRD Updated**: Status set to `in-progress`, plan linked

{If parallel phases available:}
**Parallel Opportunity**: Phase {X} can run concurrently in a separate worktree.
To start: `git worktree add -b phase-{X} ../project-phase-{X} && cd ../project-phase-{X} && /prp-plan {prd-path}`

**Summary**: {2-3 sentence feature overview}

**Complexity**: {LOW/MEDIUM/HIGH} - {brief rationale}

**Scope**:
- {N} files to CREATE
- {M} files to UPDATE
- {K} total tasks

**Key Patterns Discovered**:
- {Pattern 1 from codebase-explorer/analyst with file:line}
- {Pattern 2 from codebase-explorer/analyst with file:line}

**External Research**:
- {Key doc 1 with version}
- {Key doc 2 with version}

**UX Transformation**:
- BEFORE: {one-line current state}
- AFTER: {one-line new state}

**Risks**:
- {Primary risk}: {mitigation}

**Confidence Score**: {1-10}/10 for one-pass implementation success
- {Rationale for score}

**Next Step**: To execute, run: `/prp-implement .claude/PRPs/plans/{feature-name}.plan.md`

</output> <verification> **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? </verification>

<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>