code-prd

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:

1. ⏳ Not Started - Initial state, no work begun
2. 🔄 Implementing - Active work in progress (set at Phase 0 or when beginning substory)
3. ✅ 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):

1. Validate core PRD exists and is complete

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

3. 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:

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

2. Present configuration:

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

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

4. Run tests:

$test_cmd

5. 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:

1. Code Quality (readability, maintainability, complexity)
2. Architecture & Design (patterns, SOLID, consistency with core for expansions)
3. Security (auth, validation, injection prevention, secrets)
4. Performance (queries, caching, efficiency)
5. Testing Quality (coverage, edge cases, assertions)
6. 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]":

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

No PRD updates, no context management - just tests.

Blocker Handling

If blocked:

1. Mark substory as 🔄 with blocker note
2. Document in PRD
3. 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