Create comprehensive feature implementation plan with codebase analysis and research
Generates comprehensive implementation plans by analyzing codebase patterns and researching external documentation.
/plugin marketplace add Wirasm/PRPs-agentic-eng/plugin install prp-core@prp-marketplace<feature description | path/to/prd.md>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>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 |
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:
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}...
PHASE_0_CHECKPOINT:
EXTRACT from input:
FORMULATE user story:
As a <user type>
I want to <action/goal>
So that <benefit/value>
PHASE_1_CHECKPOINT:
GATE: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.
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:
ONLY AFTER Phase 2 is complete - solutions must fit existing codebase patterns first.
SEARCH for (use WebSearch tool):
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:
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:
ANALYZE deeply (use extended thinking if needed):
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:
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}
| 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 |
Explicit exclusions to prevent scope creep:
Execute in order. Each task is atomic and independently verifiable.
src/core/database/schema.ts (update)src/core/database/schema.ts:XX-YY - follow existing table patternimport { pgTable, text, timestamp } from "drizzle-orm/pg-core"npx tsc --noEmit - types must compilesrc/features/new/models.tssrc/features/projects/models.ts:1-10import { things } from "@/core/database/schema"type Thing = typeof things.$inferSelect$inferSelect for read types, $inferInsert for writenpx tsc --noEmitsrc/features/new/schemas.tssrc/features/projects/schemas.ts:1-30import { z } from "zod/v4" (note: zod/v4 not zod)npx tsc --noEmitsrc/features/new/errors.tssrc/features/projects/errors.ts:1-40npx tsc --noEmitsrc/features/new/repository.tssrc/features/projects/repository.ts:1-60import { db } from "@/core/database/client"results[0] pattern, not .first() - check noUncheckedIndexedAccessnpx tsc --noEmitsrc/features/new/service.tssrc/features/projects/service.ts:1-80import { getLogger } from "@/core/logging"npx tsc --noEmit && bun run lintsrc/features/new/index.tssrc/features/projects/index.ts:1-20npx tsc --noEmitsrc/features/new/tests/service.test.tssrc/features/projects/tests/service.test.ts:1-100bun test src/features/new/tests/| 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 |
bun run lint && npx tsc --noEmit
EXPECT: Exit 0, no errors or warnings
bun test src/features/{feature}/tests/
EXPECT: All tests pass, coverage >= 80%
bun test && bun run build
EXPECT: All tests pass, build succeeds, dist/ created
Use Supabase MCP to verify:
Use Browser MCP to verify:
{Step-by-step manual testing specific to this feature}
bun run lint && npx tsc --noEmit passesbun test {pattern} passesbun test && bun run build succeeds| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| {Risk description} | LOW/MED/HIGH | LOW/MED/HIGH | {Specific prevention/handling strategy} |
{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:
IMPLEMENTATION_READINESS:
PATTERN_FAITHFULNESS:
VALIDATION_COVERAGE:
UX_CLARITY:
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>