Blueprint Prp Create

/blueprint:prp-create

Create a comprehensive PRP (Product Requirement Prompt) - a self-contained packet with all context an AI agent needs to deliver production code on first attempt.

What is a PRP? PRD + Curated Codebase Intelligence + Implementation Blueprint + Validation Gates = everything needed for reliable implementation.

Usage: /blueprint:prp-create [feature-name]

Prerequisites:

• Blueprint Development initialized (docs/blueprint/ exists)
• Clear understanding of the feature to implement

When to Use This Skill

Context

• Blueprint initialized: !find docs/blueprint -maxdepth 1 -name 'manifest.json' -type f
• Last PRP ID: !jq -r '.id_registry.last_prp // 0' docs/blueprint/manifest.json
• ai_docs available: !find docs/blueprint/ai_docs -type f -name "*.md"
• Existing PRDs: !find docs/prds -name "*.md" -type f

Parameters

Parse $ARGUMENTS:

• feature-name (required): Kebab-case name for PRP (e.g., auth-oauth2, api-rate-limiting)
• Used for filename and document ID generation

Execution

Execute the complete PRP creation workflow:

Step 1: Verify prerequisites and understand requirements

1. If Blueprint not initialized → Error: "Run /blueprint:init first" 2. Ask user to describe the feature: "What feature needs to be implemented?"

• Capture: Goal, why it matters, success criteria

3. Ask if this implements an existing PRD: "Does this implement an existing PRD or is it standalone?"

• If PRD chosen → Store PRD ID for linking

4. Determine feature type (API endpoint, database, UI, integration, etc.)

Step 2: Research codebase patterns

Use Explore agent to find existing patterns:

1. Similar features already implemented (identify existing patterns to follow) 2. Relevant file locations and integration points 3. Testing patterns used for similar features 4. Architecture decisions that affect this feature

Store findings with specific file paths and line numbers.

Step 3: Research external documentation

For relevant libraries/frameworks, gather:

1. Official documentation sections (capture URLs with specific sections) 2. Known issues and gotchas from Stack Overflow / GitHub discussions 3. Best practices from documentation 4. Common implementation patterns

Use WebSearch/WebFetch as needed. Create or update ai_docs entries if needed (see REFERENCE.md).

Step 4: Generate PRP document ID and structure

Generate next PRP ID from manifest:

• Extract id_registry.last_prp from manifest.json
• Next ID = last_prp + 1 (format: PRP-NNN)

Create docs/prps/[feature-name].md with frontmatter and sections (see REFERENCE.md).

Step 5: Draft PRP content with research findings

Fill all required sections (see REFERENCE.md):

1. Goal & Why: One-sentence goal, business justification, target users, priority 2. Success Criteria: Specific, testable acceptance criteria with metrics 3. Context:

• Documentation references (URLs with specific sections)
• ai_docs references (links to curated library docs)
• Codebase Intelligence: File paths, code snippets with line numbers, patterns to follow
• Known Gotchas: Critical warnings with mitigations

4. Implementation Blueprint:

• Architecture decision with rationale
• Task breakdown (Required / Deferred / Nice-to-Have categories)
• Order of implementation

5. TDD Requirements: Test strategy and critical test cases 6. Validation Gates: Executable commands (linting, type-checking, tests, coverage)

Critical: All tasks must be explicitly categorized (see REFERENCE.md).

Step 6: Score confidence across dimensions

Rate each dimension 1-10:

Calculate overall score as average of dimensions. Target: 7+ for execution, 9+ for subagent delegation.

If score < 7 → Return to Steps 2-3 to fill gaps.

Step 7: Review and validate completeness

Verify checklist (see REFERENCE.md):

• [ ] Goal is clear and specific
• [ ] Success criteria are testable
• [ ] All file paths are explicit (not "somewhere in...")
• [ ] Code snippets show actual patterns with line references
• [ ] Gotchas include mitigations
• [ ] Validation commands are copy-pasteable
• [ ] Confidence score is honest

Update docs/blueprint/manifest.json ID registry with new PRP entry.

Step 8: Report PRP and prompt for next action

Display summary showing:

• PRP ID and location
• Feature summary and approach
• Context collected (ai_docs, patterns, documentation)
• Linked documents (source PRD if applicable)
• Confidence score with breakdown
• Any gaps if score < 7

If confidence >= 7, offer user choices:

• Execute PRP now → /blueprint:prp-execute [feature-name]
• Create work-order for subagent → /blueprint:work-order
• Review and refine → Show file location and gaps
• Done for now → Exit (save for later execution)

If confidence < 7, offer user choices:

• Research more context → Use Explore agent for gaps
• Create ai_docs entries → /blueprint:curate-docs
• Execute anyway (risky) → Proceed with warning
• Done for now → Save incomplete PRP

Agentic Optimizations

---

For PRP document structure, task categorization, review checklists, and ai_docs creation guidance, see REFERENCE.md.

blueprint-prp-create REFERENCE

Reference material for PRP document structure, section templates, task categorization, and quality checklists.

PRP Structure

---
id: PRP-NNN
created: YYYY-MM-DD
modified: YYYY-MM-DD
status: Draft | Ready | Executed
implements: [PRD-NNN] or []
relates-to: [ADR-NNNN] or []
github-issues: []
confidence: X/10
---

# Feature Name

## Goal & Why

[One sentence goal]

### Problem Statement
[Business justification for this feature]

### Target Users
[Who will use this feature]

### Priority
[P0/P1/P2 - impact and urgency]

## Success Criteria

- [ ] Criterion 1: [Specific, testable condition]
- [ ] Criterion 2: [Specific, testable condition]
- [ ] Criterion 3: [Performance baseline with metric]
- [ ] Criterion 4: [Security requirement]

## Context

### Documentation References
- [Library Name](https://docs.example.com/section) - Specific section explaining [what]
- [Framework Name](https://docs.example.com/api) - API endpoint for [feature]

### ai_docs References
- `ai_docs/libraries/[library-name].md` - Patterns for [feature type]
- `ai_docs/project/patterns.md` - Integration pattern [X]

### Codebase Intelligence

**Existing Patterns to Follow:**
- File: `src/features/auth/routes.ts:23-45` - Shows authentication middleware pattern
- File: `test/features/auth/handlers.test.ts:1-30` - Shows testing pattern for routes

**Integration Points:**
- Route handler location: `src/features/[feature]/routes.ts`
- Test file location: `test/features/[feature]/handlers.test.ts`
- Middleware chain: Line 15-25 in `src/middleware.ts`

### Known Gotchas

| Gotcha | Impact | Mitigation |
|--------|--------|-----------|
| OAuth tokens expire in 1 hour | Feature breaks silently | Implement token refresh with 10-min buffer |
| Database connection pool limits | Performance degrades under load | Set pool size to CPU count * 4 |
| File upload size limit | Large files fail silently | Return 413 error with clear message |

## Implementation Blueprint

### Architecture Decision

**Chosen Approach**: [Pattern Name]

**Rationale**:
- [Why this approach]
- [What problem it solves]
- [Trade-offs considered]

### Required Tasks
1. Implement core API endpoint
   - Pseudocode: [High-level implementation outline]
   - Files: `src/features/[feature]/handlers.ts`
   - Dependencies: [List]

2. Add input validation
   - Patterns: Follow validation middleware from `src/middleware.ts`
   - Files: `src/features/[feature]/validators.ts`

3. Write unit tests
   - Strategy: [Specific test cases needed]
   - File: `test/features/[feature]/handlers.test.ts`

### Deferred Tasks (Phase 2)
4. Add caching layer
   - Reason: Requires Redis infrastructure decision
   - Follow-up: Create separate work-order after infrastructure ready

5. Add rate limiting
   - Reason: Needs capacity planning
   - Follow-up: Implement based on production metrics

### Nice-to-Have
6. Add OpenAPI docs generation
7. Add request logging middleware

## TDD Requirements

### Test Strategy
- **Unit tests**: Logic and error handling
- **Integration tests**: API endpoints with database
- **E2E tests**: User flows (if applicable)

### Critical Test Cases

// Template for login endpoint tests describe('POST /auth/login', () => { test('succeeds with valid credentials', async () => { // Arrange: Set up test data // Act: Make request // Assert: Verify response });

test('fails with invalid credentials', async () => { // Validate error response });

test('implements rate limiting', async () => { // Verify after 5 attempts within 1 minute, returns 429 }); });

## Validation Gates

Execute these commands during and after implementation:

**Linting:**

npm run lint # Expected: No errors

**Type Checking:**

npm run type-check # Expected: No errors

**Unit Tests:**

npm test -- test/features/[feature] # Expected: All pass

**Integration Tests:**

npm run test:integration -- test/features/[feature] # Expected: All pass

**Coverage:**

npm run test:coverage # Expected: >= 80% line coverage

**Security Scan:**

npm audit # Expected: No vulnerabilities

## Task Categorization

### Required Tasks
- **Definition**: Must be implemented for MVP
- **Execution Behavior**: Fully implemented during PRP execution
- **Example**: Core API endpoint, authentication, input validation

### Deferred (Phase 2)
- **Definition**: Important but not blocking MVP
- **Execution Behavior**: Logged with reason, GitHub issue created
- **Example**: Caching, rate limiting, advanced features
- **When to Use**: Feature is valuable but:
  - Requires infrastructure decision
  - Needs capacity planning
  - Depends on other work
  - Time constraint

### Nice-to-Have
- **Definition**: Optional enhancement
- **Execution Behavior**: May be skipped, logged if deferred
- **Example**: OpenAPI docs, logging middleware, UI polish
- **When to Use**: Feature is "nice but not critical"

### Example Task List

Required Tasks

1. Implement authentication middleware 2. Create login endpoint 3. Create logout endpoint 4. Write unit tests for auth 5. Add input validation

Deferred Tasks (Phase 2)

6. Add OAuth2 integration

• Reason: OAuth provider not yet configured
• Follow-up: Implement after infrastructure setup

7. Add session caching

• Reason: Requires Redis evaluation
• Follow-up: Implement based on performance metrics

Nice-to-Have

8. Add two-factor authentication 9. Add authentication metrics dashboard

## Review Checklist

Before finalizing PRP:

- [ ] **Goal is clear and specific** - Can be understood without context
- [ ] **Success criteria are testable** - Each criterion has clear verification method
- [ ] **All file paths are explicit** - No "somewhere in..." references
- [ ] **Code snippets show actual patterns** - Include file path and line numbers
- [ ] **Gotchas include mitigations** - Don't just warn, provide solutions
- [ ] **Validation commands are executable** - Copy-paste ready
- [ ] **All tasks categorized** - Required/Deferred/Nice-to-Have explicit
- [ ] **Confidence score is honest** - Score reflects actual completeness

## Confidence Scoring

Rate each dimension 1-10:

### Context Completeness
- **10**: All file paths explicit, code snippets with line numbers, all documentation referenced
- **7**: Most context provided, some gaps acceptable
- **4**: Significant gaps, important details missing

### Implementation Clarity
- **10**: Pseudocode covers all cases, edge cases identified
- **7**: Main path clear, some edge cases may need discovery
- **4**: High-level only, implementation approach unclear

### Gotchas Documented
- **10**: All known pitfalls documented with mitigations
- **7**: Major gotchas documented, some minor ones may be missed
- **4**: Some gotchas mentioned, mitigations incomplete

### Validation Coverage
- **10**: All gates have executable commands, clear expectations
- **7**: Main validation commands provided, some gaps acceptable
- **4**: Incomplete validation gates, unclear expectations

### Overall Score Calculation
Average of all 4 dimensions.

**Decision Rules**:
- **9-10**: Ready for AI subagent execution (full autonomy)
- **7-8**: Ready for execution, some discovery expected
- **< 7**: Not ready, needs more research/context

## Creating ai_docs

If you discover new patterns during research, create ai_docs entries:

**Location**: `docs/blueprint/ai_docs/libraries/[library-name].md` or `docs/blueprint/ai_docs/project/patterns.md`

**Format**:

[Library Name] - [Pattern Name]

What

[One sentence description]

When to Use

[Specific use case]

Pattern

[Code example with explanation]

Gotchas

• [Gotcha 1]: [Mitigation]
• [Gotcha 2]: [Mitigation]

References

• Link to official docs

**Guidelines**:
- Keep under 200 lines
- Include code examples
- Document gotchas explicitly
- Make it searchable and reusable