gh-navidemad-claude-code-plugins-prd-plugin/skills/code-prd/SKILL.md

name, description

name	description
code-prd	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.

UX Enhancements: This skill includes advanced UX features detailed in 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)

Philosophy

• Substory-by-substory: Implement incrementally with progress 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)
• Any request to implement, build, or code a feature or PRD

Implementation Workflow

Phase 0: Validate Prerequisites and Configure Session

FIRST: Check for CLAUDE.md

if [[ ! -f "CLAUDE.md" ]]; then
    cat <<EOF
❌ ERROR: CLAUDE.md file not found in project root

This workflow requires a CLAUDE.md file documenting your project conventions.

To create one, start a new Claude Code session and type:
  /init

Then describe your project, and Claude will help create CLAUDE.md.

Exiting...
EOF
    exit 1
fi

Check for Adaptive Difficulty settings:

# Load user skill level from context if exists
user_level="beginner"  # default
auto_approve_safe_changes=false
learning_mode=true  # default ON

if [[ -f ".claude/user-preferences.json" ]]; then
    user_level=$(jq -r '.skill_level // "beginner"' .claude/user-preferences.json)
    auto_approve_safe_changes=$(jq -r '.auto_approve_safe_changes // false' .claude/user-preferences.json)
    learning_mode=$(jq -r '.learning_mode // true' .claude/user-preferences.json)
fi

Show configuration prompt:

✅ 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

  Recommended for: Understanding patterns and decisions

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

If user says "yes":

Enable or disable Learning Mode?
1. 💡 Enable (explain approach for each substory)
2. ⚡ Disable (faster, direct implementation)
3. 🎯 Smart (only explain new patterns)

Choice [1/2/3]:

Save preference:

# Save to .claude/user-preferences.json (user-specific, gitignored)
mkdir -p .claude

# Ensure user-preferences.json is gitignored
if [[ -f ".gitignore" ]]; then
    if ! grep -q "\.claude/user-preferences\.json" .gitignore; then
        echo "" >> .gitignore
        echo "# Claude Code user-specific preferences (do not commit)" >> .gitignore
        echo ".claude/user-preferences.json" >> .gitignore
    fi
else
    cat > .gitignore <<'GITIGNORE'
# Claude Code user-specific preferences (do not commit)
.claude/user-preferences.json
GITIGNORE
fi

# Write user preferences
echo "{
  \"skill_level\": \"$user_level\",
  \"learning_mode\": $learning_mode,
  \"auto_approve_safe_changes\": $auto_approve_safe_changes,
  \"last_updated\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
}" > .claude/user-preferences.json

echo "✅ Preferences saved (local only, not committed to git)"

Mode Detection

Check user request:

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

   • Full workflow with phases, substories, auto-testing, review

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

   • Skip PRD, just write tests for specified files
   • Detect testing framework
   • Write comprehensive tests
   • Run tests
   • Done

For Standalone Test Mode, jump to Step 8 (Write Tests).

For PRD Implementation Mode, continue below:

Step 1: Load PRD, Context, and Project Conventions

First, ensure directory structure and load PRD:

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

# Ensure checkpoints are gitignored
if [[ -f ".gitignore" ]]; then
    if ! grep -q "\.claude/checkpoints" .gitignore; then
        echo ".claude/checkpoints/" >> .gitignore
    fi
fi

# Source context manager
source skills/shared/scripts/context-manager.sh

# Validate PRD file exists
if [[ ! -f "$prd_file" ]]; then
    echo "❌ ERROR: PRD file not found: $prd_file"
    exit 1
fi

# Read the PRD file
prd_content=$(cat "$prd_file")

# Read project conventions from CLAUDE.md
if [[ ! -f "CLAUDE.md" ]]; then
    echo "❌ ERROR: CLAUDE.md not found"
    exit 1
fi
claude_md=$(cat "CLAUDE.md")

# Load or initialize PRD context
if context_exists "$prd_file"; then
    context=$(read_context "$prd_file")
    echo "✅ Loaded existing context"
else
    context_file=$(init_context "$prd_file")
    context=$(read_context "$prd_file")
    echo "✅ Initialized new context"
fi

If no PRD specified - Smart PRD Discovery:

# Strategy 1: Check for in-progress PRD from last session
last_prd=""
last_timestamp=0

# Check context files for most recently updated in-progress PRD
for context_file in .claude/prds/context/*.json; do
    if [[ -f "$context_file" ]]; then
        # Get last updated timestamp
        timestamp=$(jq -r '.last_updated // 0' "$context_file" 2>/dev/null || echo 0)
        prd_file=$(basename "$context_file" .json)
        prd_path=".claude/prds/${prd_file}.md"

        # Check if PRD exists and is in progress
        if [[ -f "$prd_path" ]] && grep -q "Status.*In Progress" "$prd_path"; then
            if [[ $timestamp -gt $last_timestamp ]]; then
                last_timestamp=$timestamp
                last_prd=$prd_path
                last_context=$context_file
            fi
        fi
    fi
done

# Strategy 2: Check git log for recently committed PRD references
recent_prd=$(git log -10 --oneline 2>/dev/null | grep -o '.claude/prds/[^)]*\.md' | head -1)

# Strategy 3: Check recently modified files in .claude/prds/
recent_file=$(ls -t .claude/prds/*.md 2>/dev/null | head -1)

If found recent PRD in progress:

🔍 Detected context from your last session:

Working on: .claude/prds/2025-10-26-hello-world-core.md
Type: Core Feature
Status: Phase 1 - In Progress (2/3 substories complete)
Last worked: 2 hours ago

Completed:
✅ Substory 1.1: Basic MVC structure
✅ Substory 1.2: RESTful routing

Next up:
⏳ Substory 1.3: Integration tests

Continue where you left off? [yes/choose-different/new]:

If user says "choose-different" or no recent PRD found:

Available PRDs:

In Progress:
  1. 🔄 [Core] hello-world-core - Basic hello world feature
     Progress: ████████░░ 66% (2/3 substories)
     Last updated: 2 hours ago

Not Started:
  2. ⏸️  [Expansion] hello-world-personalized - Add name parameter
     Depends on: hello-world-core (not complete)

  3. ⏸️  [Task] setup-ci-cd - Configure GitHub Actions
     Estimated: 5 steps

Completed:
  4. ✅ [Core] auth-core - OAuth authentication
     Completed: 3 days ago
     (Move to archive? Type 'archive 4')

Which PRD? [1/2/3/4/new]:

Determine PRD Type: Check PRD frontmatter for:

• **Type:** Core Feature
• **Type:** Expansion
• **Type:** Task

For Core PRDs:

• Load CLAUDE.md for project conventions
• Load context file (patterns, libraries, decisions from previous sessions)
• Goal: Establish clean patterns that expansions will follow

For Task PRDs:

• Load CLAUDE.md for project conventions
• Work through Implementation Checklist sequentially
• No phases/substories - just step-by-step execution
• Update checkboxes as steps complete
• Goal: Complete technical task efficiently

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

Step 1: Validate core PRD exists and is complete:

# Extract core PRD path from "Builds On" field
core_prd=$(grep "Builds On:" "$prd_file" | sed 's/.*Builds On:.*\(docs\/prds\/[^)]*\).*/\1/')

# Validate core PRD exists
if [[ ! -f "$core_prd" ]]; then
    echo "❌ ERROR: Core PRD not found: $core_prd"
    echo "This expansion requires a completed core PRD."
    exit 1
fi

# Check core is marked complete
if ! grep -q "Status.*Complete" "$core_prd"; then
    echo "⚠️  WARNING: Core PRD is not marked complete"
    echo "Building expansions on incomplete cores may cause inconsistencies."
    echo "Continue anyway? [yes/no]"
fi

# Validate core context exists
core_context_file=".claude/prds/context/$(basename $core_prd .md).json"
if [[ ! -f "$core_context_file" ]]; then
    echo "⚠️  WARNING: Core context file not found: $core_context_file"
    echo "Context loading will be limited. Continue? [yes/no]"
fi

Step 2: Load and analyze core context comprehensively:

# Load CLAUDE.md for project conventions
claude_md=$(cat "CLAUDE.md")

# Read core PRD
core_prd_content=$(cat "$core_prd")

# Read core context file
core_context=$(cat "$core_context_file")

# Extract structured data from context
core_files=$(echo "$core_context" | jq -r '.files_created[]')
core_patterns=$(echo "$core_context" | jq -r '.patterns')
core_libraries=$(echo "$core_context" | jq -r '.libraries')
core_decisions=$(echo "$core_context" | jq -r '.architectural_decisions[]')
testing_framework=$(echo "$core_context" | jq -r '.testing_framework')

# Read and analyze each core implementation file
echo "📖 Analyzing core implementation..."
for file in $core_files; do
    if [[ -f "$file" ]]; then
        # Read file to understand:
        # - Class/function naming patterns
        # - Code organization and structure
        # - Error handling approaches
        # - Validation patterns
        # - API/interface design
        # - Data access patterns
    fi
done

Step 3: Document comprehensive findings:

🔍 Core Implementation Analysis (AUTO-LOADED):

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

Implementation Files ([X] files analyzed):
- path/to/model.ext - Data model with validations [describe key aspects]
- path/to/service.ext - Business logic service [describe key aspects]
- path/to/controller.ext - API endpoints [describe key aspects]
- path/to/repository.ext - Data access layer [describe key aspects]

Established Patterns ([Y] patterns identified):
1. [Pattern Name] - [Description]
   Location: [where used in core]
   Example: [specific code example or approach]

2. [Pattern Name] - [Description]
   Location: [where used in core]
   Example: [specific code example or approach]

Libraries in Use ([Z] libraries):
- [Library 1] ([Version]) - [Purpose in core implementation]
- [Library 2] ([Version]) - [Purpose in core implementation]

Architectural Decisions ([W] decisions):
1. [Decision]: [Rationale from context]
2. [Decision]: [Rationale from context]

Code Analysis Insights:
- Naming convention: [Observed pattern, e.g., "FeatureService", "FeatureRepository"]
- Error handling: [Approach, e.g., "Custom exception hierarchy with FeatureError base"]
- Validation: [Approach, e.g., "Joi schemas in validators/ directory"]
- Data access: [Pattern, e.g., "Repository pattern with TypeORM"]
- Testing: [Framework and approach, e.g., "Jest with 95% coverage requirement"]

Project Conventions (from CLAUDE.md):
- Tech stack: [List from CLAUDE.md]
- Architecture: [Pattern from CLAUDE.md]
- Code style: [Standards from CLAUDE.md]

✅ Expansion will EXTEND these patterns consistently.
   - Will modify existing files where appropriate
   - Will create new files following established naming
   - Will use same libraries and approaches
   - Will maintain architectural consistency

Step 2: Analyze Existing Architecture

Before writing code, understand the codebase:

# Explore existing architecture patterns
# Find similar features/components
# Identify naming conventions
# Locate relevant directories

Analyze:

• Existing code structure and patterns
• Current architecture (layering, separation of concerns)
• Naming conventions in use
• Where similar features are implemented
• Data layer patterns (if applicable - database, ORM, storage)
• API patterns (if applicable - REST, GraphQL, gRPC)

Document findings based on your project's CLAUDE.md and codebase analysis.

Step 2a: PRD Health Check

Before implementing, validate PRD quality:

# Run automated PRD quality analysis
prd_score=0
issues=()
warnings=()

# Check 1: Acceptance criteria defined
if grep -q "Acceptance Criteria:" "$prd_file"; then
    prd_score=$((prd_score + 20))
else
    issues+=("❌ Missing acceptance criteria")
fi

# Check 2: Success metrics defined
if grep -q "Success Criteria:" "$prd_file"; then
    prd_score=$((prd_score + 15))
else
    warnings+=("⚠️  Missing success metrics")
fi

# Check 3: Security considerations
if grep -qi "security\|auth\|permission\|sanitiz" "$prd_file"; then
    prd_score=$((prd_score + 15))
else
    warnings+=("⚠️  No security considerations documented")
fi

# Check 4: Performance requirements
if grep -qi "performance\|latency\|speed\|optimize" "$prd_file"; then
    prd_score=$((prd_score + 10))
else
    warnings+=("⚠️  No performance requirements")
fi

# Check 5: Error handling approach
if grep -qi "error\|exception\|failure\|fallback" "$prd_file"; then
    prd_score=$((prd_score + 10))
else
    warnings+=("⚠️  No error handling strategy")
fi

# Check 6: Testing strategy
if grep -qi "test\|testing\|coverage" "$prd_file"; then
    prd_score=$((prd_score + 15))
else
    warnings+=("⚠️  No testing strategy defined")
fi

# Check 7: Clear substories with phases
substory_count=$(grep -c "Substory" "$prd_file" || echo 0)
if [[ $substory_count -gt 0 ]]; then
    prd_score=$((prd_score + 15))
else
    issues+=("❌ No substories defined")
fi

Show health check results:

🔍 PRD Health Check

Analyzing: .claude/prds/2025-10-26-hello-world-core.md

Quality Score: ${prd_score}/100 $(if [[ $prd_score -ge 80 ]]; then echo "(Excellent ✅)"; elif [[ $prd_score -ge 60 ]]; then echo "(Good 👍)"; elif [[ $prd_score -ge 40 ]]; then echo "(Acceptable ⚠️)"; else echo "(Needs Improvement ❌)"; fi)

[If issues found:]
Critical Issues:
${issues[@]}

[If warnings found:]
Recommendations:
${warnings[@]}

[If prd_score >= 60:]
✅ PRD quality is sufficient for implementation

[If prd_score < 60:]
⚠️  PRD quality is below recommended threshold

Options:
1. 🔧 Fix issues now (pause to improve PRD)
2. ⏭️  Implement anyway (accept risks)
3. 📋 Show detailed recommendations

Choice [1/2/3/default: 2]:

If user chooses "3 - Show detailed recommendations":

📋 Detailed Recommendations

To improve this PRD to ${100 - prd_score}% better quality:

1. Add acceptance criteria for each substory
   Why: Defines "done" clearly, prevents scope creep
   How: For each substory, add checklist of verifiable outcomes

2. Define success metrics
   Why: Measurable goals help track feature effectiveness
   How: Add metrics like "response time < 200ms" or "95% test coverage"

3. Document security approach
   Why: Security considerations upfront prevent vulnerabilities
   How: Add section covering auth, input validation, data protection

[etc for each missing element]

Would you like to improve the PRD now? [yes/no/implement-anyway]

Step 3: Parse PRD and Create Implementation Plan

Parse PRD for:

• Phases and substories
• Current status (⏳ Not Started / 🔄 In Progress / ✅ Completed)
• Dependencies between substories
• Acceptance criteria for each

For new implementation:

• Start at Phase 1, Substory 1
• Show implementation plan
• Confirm approach with user

For continuation:

• Load current_phase from context
• Find last in-progress (🔄) or next pending (⏳)
• Show completion summary
• Confirm continuation point

Show plan with Progress Visualization:

📋 Implementation Plan: [Feature Name]

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

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

Context loaded: ✅
Patterns to follow: [list from context and CLAUDE.md]

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

For continuation (resuming in-progress PRD):

📋 Implementation Plan: Hello World Core

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

Phase 1: Core Foundation (3 substories)
├─ ✅ Substory 1.1: Basic MVC structure - Completed
├─ ✅ Substory 1.2: RESTful routing - Completed
└─ 🔄 Substory 1.3: Integration tests - In Progress

Context loaded: ✅
Patterns established: Rails MVC, Thin controller pattern
Files created so far: 3 files, 1 modified

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

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

For each substory in the phase:

Step 4.0: Learning Mode Explanation (If Enabled)

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

If Learning Mode is enabled, explain approach before implementing:

• Show what will be built and why
• Explain pattern choices and decisions
• List files to be created/modified
• Estimate complexity

Give user option to proceed, request more details, or adjust approach.

Step 4.1: Dependency Warnings Check

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

Before implementing substory, detect and warn about dependencies:

• Check for required API keys/credentials
• Verify external services are running
• Check for pending migrations
• Validate package dependencies

If blockers found, offer to resolve, skip, or continue anyway.

Mark Substory In Progress

Update PRD:

- 🔄 [1.1] User OAuth integration - In Progress
  - Current: Implementing OAuth flow
  - Started: YYYY-MM-DD HH:MM

Update context:

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

Write Code

For Core PRDs: Establish clean, simple patterns that will be extended later.

For Expansion PRDs (CRITICAL - USE LOADED PATTERNS):

• Reference loaded core implementation files
• Follow established patterns exactly
• Extend, don't replace core code
• Maintain consistency in naming, structure, and approach
• Use same libraries/services as core

Follow project conventions from CLAUDE.md and established patterns from context.

• For expansions: Extend core code following established patterns

Quality Requirements:

• Follow project conventions (CLAUDE.md, .editorconfig, linting)
• Write clean, readable code
• Add comments for complex logic
• Use consistent naming (especially in expansions - match core naming)
• Handle errors properly
• Validate inputs
• Log appropriately

Track files created/modified:

# Add to context
add_created_file "$prd_file" "src/models/user.model.ts"
add_created_file "$prd_file" "src/services/oauth.service.ts"

Track decisions made:

# If using a new library or pattern
add_decision "$prd_file" "[Your architectural decision]"
set_library "$prd_file" "[category]" "[library name]"
set_pattern "$prd_file" "[pattern name]" "[pattern location/description]"

Mark Substory Complete

Update PRD:

- ✅ [1.1] User OAuth integration - Completed (YYYY-MM-DD)
  Files: src/models/user.model.ts, src/services/oauth.service.ts
  Summary: Implemented OAuth flow with provider support

Show Progress After Each Substory

✅ Substory 1.1 complete!

📝 Files created/modified:
- src/models/user.model.ts (User model with OAuth fields)
- src/services/oauth.service.ts (OAuth service)
- src/dto/oauth-response.dto.ts (Response DTO)

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

⏭️  Next: Substory 1.2 - OAuth callback handler

Continue to next substory automatically until phase is complete.

Step 4.9: Rollback Protection Checkpoint

💾 See references/ux-enhancements.md Section 3 for full implementation

Before starting each new phase, create automatic checkpoint:

• Save git state (diffs, status, commit hash)
• Backup PRD and context files
• Create rollback script
• Auto-add to .gitignore

Show checkpoint confirmation with rollback instructions.

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

When all substories in a phase are complete:

🎉 Phase 1 Complete: [Phase Name]

✅ Completed substories:
- [1.1] User OAuth integration
- [1.2] OAuth callback handler
- [1.3] Token management
- [1.4] Account linking

📊 Phase Stats:
- Files: 8 files created/modified
- Lines: +350 lines
- Patterns: Service layer pattern established

🧪 Now running testing and review...

Step 5a: Auto-Run Tests

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

Before writing tests, analyze code complexity and suggest test strategy:

• Calculate cyclomatic complexity
• Count public methods and edge cases
• Recommend test coverage level (minimal/standard/comprehensive)
• Let user choose or customize test plan

Check if testing is applicable:

# Read CLAUDE.md for testing info
if grep -qi "no tests\|testing: none\|tests: n/a" CLAUDE.md; then
    testing_disabled=true
fi

If testing is disabled in CLAUDE.md:

ℹ️  Testing skipped (CLAUDE.md indicates no tests for this project)

Proceeding to code review...

If testing is enabled, analyze project testing setup comprehensively:

Step 1: Identify testing framework and conventions:

# Check CLAUDE.md for testing info
testing_info=$(grep -A 10 -i "testing\|test" CLAUDE.md)

# Detect testing framework from multiple sources:
# 1. CLAUDE.md explicit mention
# 2. package.json/requirements.txt dependencies
# 3. Existing test file patterns
# 4. Test configuration files

# Common framework detection:
if grep -q "jest" package.json 2>/dev/null; then
    framework="Jest"
    test_pattern="**/*.test.ts"
elif grep -q "pytest" requirements.txt 2>/dev/null; then
    framework="pytest"
    test_pattern="**/test_*.py"
elif grep -q "rspec" Gemfile 2>/dev/null; then
    framework="RSpec"
    test_pattern="**/spec/**/*_spec.rb"
elif grep -q "vitest" package.json 2>/dev/null; then
    framework="Vitest"
    test_pattern="**/*.test.ts"
fi

# Find test command from package.json, Makefile, or CLAUDE.md
if [[ -f "package.json" ]]; then
    test_cmd=$(jq -r '.scripts.test // empty' package.json)
elif [[ -f "Makefile" ]]; then
    test_cmd=$(grep "^test:" Makefile | cut -d':' -f2 | xargs)
fi

# Examine existing test files for patterns
existing_tests=$(find . -name "*test*" -o -name "*spec*" | head -5)

Step 2: Analyze existing test patterns:

📊 Testing Framework Detected: [Framework]

Test Configuration:
- Framework: [Framework and version]
- Test pattern: [File pattern, e.g., "*.test.ts"]
- Test command: [Command, e.g., "npm test"]
- Coverage tool: [Tool if detected, e.g., "Istanbul"]

Existing Test Patterns (from analysis):
- Test file location: [Pattern, e.g., "__tests__/" or "spec/"]
- Naming convention: [Pattern, e.g., "feature.test.ts" or "feature_spec.rb"]
- Test structure: [Describe/it, test/expect, etc.]
- Mocking approach: [Library and pattern used]
- Setup/teardown: [How tests are initialized]

Conventions from CLAUDE.md:
- Coverage requirement: [E.g., ">= 90%"]
- Test types required: [Unit, integration, e2e]
- Mock strategy: [Real vs mocked dependencies]

Step 3: Write comprehensive tests following established patterns:

• Unit tests for core logic (business logic, utilities, domain models)
• Integration tests for component interactions
• Coverage for all acceptance criteria from substories
• Test cases:
  • Happy paths (expected successful flows)
  • Error scenarios (validation failures, exceptions)
  • Edge cases (boundary conditions, null/empty values)
  • Business rule validation
• Follow project conventions:
  • Match file naming and location patterns
  • Use same test structure and assertions
  • Follow mocking strategy from existing tests
  • Match code style and organization

Step 4: Update context with testing info:

# Save testing framework for future reference
update_context "$prd_file" "testing_framework" "$framework"
update_context "$prd_file" "test_command" "$test_cmd"
update_context "$prd_file" "test_pattern" "$test_pattern"

Run tests:

# Identify test command from CLAUDE.md or project config
# Execute tests
# Capture results

# If test command fails or not found:
if [[ $test_exit_code -ne 0 ]] && [[ "$test_output" == *"command not found"* ]]; then
    cat <<EOF
⚠️  Warning: Unable to run tests

Test command failed or not found. Possible reasons:
- Test command not configured in CLAUDE.md
- Dependencies not installed
- Test framework not set up

Skipping test execution. Please verify tests manually.

Proceeding to code review...
EOF
    tests_skipped=true
fi

If tests run successfully:

• Report results with pass/fail counts and coverage if available

Report results:

🧪 Tests Written and Executed:

✅ [X] tests passed
📊 Coverage: [Y]%
⏱️  Duration: [time]

Test breakdown:
- [Test type 1]: [count] tests
- [Test type 2]: [count] tests

All acceptance criteria verified!

If tests fail (and tests weren't skipped):

• Show failures
• Fix code
• Re-run tests
• Loop until all tests pass

If tests were skipped:

• Continue to code review without test results
• Note in review summary that tests were not executed

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

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

Enhanced code review with trends, gamification, and achievements:

• Track quality score trends across substories
• Show improvement/regression in each dimension
• Unlock achievements for consistent quality
• Provide focus areas for next substory

Run comprehensive internal code review analysis:

Review Dimensions:

1. Code Quality:

   • Readability (clear naming, appropriate comments)
   • Maintainability (DRY, single responsibility)
   • Complexity (cyclomatic complexity, nesting depth)
   • Code organization and structure

2. Architecture & Design:

   • Design patterns (match established patterns from context)
   • SOLID principles adherence
   • Separation of concerns
   • Dependency management
   • For Expansions: Consistency with core implementation

3. Security:

   • Authentication and authorization
   • Input validation and sanitization
   • SQL injection prevention
   • XSS prevention
   • Secrets management (no hardcoded credentials)
   • Data exposure (sensitive data handling)

4. Performance:

   • Database query optimization (N+1 queries, indexes)
   • Caching strategy
   • Algorithm efficiency
   • Resource management (connections, memory)
   • Async/await usage (if applicable)

5. Testing Quality:

   • Coverage of acceptance criteria
   • Edge case coverage
   • Meaningful test assertions
   • Test maintainability
   • Mock appropriateness

6. Project-Specific (from CLAUDE.md and context):

   • Tech stack best practices
   • Framework conventions
   • Coding standards and style
   • For Expansions: Pattern consistency with core

Categorize findings by severity:

• 🔴 Critical (Must fix before approval):

  • Security vulnerabilities
  • Data loss risks
  • Breaking changes without migration
  • Crashes or fatal errors

• 🟠 Major (Should fix):

  • Performance issues
  • Missing validation
  • Poor error handling
  • Pattern inconsistencies (especially in expansions)
  • Missing tests for critical paths

• 🟡 Minor (Nice to have):

  • Code style inconsistencies
  • Missing edge case tests
  • Refactoring opportunities
  • Documentation improvements

• ✅ Positive (Done well):

  • Highlight good patterns
  • Acknowledge thorough testing
  • Note security best practices
  • Recognize clear, maintainable code

Show review summary:

📋 Code Review Complete:

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

Major issues:
1. [src/controllers/users.controller.ts:23] Missing pagination on list endpoint
   Risk: Could return thousands of records, causing performance issues
   Fix: Add pagination with skip/take or cursor-based pagination

2. [src/repositories/user.repository.ts:45] Missing database index on (oauth_provider, oauth_uid)
   Risk: Slow queries when looking up OAuth users
   Fix: Add composite index in schema migration

Minor suggestions:
- [src/services/oauth.service.ts:12] Extract magic number to constant
- [src/utils/validators.ts:34] Consider adding input sanitization
- ...

✅ Excellent work on:
- Clear separation of concerns with service layer
- Comprehensive error handling
- Consistent naming conventions
- Good test coverage (94%)

Step 5c: Auto-Fix Issues (If Any)

If critical or major issues found:

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

Fixing issue 1: Adding pagination to users endpoint...
✅ Fixed src/controllers/users.controller.ts

Fixing issue 2: Adding database index...
✅ Updated database schema with composite index

Re-running code review to verify fixes...

Re-run review:

📋 Re-Review Complete:

🔴 Critical: 0
🟠 Major: 0 (all fixed!)
🟡 Minor: 5
✅ Positive: 10 things done well

All critical and major issues resolved!

If still has critical/major issues after iteration 1:

• Continue to iteration 2 with auto-fix

If still has critical/major issues after iteration 2:

• Ask user for guidance:

🔧 Auto-fix iteration 2/3 complete, but issues remain:

🔴 Critical: 1
🟠 Major: 1

Remaining issues:
1. [Critical] [file:line] Issue description
   Current approach tried: [what was attempted]

2. [Major] [file:line] Issue description
   Current approach tried: [what was attempted]

💡 Need your input for final iteration (3/3):
- Do you have additional context about these issues?
- Any specific approach you'd like me to try?
- Alternative libraries or patterns to consider?

Your guidance: [user input]

After receiving user guidance:

• Apply user suggestions in iteration 3
• Re-run review
• Report final results

If still has critical/major issues after iteration 3:

• Stop auto-fixing
• Show detailed issue summary
• Provide options:

⚠️ Unable to resolve all issues after 3 iterations.

Remaining issues:
🔴 Critical: X
🟠 Major: Y

Options:
1. **approve-with-issues** - Continue anyway, fix in next phase/PR review
2. **manual-fix** - You'll fix manually, then continue
3. **redo-substory** - Re-implement substory with different approach
4. **get-help** - Pause and document blocker

What would you like to do? [1/2/3/4]

Step 6: Phase Approval Gate

When review is complete and clean (no critical/major issues):

🎉 Phase 1 Ready for Approval!

📊 Summary:
✅ 4 substories completed
✅ 23 tests passing (94% coverage) [or "⚠️ Tests skipped - manual verification needed"]
✅ Code review: No critical/major issues
📝 8 files created/modified
⏱️  Duration: ~45 minutes

Changes:
- User OAuth integration with validations
- OAuth callback endpoint
- Token management service
- Account linking logic

Patterns established:
- Service layer for business logic
- RESTful API structure
- JWT token management

Context updated: .claude/context/{prd-name}.json
PRD updated with completion status

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

User options:

• yes: Mark phase complete, continue to next phase (if exists)
• show-changes: Show detailed git diff
• redo-phase: Re-implement phase with different approach
• stop: Stop here, don't continue to next phase

If user approves ("yes"):

# Mark phase complete in context
mark_phase_complete "$prd_file" "Phase 1"

# Update PRD
- ✅ Phase 1: Core Foundation - Completed (YYYY-MM-DD)

# Continue to next phase or finish

Step 6.5: Parallel Work Detection

🔍 See references/ux-enhancements.md Section 6 for full implementation

Before continuing to next phase, check for parallel work on main branch:

• Fetch latest from remote
• Compare changed files between branches
• Identify potential conflicts
• Show risk level and affected substories

If conflicts detected, offer to merge now, continue anyway, or coordinate with team.

Step 7: Continuation or Completion

If more phases exist:

• Show next phase plan
• Continue to Step 4 for next phase
• Repeat: Implement → Test → Review → Fix → Approve

If all phases complete:

For CORE PRD:

First, detect git state to provide contextual next steps:

# Detect current git branch
current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
base_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# Check if on main/master
on_main=false
if [[ "$current_branch" == "main" ]] || [[ "$current_branch" == "master" ]] || [[ "$current_branch" == "$base_branch" ]]; then
    on_main=true
fi

# Check for uncommitted changes
has_changes=false
if [[ -n $(git status --porcelain 2>/dev/null) ]]; then
    has_changes=true
fi

Then show contextual completion message:

🎉 Core PRD Complete!

✅ All phases implemented and tested:
- Phase 1: Core Foundation (3 substories)

📊 Core Stats:
- Files created: 3 files
- Files modified: 1 file
- Tests: 2 tests, 3 assertions, 100% passing
- Patterns established:
  * Rails MVC structure
  * Thin controller pattern
  * RESTful routing
  * Minitest integration testing
  * frozen_string_literal pragma

🌱 Core foundation is ready!

Context saved: .claude/prds/context/2025-10-26-hello-world-core.json
This context will be auto-loaded when creating expansion PRDs.

💡 Next steps:

[If on_main == true && has_changes == true:]
**Git Status:** On main branch with uncommitted changes

Choose an option or type your own:
1. 🚀 Create pull request (creates feature branch, commits, pushes, opens PR)
2. 📋 Plan expansion (create expansion PRD to add more features)
3. ✏️  Continue coding (keep working on this branch)

[If on_main == false && has_changes == true:]
**Git Status:** On branch '${current_branch}' with uncommitted changes

Choose an option or type your own:
1. 💾 Commit changes (creates commit on current branch)
2. 📋 Plan expansion (create expansion PRD to add more features)
3. ✏️  Continue coding (keep working without committing)

[If on_main == false && has_changes == false:]
**Git Status:** On branch '${current_branch}' - ready to ship

Choose an option or type your own:
1. 🚀 Create pull request (push branch and open PR to ${base_branch})
2. 💾 Commit more changes (continue working on branch)
3. 📋 Plan expansion (create expansion PRD to add more features)

[If on_main == true && has_changes == false:]
**Git Status:** On main branch - all changes committed

**🎯 See references/ux-enhancements.md Section 7 for Context-Aware Expansion Suggestions**

Analyze core implementation for smart expansion suggestions:
- Check "Out of Scope" section from PRD
- Find TODO comments in implemented files
- Analyze data model for missing relationships
- Rank by effort, impact, and dependencies

Choose an option or type your own:
1. 📋 Plan expansion (create expansion PRD to add more features):
   [Smart suggestions based on code analysis:]
   - Personalized greeting (accept name parameter)
   - Styling with CSS/Tailwind
   - Interactive form version
   - API endpoint version (JSON response)
2. ✏️  Start new feature (plan a different PRD)
3. 🎯 Other (describe what you'd like to do)

What would you like to do? [1/2/3 or type your request]:

For EXPANSION PRD:

First, detect git state (same as Core PRD), then show contextual completion:

🎉 Expansion Complete: [Expansion Name]

✅ All phases implemented and tested:
- Phase 1: [Expansion Name] (3 substories)

📊 Expansion Stats:
- Core files extended: 3
- New files created: 5
- Tests: 18 tests, 93% coverage
- Followed core patterns: ✅

Extended core with:
- [New functionality 1]
- [New functionality 2]

Context updated: .claude/prds/context/2024-10-25-invoice-{expansion}.json

💡 Next steps:

[If on_main == true && has_changes == true:]
**Git Status:** On main branch with uncommitted changes

Choose an option or type your own:
1. 🚀 Create pull request (creates feature branch, commits, pushes, opens PR)
2. 📋 Plan another expansion (add more features to core)
3. ✏️  Continue coding (keep working on this branch)

[If on_main == false && has_changes == true:]
**Git Status:** On branch '${current_branch}' with uncommitted changes

Choose an option or type your own:
1. 💾 Commit changes (creates commit on current branch)
2. 📋 Plan another expansion (add more features to core)
3. ✏️  Continue coding (keep working without committing)

[If on_main == false && has_changes == false:]
**Git Status:** On branch '${current_branch}' - ready to ship

Choose an option or type your own:
1. 🚀 Create pull request (push branch and open PR to ${base_branch})
2. 💾 Commit more changes (continue working on branch)
3. 📋 Plan another expansion (add more features to core)

[If on_main == true && has_changes == false:]
**Git Status:** On main branch - all changes committed

Choose an option or type your own:
1. 📋 Plan another expansion (continue building on core)
2. ✏️  Start new feature (plan a different PRD)
3. 🎯 Other (describe what you'd like to do)

What would you like to do? [1/2/3 or type your request]:

Handling User Response:

The user can respond in three ways:

1. Select numbered option: "1" or "2" or "3"
2. Type natural language: "I want to add authentication" or "let's create a PR"
3. Use skill keywords: "ship", "plan", "implement"

Map responses to actions:

# If user selects option 1-3, map to the corresponding action
# If user types natural language, interpret intent:
#   - Words like "commit", "save", "ship" → trigger publish skill
#   - Words like "pr", "pull request", "merge" → trigger publish skill in PR mode
#   - Words like "plan", "expansion", "add feature" → trigger plan-prd skill
#   - Otherwise, treat as continuation of conversation

Step 8: Standalone Test Mode (No PRD)

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

Step 1: Identify and validate target:

# Specific files mentioned
if [[ -f "$target_file" ]]; then
    target_files=("$target_file")
else
    # Feature area - find related files
    target_files=$(find . -name "*$feature*" -type f ! -path "*/test/*" ! -path "*/spec/*")
fi

# Validate files exist
if [[ ${#target_files[@]} -eq 0 ]]; then
    echo "❌ ERROR: No files found for: $target"
    exit 1
fi

echo "📋 Found ${#target_files[@]} files to test"

Step 2: Comprehensive testing setup analysis:

# Read CLAUDE.md for testing framework and conventions
testing_info=$(grep -A 10 -i "testing\|test" CLAUDE.md)

# Detect framework (same logic as Phase implementation)
# - Check package.json, requirements.txt, Gemfile
# - Identify test command
# - Find test file patterns

# Analyze existing test files
existing_tests=$(find . -name "*test*" -o -name "*spec*" | head -5)

# For each existing test file, analyze:
# - File structure and organization
# - Test naming patterns
# - Assertion style
# - Mocking patterns
# - Setup/teardown approach

Step 3: Present testing plan:

📊 Testing Setup Detected:

Framework: [Framework name]
Test command: [Command to run tests]
Test file pattern: [Where to place tests]

Files to test ([X] files):
- path/to/file1.ext - [Brief description of what it does]
- path/to/file2.ext - [Brief description of what it does]

Test plan:
- Unit tests: [Estimated count] tests for [specific areas]
- Integration tests: [If applicable]
- Coverage goals: [From CLAUDE.md or project standard]

Proceeding with test generation...

Step 4: Analyze implementation files deeply:

# For each target file, analyze:
# - Public API (exported functions, classes, methods)
# - Business logic and algorithms
# - Error handling paths
# - Input validation
# - Edge cases and boundary conditions
# - Dependencies and interactions

Step 5: Write comprehensive tests following patterns:

• Unit tests for:

  • Each public method/function
  • Business logic and calculations
  • Validation rules
  • Error handling
  • Edge cases (null, empty, boundary values)

• Integration tests (if applicable):

  • Component interactions
  • Database operations
  • External service calls
  • Full feature workflows

• Follow established patterns:

  • Match test file naming and location
  • Use same test structure (describe/it, test/expect)
  • Follow mocking strategy from existing tests
  • Match assertion style and organization
  • Include setup/teardown as needed

Step 6: Run tests and verify:

# Run test command
$test_cmd

# Capture results:
# - Pass/fail count
# - Coverage percentage
# - Any failures or errors

Step 7: Report comprehensive results:

✅ Tests written for [file/feature]

📝 Test files created:
- tests/unit/feature.test.ts (15 tests)
  * Happy path scenarios: 5 tests
  * Error handling: 4 tests
  * Edge cases: 6 tests
- tests/integration/feature-flow.test.ts (8 tests)
  * End-to-end workflows: 8 tests

🧪 Test results:
✅ 23/23 tests passing
📊 Coverage:
  - Overall: 96% (+12% from baseline)
  - Branches: 94%
  - Functions: 100%
  - Lines: 96%

⏱️  Duration: 2.3s

Test breakdown:
- Unit tests: 15/15 passing
- Integration tests: 8/8 passing

All acceptance criteria verified ✅
Done!

Important: No PRD updates, no context management, just comprehensive tests following project patterns.

Blocker Handling

If implementation is blocked:

1. Mark substory as 🔄 with blocker note
2. Document blocker in PRD:

   - 🔄 [1.2] OAuth callback handler - Blocked
     - Blocker: Need OAuth credentials from PM
     - Waiting for: Client IDs and secrets
   

3. Ask user for resolution or skip to next non-blocked substory
4. Suggest workarounds if possible

Key Principles

This skill DOES:

• Implement code substory-by-substory
• Show progress after each substory
• Auto-run tests after each phase
• Auto-run code review after each phase
• Auto-fix critical/major issues
• Ask for approval at phase boundaries
• Update PRD with status automatically
• Update context with patterns/decisions automatically
• Load core context for expansions automatically
• Write standalone tests without PRD

This skill DOES NOT:

• Auto-continue to next phase without approval
• Auto-commit changes (that's "ship" skill's job)
• Auto-create PRs (that's "ship" skill's job)
• Skip testing or review
• Hide review findings from user

Workflow:

Implement substories → Show progress → Phase complete →
Auto-test → Auto-review → Auto-fix → Ask approval →
Continue or stop

Directory Structure

The skill works with this directory structure:

.claude/
├── prds/
│   ├── YYYY-MM-DD-feature-core.md              # Active PRD files
│   ├── YYYY-MM-DD-feature-expansion.md
│   ├── context/                                 # Active context files
│   │   ├── YYYY-MM-DD-feature-core.json
│   │   └── YYYY-MM-DD-feature-expansion.json
│   └── archive/                                 # Manual archival (user responsibility)
│       ├── old-feature.md                       # Archived PRD
│       └── context/
│           └── old-feature.json                 # Archived context
├── user-preferences.json                        # User-specific settings (GITIGNORED)
└── checkpoints/                                 # Rollback protection (GITIGNORED)
    └── phase-1-20251026-143022/
        ├── git-diff.patch
        ├── prd.md
        └── rollback.sh

.gitignore additions:
# Claude Code user-specific files (do not commit)
.claude/user-preferences.json
.claude/checkpoints/

Important Notes:

• PRDs and context files: Committed to git (team-shared)
• User preferences: Local only, auto-gitignored (personal settings)
• Checkpoints: Local only, auto-gitignored (temporary rollback points)
• Archive folder: When archiving, move both .md and .json files to maintain the pair

UX Enhancement Reference Map

This skill includes advanced UX features. At each workflow step, refer to references/ux-enhancements.md:

Workflow Step	UX Enhancement	Section
Phase 0	Learning Mode Toggle	Section 1
Phase 0	Adaptive Difficulty Check	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

When to read references/ux-enhancements.md:

• At workflow step callouts (📚 🧪 📋 💾 🔍 🎯 markers)
• When user requests specific feature (e.g., "enable learning mode")
• To understand full implementation details for any enhancement

Guidelines

• Work incrementally (one substory at a time)
• Always load PRD context and CLAUDE.md at start
• For expansions: auto-load core context and files
• Always analyze existing architecture before coding
• Follow project conventions from CLAUDE.md and established patterns religiously
• Update PRD status after each substory
• Update context with patterns/libraries/decisions
• Auto-test after each phase (not per substory)
• Auto-review after tests pass
• Auto-fix critical/major issues
• Get approval at phase boundaries
• Track files created in context
• Communicate clearly and frequently
• Handle blockers gracefully
• Support standalone test mode
• Reference references/ux-enhancements.md at callout steps for full feature implementation