name	code-prd
description	Build features when user wants to implement PRDs, write code for specs, or develop functionality. Works incrementally substory-by-substory with automatic testing and code review. Automatically loads PRD context to maintain consistency. Also writes standalone tests for any file.

Code PRD Implementation

Write production-quality code for PRD substories with automatic testing, code review, and iterative refinement until ready.

Communication Style: In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.

Philosophy

Substory-by-substory: Implement incrementally with clear status tracking (⏳ → 🔄 → ✅)
Phase-level approval: Auto-test and review each phase, get user approval before continuing
Auto-refinement: Run code-review internally, fix issues, re-review until satisfied
Context-aware: Load PRD context to maintain consistency (especially for expansions)
Flexible: Can implement full PRD OR write standalone tests for any file

When to Activate

This skill activates when user says things like:

"implement [feature/PRD]"
"build this feature"
"code this"
"develop [feature name]"
"start implementation"
"write code for [PRD/feature]"
"write tests for [file/feature]" (standalone test mode)

Substory Status Lifecycle

Critical: Substories follow this status lifecycle:

⏳ Not Started - Initial state, no work begun
🔄 Implementing - Active work in progress (set at Phase 0 or when beginning substory)
✅ Completed - Implementation, tests, and review complete

When to update status:

Phase 0: After configuration, mark first substory as "🔄 Implementing"
During work: Substory stays "🔄 Implementing" until fully done
After completion: Only mark "✅ Completed" when implementation, tests, and review all pass

UX Enhancements

This skill includes advanced UX features. For full implementation details, read references/ux-enhancements.md:

Learning Mode (explain approach before substories)
Smart PRD Discovery (auto-resume from last session)
PRD Health Check (validate quality before implementing)
Progress Visualization (visual progress bars)
Dependency Warnings (detect blockers early)
Smart Test Suggestions (complexity-based test plans)
Code Review Insights (trends and gamification)
Rollback Protection (auto-checkpoints at phases)
Context-Aware Expansion Suggestions (data-driven next steps)
Parallel Work Detection (merge conflict prevention)
Adaptive Difficulty (workflow speeds up as you improve)

See references/ux-enhancements.md for when and how to use each feature.

Implementation Workflow

Phase 0: Validate Prerequisites and Configure Session

FIRST: Check for CLAUDE.md

if [[ ! -f "CLAUDE.md" ]]; then
    echo "❌ ERROR: CLAUDE.md file not found in project root"
    echo "This workflow requires a CLAUDE.md file. To create: type /init"
    exit 1
fi

Configure session with Learning Mode:

✅ CLAUDE.md found
📋 Ready to implement

💡 Session Configuration:

Learning Mode: [Currently: ${learning_mode ? "ON" : "OFF"}]
  When ON: I'll explain my approach before each substory
  When OFF: I'll implement directly without explanations

Change Learning Mode? [yes/no/default: no]:

See references/ux-enhancements.md Section 1 for full Learning Mode implementation.

Mark first substory as "Implementing" once configuration complete and work begins.

Mode Detection

1. PRD Implementation Mode - User mentions PRD or says "implement"

Full workflow: phases → substories → auto-testing → review → approval

2. Standalone Test Mode - User says "write tests for [file/feature]"

Jump to Step 8, skip PRD workflow

Step 1: Load PRD, Context, and Project Conventions

Essential loading sequence:

# Ensure directory structure
mkdir -p .claude/prds/context .claude/prds/archive/context .claude/checkpoints

# Gitignore checkpoints
if ! grep -q "\.claude/checkpoints" .gitignore 2>/dev/null; then
    echo ".claude/checkpoints/" >> .gitignore
fi

# Load PRD
prd_content=$(cat "$prd_file")
claude_md=$(cat "CLAUDE.md")

# Load or init context
if context_exists "$prd_file"; then
    context=$(read_context "$prd_file")
else
    init_context "$prd_file"
fi

Smart PRD Discovery - If no PRD specified:

Check for in-progress PRD from last session (context files with recent timestamps)
Show resume prompt with progress summary
Offer to choose different PRD or create new

See built-in workflow for Smart PRD Discovery details (lines 205-278 of original).

Determine PRD Type (Core / Expansion / Task):

For Core PRDs:

Load CLAUDE.md for project conventions
Goal: Establish clean patterns for expansions

For Task PRDs:

Work through Implementation Checklist step-by-step
No phases/substories - checkbox completion

For Expansion PRDs (CRITICAL - AUTO-LOAD CORE):

Validate core PRD exists and is complete
Load comprehensive core context:
- Read core PRD file and context JSON
- Extract files_created, patterns, libraries, decisions
- Read actual implementation files to analyze patterns
- Document findings with specific code examples
Present findings before coding:

🔍 Core Implementation Analysis (AUTO-LOADED):

Core PRD: .claude/prds/YYYY-MM-DD-{feature}-core.md
Status: ✅ Complete

Implementation Files ([X] analyzed):
- [list files with descriptions]

Established Patterns ([Y] identified):
- [pattern name]: [description and examples]

Libraries: [Z] libraries
Architectural Decisions: [W] decisions

Code Analysis Insights:
- Naming conventions: [observed patterns]
- Error handling: [approach used]
- Validation: [approach used]

✅ Expansion will EXTEND these patterns consistently.

Step 2: Analyze Existing Architecture

Before writing code:

Explore existing code structure and patterns
Identify naming conventions
Locate similar features/components
Document findings from CLAUDE.md and codebase

Step 2a: PRD Health Check

Run automated quality analysis:

Check acceptance criteria (20 pts)
Check success metrics (15 pts)
Check security considerations (15 pts)
Check performance requirements (10 pts)
Check error handling (10 pts)
Check testing strategy (15 pts)
Check substories defined (15 pts)

Show health check with quality score:

🔍 PRD Health Check

Quality Score: ${score}/100 [Excellent ✅ / Good 👍 / Acceptable ⚠️ / Needs Improvement ❌]

[If score < 60:]
⚠️  PRD quality below threshold

Options:
1. 🔧 Fix issues now
2. ⏭️  Implement anyway
3. 📋 Show detailed recommendations

See built-in workflow for full health check implementation (lines 432-543 of original).

Step 3: Parse PRD and Create Implementation Plan

Parse for:

Phases and substories
Current status (⏳ / 🔄 / ✅)
Dependencies
Acceptance criteria

Show plan with Progress Visualization:

📋 Implementation Plan: [Feature Name]

Overall Progress: ░░░░░░░░░░ 0% (0/4 substories)

Phase 1: [Phase Name] (4 substories)
├─ ⏳ Substory 1.1: [Name] - Not Started
├─ ⏳ Substory 1.2: [Name] - Not Started
├─ ⏳ Substory 1.3: [Name] - Not Started
└─ ⏳ Substory 1.4: [Name] - Not Started

Ready to begin Phase 1? [yes/show-details/skip-to]

For resuming in-progress:

Overall Progress: ████████░░ 66% (2/3 complete)

Phase 1: [Phase Name]
├─ ✅ Substory 1.1 - Completed
├─ ✅ Substory 1.2 - Completed
└─ 🔄 Substory 1.3 - Implementing

Resume at Substory 1.3? [yes/restart-substory]

Step 4: Implement Phase (Substory-by-Substory)

For each substory:

Step 4.0: Learning Mode Explanation (If Enabled)

📚 See references/ux-enhancements.md Section 1

If enabled, explain approach before implementing.

Step 4.1: Dependency Warnings Check

⚠️ See references/ux-enhancements.md Section 2

Check for blockers: API keys, external services, migrations, dependencies.

Mark Substory Implementing

Update PRD:

🔄 Substory 1.1: [Name] - Implementing
  Started: YYYY-MM-DD HH:MM
  Current: [Brief status]

Update context:

set_current_phase "$prd_file" "Phase 1: Substory 1.1"

Write Code

For Core PRDs: Establish clean, simple patterns.

For Expansion PRDs (USE LOADED PATTERNS):

Follow established patterns exactly
Extend (don't replace) core code
Maintain naming/structure consistency
Use same libraries as core

Quality Requirements:

Follow CLAUDE.md conventions
Clean, readable code
Appropriate comments
Consistent naming (match core for expansions)
Proper error handling
Input validation
Appropriate logging

Track changes:

add_created_file "$prd_file" "src/models/user.model.ts"
add_decision "$prd_file" "[decision made]"
set_library "$prd_file" "[category]" "[library]"
set_pattern "$prd_file" "[pattern]" "[location/description]"

Mark Substory Complete

Update PRD:

✅ Substory 1.1: [Name] - Completed (YYYY-MM-DD)
  Files: [list files]
  Summary: [brief summary]

Show Progress

✅ Substory 1.1 complete!

📝 Files created/modified:
- [file list with descriptions]

📊 Progress: 1/4 substories (25% of Phase 1)

⏭️  Next: Substory 1.2 - [Name]

Continue to next substory until phase complete.

Step 4.9: Rollback Protection Checkpoint

💾 See references/ux-enhancements.md Section 3

Before each new phase, create automatic checkpoint with rollback script.

Step 5: Phase Complete - Auto-Test and Review Loop

When all substories in phase complete:

🎉 Phase 1 Complete: [Phase Name]

✅ Completed substories: [list]
📊 Phase Stats: [files, lines, patterns]

🧪 Now running testing and review...

Step 5a: Auto-Run Tests

🧪 See references/ux-enhancements.md Section 4 for Smart Test Suggestions

If testing disabled in CLAUDE.md:

ℹ️  Testing skipped (CLAUDE.md indicates no tests)
Proceeding to code review...

If testing enabled:

Identify framework (Jest, pytest, RSpec, Vitest, etc.)
- Check CLAUDE.md, package.json, requirements.txt, Gemfile
- Find test command and file patterns
- Analyze existing test patterns
Present configuration:

📊 Testing Framework: [Framework]
Test command: [command]
Test pattern: [pattern]
Coverage: [requirement from CLAUDE.md]

Write comprehensive tests:
- Unit tests for business logic
- Integration tests for interactions
- Cover all acceptance criteria
- Test happy paths, errors, edge cases
- Follow project test patterns
Run tests:

$test_cmd

Report results:

🧪 Tests Written and Executed:
✅ [X] tests passed
📊 Coverage: [Y]%
⏱️  Duration: [time]

If tests fail (and not skipped):

Show failures
Fix code
Re-run until passing

Step 5b: Auto-Run Code Review (Internal)

📋 See references/ux-enhancements.md Section 5 for Code Review Insights

Review Dimensions:

Code Quality (readability, maintainability, complexity)
Architecture & Design (patterns, SOLID, consistency with core for expansions)
Security (auth, validation, injection prevention, secrets)
Performance (queries, caching, efficiency)
Testing Quality (coverage, edge cases, assertions)
Project-Specific (CLAUDE.md standards, framework conventions)

Categorize findings:

🔴 Critical (must fix): Security vulnerabilities, data loss, crashes
🟠 Major (should fix): Performance issues, missing validation, pattern inconsistencies
🟡 Minor (nice to have): Style issues, refactoring opportunities
✅ Positive: Highlight good practices

Show summary:

📋 Code Review Complete:

🔴 Critical: 0
🟠 Major: 2
🟡 Minor: 5
✅ Positive: 8 things done well

[List major/critical issues with file:line, risk, fix]

Step 5c: Auto-Fix Issues

If critical/major issues found:

🔧 Fixing [N] issues automatically... (Iteration 1/3)

[Fix each issue, show progress]

Re-running review...

Auto-fix iterations:

Iteration 1: Auto-fix
Iteration 2: Auto-fix (if issues remain)
Iteration 3: Ask user for guidance, then fix

If issues remain after 3 iterations:

⚠️ Unable to resolve all issues after 3 iterations.

Options:
1. approve-with-issues - Continue anyway
2. manual-fix - You fix manually
3. redo-substory - Re-implement with different approach
4. get-help - Document blocker

Step 6: Phase Approval Gate

When review clean (no critical/major):

🎉 Phase 1 Ready for Approval!

📊 Summary:
✅ [X] substories completed
✅ [Y] tests passing ([Z]% coverage) [or "⚠️ Tests skipped"]
✅ Code review: No critical/major issues
📝 [N] files created/modified

Changes: [summary]
Patterns established: [list]

Approve Phase 1 and continue? [yes/show-changes/redo-phase/stop]

User options:

yes: Continue to next phase
show-changes: Show git diff
redo-phase: Re-implement
stop: Stop here

Step 6.5: Parallel Work Detection

🔍 See references/ux-enhancements.md Section 6

Before next phase, check for parallel work on main branch to prevent conflicts.

Step 7: Continuation or Completion

If more phases: Continue to Step 4

If all phases complete:

Detect git state for contextual next steps:

current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
base_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
on_main=false
has_changes=false

if [[ "$current_branch" == "main" ]] || [[ "$current_branch" == "master" ]] || [[ "$current_branch" == "$base_branch" ]]; then
    on_main=true
fi

if [[ -n $(git status --porcelain 2>/dev/null) ]]; then
    has_changes=true
fi

Show completion with context-aware options:

For CORE PRD:

🎉 Core PRD Complete!

✅ All phases implemented
📊 Core Stats: [files, tests, patterns]
🌱 Core foundation ready!

Context saved: .claude/prds/context/{prd}.json
(Auto-loaded when creating expansion PRDs)

💡 Next steps:

[Contextual options based on git state:]

[If on_main && has_changes:]
1. 🚀 Create pull request
2. 📋 Plan expansion
3. ✏️  Continue coding

[If !on_main && has_changes:]
1. 💾 Commit changes
2. 📋 Plan expansion
3. ✏️  Continue coding

[If !on_main && !has_changes:]
1. 🚀 Create pull request
2. 💾 Commit more changes
3. 📋 Plan expansion

[If on_main && !has_changes:]
**🎯 See references/ux-enhancements.md Section 7 for Context-Aware Expansion Suggestions**

1. 📋 Plan expansion:
   [Smart suggestions from code analysis]
2. ✏️  Start new feature
3. 🎯 Other

What would you like to do? [1/2/3 or describe]:

For EXPANSION PRD: Similar format with expansion-specific messaging.

Step 8: Standalone Test Mode (No PRD)

When user says "write tests for [file/feature]":

Identify target (specific files or feature area)
Analyze testing setup (framework, command, patterns from CLAUDE.md and existing tests)
Present test plan
Write comprehensive tests (unit, integration, following project patterns)
Run tests
Report results with coverage

No PRD updates, no context management - just tests.

Blocker Handling

If blocked:

Mark substory as 🔄 with blocker note
Document in PRD
Ask for resolution or skip to next non-blocked substory

Key Principles

This skill DOES:

Implement substory-by-substory with clear status tracking (⏳ → 🔄 → ✅)
Show progress after each substory
Auto-test and auto-review after each phase
Auto-fix critical/major issues (up to 3 iterations)
Ask for approval at phase boundaries
Update PRD and context automatically
Load core context for expansions automatically
Write standalone tests without PRD

This skill DOES NOT:

Auto-continue without approval
Auto-commit or auto-create PRs
Skip testing or review

Workflow:

Substories (⏳ → 🔄 → ✅) → Phase complete →
Auto-test → Auto-review → Auto-fix → Approval →
Continue or stop

Directory Structure

.claude/
├── prds/
│   ├── YYYY-MM-DD-feature-core.md
│   ├── context/
│   │   └── YYYY-MM-DD-feature-core.json
│   └── archive/
├── user-preferences.json (GITIGNORED)
└── checkpoints/ (GITIGNORED)

.gitignore additions:
.claude/user-preferences.json
.claude/checkpoints/

UX Enhancement Reference Map

At each workflow step, refer to references/ux-enhancements.md for full implementation:

Workflow Step	Enhancement	Section
Phase 0	Learning Mode	Section 1
Phase 0	Adaptive Difficulty	Section 8
Step 1	Smart PRD Discovery	Built-in
Step 2a	PRD Health Check	Built-in
Step 3	Progress Visualization	Built-in
Step 4.0	Learning Mode Explanation	Section 1
Step 4.1	Dependency Warnings	Section 2
Step 4.9	Rollback Protection	Section 3
Step 5a	Smart Test Suggestions	Section 4
Step 5b	Code Review Insights	Section 5
Step 6.5	Parallel Work Detection	Section 6
Step 7	Context-Aware Expansions	Section 7

Guidelines

Work incrementally (one substory at a time)
Track status clearly: ⏳ Not Started → 🔄 Implementing → ✅ Completed
Mark first substory "🔄 Implementing" after Phase 0 configuration
Always load PRD context and CLAUDE.md
For expansions: auto-load and analyze core context
Follow CLAUDE.md conventions religiously
Update PRD status after each substory
Update context with patterns/libraries/decisions
Auto-test after each phase
Auto-review and auto-fix
Get approval at phase boundaries
Reference references/ux-enhancements.md at callout steps

code-prd

Install Skill

SKILL.md