/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 Task tool with subagent_type="Explore" for codebase intelligence gathering. This ensures thorough pattern discovery before any external research. </objective>

<context> Project structure: !`ls -la src/` Package info: !`cat package.json | head -30` Existing features: !`ls src/features/ 2>/dev/null || echo "No features directory"` CLAUDE.md rules: @CLAUDE.md </context> <process>

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: Use Task tool with subagent_type="Explore" and prompt for thoroughness="very thorough"

Example Task invocation:

Explore the codebase to find patterns, conventions, and integration points
relevant to implementing: [feature description].

DISCOVER:
1. Similar implementations - find analogous features with file:line references
2. Naming conventions - extract 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
7. Integration points - where new code connects to existing
8. Dependencies - relevant libraries already in use

Return ACTUAL code snippets from codebase, not generic examples.

DOCUMENT discoveries in table format:

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

PHASE_2_CHECKPOINT:

• Explore agent launched and completed successfully
• At least 3 similar implementations found with file:line refs
• Code snippets are ACTUAL (copy-pasted from codebase, not invented)
• Integration points mapped with specific file paths
• 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.

SEARCH for (use WebSearch tool):

• Official documentation for involved libraries (match versions from package.json)
• Known gotchas, breaking changes, deprecations
• Security considerations and best practices
• Performance optimization patterns

FORMAT references with specificity:

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

• 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

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: npx tsc --noEmit && bun run lint

Task 7: CREATE src/features/new/index.ts

• ACTION: CREATE public API exports
• IMPLEMENT: Export types, schemas, errors, service functions
• MIRROR: src/features/projects/index.ts:1-20
• PATTERN: Named exports only, hide repository (internal)
• VALIDATE: npx tsc --noEmit

Task 8: CREATE src/features/new/tests/service.test.ts

• ACTION: CREATE unit tests for service
• IMPLEMENT: Test each service function, happy path + error cases
• MIRROR: src/features/projects/tests/service.test.ts:1-100
• PATTERN: Use describe/it from bun:test, mock repository
• VALIDATE: bun test src/features/new/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

• Empty string inputs
• Missing required fields
• Unauthorized access attempts
• Not found scenarios
• Duplicate creation attempts
• {feature-specific edge case}

---

Validation Commands

Level 1: STATIC_ANALYSIS

bun run lint && npx tsc --noEmit

EXPECT: Exit 0, no errors or warnings

Level 2: UNIT_TESTS

bun test src/features/{feature}/tests/

EXPECT: All tests pass, coverage >= 80%

Level 3: FULL_SUITE

bun test && bun run build

EXPECT: All tests pass, build succeeds, dist/ created

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: bun run lint && npx tsc --noEmit passes
• Level 2: bun test {pattern} passes
• Level 3: bun test && bun run 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 Explore agent with file:line}
- {Pattern 2 from Explore agent 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 Explore agent 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 Explore agent 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>