Prd Driven Development

PRD-Driven Development Workflow

This skill provides a complete workflow for building software applications from Product Requirements Documents (PRDs) through structured task execution and test auditing, following enterprise-grade development practices with built-in quality gates, dependency management, and traceability.

How to Use This Skill

Invocation Method

This skill contains a complete 6-phase workflow for PRD-driven development. The workflow phases are built into the skill itself and don't require separate slash command files.

To use this skill:

1. Invoke the skill once:

   skill: prd-driven-development
   

2. Then use natural language to trigger workflow phases:

   • "Import PRDs from specs/features.md"
   • "Create a PRD for user authentication feature"
   • "Extend PRD-0001 with OAuth authentication"
   • "Generate tasks from prds/0001-prd-auth.md"
   • "Process task list tasks/tasks-0001-prd-auth.md"
   • "Audit tests for completed features"
   • "Generate status report"

Command Notation in This Documentation

Throughout this skill documentation, you'll see commands referenced like:

@import-prds <PATH_TO_FEATURES_FILE>
@create-prd <FEATURE_DESCRIPTION|PATH>
@generate-tasks <PATH_TO_PRD_FILE>

Important: These are workflow phase triggers, NOT separate slash command files. The @ notation is just a documentation convention to clearly mark workflow phases.

You invoke them by:

• ✅ Natural language after invoking the skill: "Import PRDs from specs/features.md"
• ✅ Explicit phrasing: "Using Phase 1, import PRDs from specs/features.md"
• ❌ NOT as slash commands: /import-prds (these files don't exist)

Integration with Slash Commands

This skill works alongside existing slash commands:

• Skill Workflow → Creates PRDs, generates task lists, manages dependencies
• Slash Commands (@code, @test, @debug, @ask) → Recognize and update skill outputs (PRD files, task files)

Example Integration:

skill: prd-driven-development
# Creates PRD and task files

@code implement feature X
# Recognizes task file and updates it automatically

@test add coverage for authentication
# Adds tests and updates task completion status

Prerequisites

CLAUDE.md Architecture Baseline (REQUIRED)

All commands require a CLAUDE.md file at the repository root containing or linking to:

• System architecture and service boundaries
• Tech stack (languages, frameworks, versions)
• Data stores, migrations, and messaging
• Testing strategy and quality gates
• CI/CD and environments
• Feature flags and rollout practices

Bootstrap Process (First-Time Setup):

If CLAUDE.md is missing, the skill will automatically:

1. Check if CLAUDE.md.template exists at root
2. Copy it to CLAUDE.md
3. Guide you through filling required sections interactively:
   • Tech stack (languages/frameworks - detect from package.json, requirements.txt, go.mod, etc.)
   • Testing strategy (frameworks - suggest based on detected stack)
   • Data stores (databases - detect from dependencies)
   • Architecture type (monolith/microservices/serverless)
4. Mark template sections that need your input with [TODO: Fill this]
5. Save the populated CLAUDE.md

You can also manually run: "Create CLAUDE.md from template and help me fill required sections"

If neither file exists: The skill will generate a basic CLAUDE.md with detected stack information and placeholders.

Testing Requirements Hierarchy (CRITICAL)

CLAUDE.md is the authoritative source for testing requirements:

1. Read CLAUDE.md Testing Strategy section FIRST

2. Respect explicit exclusions:

   • If CLAUDE.md says "No unit tests" → Do NOT generate unit tests
   • If CLAUDE.md says "No integration tests" → Do NOT generate integration tests
   • If CLAUDE.md says "No E2E tests" → Do NOT generate E2E tests

3. If CLAUDE.md is silent, has template text, or Testing Strategy section is incomplete:

   ⚠️ Default Assumption: Testing is REQUIRED

   Apply test requirements based on PRD complexity:

   simple complexity:

   • Unit tests: For core business logic only
   • Integration tests: Optional (only if API or database involved)
   • E2E tests: Optional (only if frontend-backend interaction exists)

   standard complexity (DEFAULT):

   • Unit tests: REQUIRED for all FRs involving business logic, validation, utilities
   • Integration tests: REQUIRED for all FRs involving APIs, database operations, service integration
   • E2E tests: AUTOMATIC for frontend-backend features (login, registration, CRUD, forms, real-time, chatbots)

   complex complexity:

   • Unit tests: REQUIRED for all FRs
   • Integration tests: REQUIRED for all FRs
   • E2E tests: REQUIRED when applicable (all user-facing frontend-backend flows)

   Important: When CLAUDE.md Testing Strategy is incomplete, the workflow will:

   • Prompt: "CLAUDE.md Testing Strategy has template text. Applying defaults: unit + integration + E2E (auto-detect for UI features). Continue? (yes/customize)"
   • Allow customization before proceeding
   • Update CLAUDE.md with chosen strategy

   Never skip tests due to difficulty - invest significant effort in making tests work (see Escalation Paths section below)

Lightweight Mode Triggers (automatically use simple complexity):

• Bug fixes that don't add new functionality
• Configuration changes (env vars, feature flags, settings)
• Documentation updates
• Infrastructure scripts
• Database schema changes ONLY (no business logic)

Examples:

✅ CLAUDE.md says: "Unit: Jest (required), Integration: Supertest (required), E2E: None (infrastructure not available)" → Skill generates unit + integration only, NO E2E tests

✅ CLAUDE.md says: "Unit: pytest, Integration: TestContainers, E2E: Playwright for critical flows" → Skill generates all three test types with diligence

✅ CLAUDE.md says: "Testing: TBD" or has generic template text → Skill applies default requirements (unit + integration mandatory, E2E for UI-backend)

Never override CLAUDE.md explicit requirements.

Global Standards

Define in CLAUDE.md or linked docs:

• Performance SLO/SLIs, availability targets
• Accessibility level requirements
• Security/privacy/tenancy model
• Test environment standards (Testcontainers, docker-compose)
• ADR (Architecture Decision Records) workflow

Quick Start Example

Here's a minimal example showing the complete workflow with a trivial feature: "Add /health endpoint"

1. Setup (One-Time)

skill: prd-driven-development
"Create CLAUDE.md from template"

Output: CLAUDE.md created with detected stack (Node.js from package.json)

Fill minimum sections:

• Tech Stack: Node.js 18, Express 4
• Testing: Jest (unit), Supertest (integration)
• Database: None (simple API)

2. Create PRD

"Create a PRD for: Add a /health endpoint that returns {status: 'ok', uptime: <seconds>}"

Claude asks clarifying questions:

• Q: "Should this be authenticated?" → A: "No, public endpoint"
• Q: "Any specific uptime format?" → A: "Seconds as integer"

Output: prds/0001-prd-health-endpoint.md with:

• PRD-0001-FR-1: Endpoint returns 200 with JSON payload
• PRD-0001-FR-2: Payload includes status and uptime fields
• PRD-0001-NFR-1: Response time < 50ms

3. Generate Tasks

"Generate tasks from prds/0001-prd-health-endpoint.md"

Output (Phase 1 - Parent Tasks):

## Tasks

### 1.0 [  ] Create /health endpoint handler (PRD-0001-FR-1, PRD-0001-FR-2)

### 2.0 [  ] Verify performance requirements (PRD-0001-NFR-1)

Claude stops and waits: "I've generated parent tasks. Review them above. Reply 'Go' to proceed with detailed sub-tasks."

You reply: "Go"

Output (Phase 2 - Sub-Tasks):

### 1.0 [  ] Create /health endpoint handler

  - [ ] 1.1 Write unit tests for health check logic (PRD-0001-FR-2)
  - [ ] 1.2 Write integration test for GET /health endpoint (PRD-0001-FR-1)
  - [ ] 1.3 Implement /health route handler
  - [ ] 1.4 Run tests and fix failures

### 2.0 [  ] Verify performance requirements

  - [ ] 2.1 Add performance test harness (PRD-0001-NFR-1)
  - [ ] 2.2 Run performance tests and verify < 50ms

Also created: tasks/_index.md (global dependency tracker)

4. Execute Tasks

"Process task list tasks/tasks-0001-prd-health-endpoint.md"

Claude works through sub-tasks one at a time:

Sub-task 1.1 (Unit Tests):

// tests/health.test.js
describe('PRD-0001-FR-2 health check data', () => {
  test('returns status ok', () => {
    const data = getHealthData();
    expect(data.status).toBe('ok');
  });

  test('returns uptime as integer', () => {
    const data = getHealthData();
    expect(Number.isInteger(data.uptime)).toBe(true);
  });
});

Sub-task 1.2 (Integration Tests):

// tests/health.integration.test.js
describe('PRD-0001-FR-1 GET /health endpoint', () => {
  test('returns 200 with JSON', async () => {
    const res = await request(app).get('/health');
    expect(res.status).toBe(200);
    expect(res.body).toMatchObject({
      status: 'ok',
      uptime: expect.any(Number)
    });
  });
});

Sub-task 1.3 (Implementation):

// routes/health.js
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    uptime: Math.floor(process.uptime())
  });
});

Sub-task 1.4 (Run Tests):

npm test
✓ All tests passing (2 unit, 1 integration)

Parent 1.0 Complete - Quality Gates:

• ✅ Lint: npm run lint passes
• ✅ Type-check: tsc --noEmit passes
• ✅ Security: npm audit clean
• ✅ Coverage: 100% (meets threshold)

Commit:

feat: add /health endpoint (PRD-0001-FR-1, PRD-0001-FR-2)

- Returns {status, uptime} as JSON
- Adds unit and integration tests
- Response time verified < 50ms

Related to PRD-0001

5. Audit Tests (Optional)

"Audit tests for completed features"

Output: TEST_AUDIT.md with:

• ✅ Coverage: 100% (2 FRs fully tested)
• ✅ Correctness: Tests validate right behavior
• ✅ Traceability: All tests map to PRD-0001-FR-n
• ✅ Quality Gates: All passing

Final Directory Structure

.
├── CLAUDE.md
├── prds/
│   └── 0001-prd-health-endpoint.md
├── tasks/
│   ├── _index.md
│   └── tasks-0001-prd-health-endpoint.md
├── routes/
│   └── health.js
├── tests/
│   ├── health.test.js
│   └── health.integration.test.js
└── TEST_AUDIT.md

For detailed walkthrough with more complex features, see: references/quick-start-tutorial.md

Core Workflow

Phase 1: Import Feature Bundle (Optional)

Workflow Phase: Import PRDs from feature bundle

How to invoke: "Import PRDs from <PATH_TO_FEATURES_FILE>" or "Use Phase 1 to import PRDs from <PATH_TO_FEATURES_FILE>"

Use when: You have a single spec file containing multiple features.

Process:

1. Validate CLAUDE.md exists with architecture baseline
2. Parse bundle to identify distinct features
3. Extract draft PRD skeletons with preliminary dependencies and sizing
4. Build /prd-bundle/index.md with dependency graph and critical path
5. Detect cross-feature conflicts

Deliverables:

• /prd-bundle/index.md - Global summary and dependency graph
• /prd-bundle/[nn]-draft-prd-[feature-name].md - Draft PRD skeletons

Next Steps: Use Phase 2 on each draft to finalize into /prds/

Phase 2: Create Comprehensive PRD

Workflow Phase: Create Product Requirements Document

How to invoke: "Create a PRD for <FEATURE_DESCRIPTION>" or "Create a PRD from <PATH_TO_DRAFT>" (optional: "with complexity level: simple/standard/complex")

Complexity Profiles:

• simple - Lightweight mode for UI-only features, bug fixes, scripts, config changes (minimal testing requirements)
• standard - Standard mode for typical features (default - unit + integration required)
• complex - Comprehensive mode for multi-service, data-heavy features (all test types when applicable)

Process:

1. Validate CLAUDE.md architecture baseline
2. Analyze feature description
3. Ask tiered clarifying questions (Critical → Important → Nice-to-have)
4. Generate PRD with PRD-scoped IDs (PRD-####-FR-n, PRD-####-NFR-n)
5. Save to /prds/[nnnn]-prd-[feature-name].md

Key PRD Sections:

• Introduction, Goals, User Stories
• Functional Requirements (with PRD-scoped IDs)
• Acceptance Criteria (testable, linked to FR IDs)
• Non-Functional Requirements (measurable targets)
• API Contract, Dependencies & Predecessors
• Test Strategy, Feature Flags & Rollout
• Database Change Verification Checklist
• Operational Readiness, Definition of Done
• Traceability Matrix

Next Step: Use Phase 3 on the finalized PRD

Phase 2b: Extend Existing PRD

Workflow Phase: Extend an existing PRD with new requirements

How to invoke: "Extend PRD-0001 with OAuth authentication" or "Add social login to PRD-0001"

Use when:

• Adding new capabilities to a completed PRD
• Enhancing existing features without breaking changes
• Versioning up an existing feature (v1.0 → v2.0)

Smart Detection:

The workflow automatically determines if your request is:

• ✅ Extension (backward compatible) → Updates existing PRD, appends tasks
• ❌ Breaking change (incompatible) → Suggests creating new PRD instead

Extension Criteria (automatic approval):

• Adds new FRs/NFRs with incremented IDs (FR-6, FR-7, etc.)
• Doesn't modify existing FR acceptance criteria
• Backward compatible architecture changes
• Can be implemented without rewriting existing code

Breaking Change Criteria (suggests new PRD):

• Modifies existing FR definitions
• Requires existing code rewrites
• Incompatible architecture changes
• Changes existing API contracts

Process:

1. Read existing PRD file

   • Load prds/0001-prd-feature.md
   • Parse current version, FRs, NFRs
   • Check completion status in prds/_index.md

2. Analyze extension requirements

   • Ask clarifying questions about new capabilities
   • Detect if extension or breaking change
   • If breaking change → prompt: "This looks like a breaking change. Create new PRD instead? (yes/no)"

3. Update PRD file (if extension approved)

   • Increment version (1.0 → 2.0)
   • Add new FRs/NFRs with next sequential IDs
   • Update architecture/design sections
   • Add to "Version History" section
   • Update "Last Updated" timestamp

4. Generate incremental tasks

   • Append new parent tasks to existing task file
   • Generate sub-tasks for new FRs/NFRs
   • Preserve all existing tasks (don't modify completed ones)
   • Update task numbering (if task 3.0 was last, new tasks start at 4.0)

5. Update status tracking

   • Update prds/_index.md:
     • Change status from "✅ Complete" → "🔄 In Progress"
     • Increment version number
     • Add version history entry
     • Recalculate completion % based on new tasks
   • Update tasks/_index.md if cross-PRD dependencies changed

Example:

Before (PRD-0001 v1.0 - Complete):

## Metadata
- **PRD ID:** PRD-0001
- **Version:** 1.0
- **Status:** ✅ Complete
- **Last Updated:** 2025-01-10

## Functional Requirements
### PRD-0001-FR-1: Accept registration request
### PRD-0001-FR-2: Validate email/password
### PRD-0001-FR-3: Check duplicate email
### PRD-0001-FR-4: Create user record
### PRD-0001-FR-5: Return success response

After Extension (PRD-0001 v2.0 - In Progress):

## Metadata
- **PRD ID:** PRD-0001
- **Version:** 2.0
- **Status:** 🔄 In Progress (60% - 3/5 new tasks complete)
- **Last Updated:** 2025-01-15

## Version History
### v2.0 (2025-01-15) - OAuth Authentication Extension
- Added FR-6: OAuth login flow
- Added FR-7: Social provider integration (Google, GitHub)
- Status: 🔄 In Progress (60%)

### v1.0 (2025-01-10) - Email/Password Registration
- Initial implementation
- Status: ✅ Complete (deployed to production)

## Functional Requirements
### PRD-0001-FR-1: Accept registration request ✅
### PRD-0001-FR-2: Validate email/password ✅
### PRD-0001-FR-3: Check duplicate email ✅
### PRD-0001-FR-4: Create user record ✅
### PRD-0001-FR-5: Return success response ✅
### PRD-0001-FR-6: OAuth login flow (NEW v2.0)
### PRD-0001-FR-7: Social provider integration (NEW v2.0)

Task File Update:

### 1.0 [✅] Input Validation (v1.0)
### 2.0 [✅] Database Operations (v1.0)
### 3.0 [✅] API Endpoints (v1.0)

### 4.0 [ ] OAuth Integration (v2.0 - NEW)
  - [ ] 4.1 Write unit tests for OAuth flow (PRD-0001-FR-6)
  - [ ] 4.2 Write integration tests for OAuth providers (PRD-0001-FR-6)
  - [ ] 4.3 Implement OAuth callback handler
  - [ ] 4.4 Run tests and verify

### 5.0 [ ] Social Provider Setup (v2.0 - NEW)
  - [ ] 5.1 Configure Google OAuth (PRD-0001-FR-7)
  - [ ] 5.2 Configure GitHub OAuth (PRD-0001-FR-7)
  - [ ] 5.3 Add provider selection UI

Status Index Update:

| PRD ID | Title | Version | Status | Completion | Tasks | Last Updated | Notes |
|--------|-------|---------|--------|------------|-------|--------------|-------|
| PRD-0001 | User Registration | 2.0 | 🔄 In Progress | 60% (3/5) | 5 | 2025-01-15 | v1.0 complete ✅, v2.0 OAuth in progress |

Deliverable:

• Updated PRD file with version 2.0
• Appended tasks in existing task file
• Updated prds/_index.md with new version and status
• Ready to execute new tasks with Phase 4

Next Step: Use Phase 4 to process the extended task list

Phase 3: Generate Task List

Workflow Phase: Generate structured task list from PRD

How to invoke: "Generate tasks from <PATH_TO_PRD_FILE>" or "Use Phase 3 on prds/0001-prd-feature.md"

Two-Phase Process:

Phase 3.1 - Parent Tasks:

1. Analyze PRD and existing codebase

2. Extract FR/NFR IDs for traceability

3. Derive dependencies and generate topologically ordered parent tasks (typically 4-6 tasks)

4. Create tasks/tasks-[prd-name].md with parent tasks only

5. Present parent tasks to user with clear message:

   "I've generated {N} parent tasks for this PRD. Please review them above to ensure they match your expectations."

   "These parent tasks will be broken down into detailed sub-tasks (including test sub-tasks based on CLAUDE.md requirements)."

   "Reply 'Go' when ready to proceed with sub-task generation, or ask for changes if needed."

6. STOP and WAIT for user response (required: "Go", "go", or explicit approval)

Why the wait?

• Gives you a chance to review high-level task breakdown
• Allows corrections before detailed sub-tasks are generated
• Prevents rework if parent structure is misaligned with expectations

Phase 3.2 - Sub-Tasks (Test-First with CLAUDE.md Authority): After user confirms "Go":

STEP 1: Parse CLAUDE.md Testing Strategy

• Identify which test types are explicitly REQUIRED
• Identify which test types are explicitly EXCLUDED
• For silent/unclear requirements, default to: unit + integration required

STEP 2: Generate Test Sub-Tasks Based on CLAUDE.md

For EACH parent task, break down into sub-tasks following pattern:

If CLAUDE.md requires unit tests (or is silent):

• Write unit tests for FR-n (business logic, validation, utilities)
• Run unit tests and fix ALL failures (invest effort, do not skip easily)

If CLAUDE.md requires integration tests (or is silent):

• Write integration tests for FR-n (API contracts, DB operations, service integration)
• Run integration tests and fix ALL failures (invest effort, do not skip easily)

If CLAUDE.md requires E2E tests AND FR involves frontend-backend (or is silent + frontend-backend): Auto-detect: login, registration, CRUD operations, chatbots, SSE, forms, etc.

• Write AUTOMATED E2E tests for FR-n (user flows, UI-to-API integration)
• Use stack-appropriate E2E framework (Playwright for JS/TS, Playwright/Selenium for Python, etc.)
• Minimize manual testing - automate browser interactions, form fills, assertions
• Run E2E tests and fix ALL failures (invest effort, do not skip easily)

E2E Framework Suggestions by Stack:

• React/Vue/Angular/Svelte/Next.js → Playwright (recommended) or Cypress
• Django/Flask → Playwright for Python or Selenium
• Rails → Capybara or Playwright
• Go web apps → chromedp or playwright-go
• Backend API only → E2E not applicable

If CLAUDE.md explicitly excludes a test type:

• DO NOT generate test sub-tasks for excluded type
• Add note: "X tests excluded per CLAUDE.md Testing Strategy"

Implementation sub-task (always included):

• Implement functionality for FR-n

For database changes, add verification sub-tasks:

• Generate migration files
• VERIFY: Execute migrations against database
• VERIFY: Inspect schema
• VERIFY: Test seed/population script
• VERIFY: Test rollback and re-apply
• Run integration tests against real database

Only skip tests when:

• CLAUDE.md explicitly excludes that test type
• Dependencies truly not available (mark with Structured BLOCKED_BY_TASK notation - see below)
• Infrastructure not ready (document in Deferred/Skipped Tests section with mitigation)
• NEVER skip due to difficulty - invest significant effort to make tests work

Structured BLOCKED_BY_TASK Notation (REQUIRED):

When blocking a test or sub-task, use this format:

BLOCKED_BY_TASK <task-id>: <root-cause> | Mitigation: <workaround> | ETA: <date> | Owner: <person> | Safe: <yes|no|partial>

Examples:

✅ Good (structured):

test.skip('PRD-0007-FR-5 payment processing', () => {
  // BLOCKED_BY_TASK 4.2: Payment gateway API not deployed to staging
  // Mitigation: Using mock payment responses in local tests
  // ETA: 2025-01-20 | Owner: @jane | Safe: Yes with feature flag
});

✅ Good (structured, Python):

@pytest.mark.skip(reason="BLOCKED_BY_TASK 3.1: User model migration pending | Mitigation: Using in-memory stub | ETA: Tomorrow | Owner: @bob | Safe: No - integration tests blocked")
def test_user_creation_prd_0012_fr_2():
    pass

❌ Bad (unstructured):

test.skip('payment test', () => {
  // BLOCKED_BY_TASK 4.2
});

Required Fields:

• task-id: Blocking task ID (e.g., 4.2, 0001-2.0)
• root-cause: Why is this blocked? (dependency not ready, API unavailable, migration pending)
• Mitigation: What workaround exists? (mocks, feature flags, contract stubs)
• ETA: When will blocker be resolved? (date or "Unknown")
• Owner: Who owns unblocking this? (@username or team)
• Safe: Can downstream work proceed? (Yes with mitigation, No must wait, Partial limited functionality)

3. Include PRD FR/NFR tokens in test names
4. Update or create tasks/_index.md for global dependency tracking

Contract-First Workflow for Blocked Dependencies:

When a sub-task depends on an incomplete upstream task, use contract-first development to avoid rewrites:

Step 1: Identify the Dependency Interface

• API endpoint → OpenAPI/GraphQL schema
• Database → Schema definition (Prisma, SQL DDL, migrations)
• Service → Shared types/interfaces (TypeScript, protobuf, JSON schema)
• Message queue → Event schema (Avro, JSON schema)

Step 2: Define or Import the Contract

# Example: API dependency
mkdir -p contracts/
# Get contract from upstream team OR define expected interface
curl https://api-staging.example.com/openapi.yaml > contracts/auth-api-v1.yaml

# Example: Database dependency
# Reference existing schema or create expected schema
cp prisma/schema.prisma contracts/expected-user-model.prisma

Step 3: Generate Code from Contract

• TypeScript: Use OpenAPI Generator, Prisma client, GraphQL Codegen
• Python: Use datamodel-code-generator, OpenAPI Generator, Pydantic
• Go: Use oapi-codegen, protoc, sqlc

Step 4: Implement Against Contract with Feature Flags

// Example: Feature flag for unstable dependency
import { authClient } from './generated/auth-api-client'; // from contract
import { mockAuthClient } from './mocks/auth-client'; // mock for testing

const useRealAuth = process.env.ENABLE_REAL_AUTH === 'true'; // feature flag

export const auth = useRealAuth ? authClient : mockAuthClient;

test('PRD-0007-FR-3 user login', async () => {
  // Test works with both real and mock auth
  const result = await auth.login({ email, password });
  expect(result.token).toBeDefined();
});

Step 5: Add Contract Sync Check

# scripts/check_contract_sync.sh
#!/bin/bash
# Compares local contract with upstream to detect breaking changes

LOCAL_CONTRACT="contracts/auth-api-v1.yaml"
REMOTE_CONTRACT="https://api-staging.example.com/openapi.yaml"

diff <(curl -s $REMOTE_CONTRACT) $LOCAL_CONTRACT
if [ $? -ne 0 ]; then
  echo "⚠️ Contract mismatch detected! Upstream API changed."
  echo "Update $LOCAL_CONTRACT and regenerate client code."
  exit 1
fi

Step 6: Switch to Real Implementation Once upstream task completes with Readiness Proof:

// 1. Update contract file if needed
// 2. Regenerate client code: npm run generate:api-client
// 3. Enable feature flag: ENABLE_REAL_AUTH=true
// 4. Run integration tests: npm test -- --integration
// 5. Remove mock once tests pass

Contract-First Checklist:

• Dependency interface documented (API contract, schema, types)
• Contract file stored in contracts/ or linked from upstream
• Generated client/types from contract (not hand-written stubs)
• Feature flag controls which implementation is used
• Tests work with both mock and real implementation
• Contract sync check runs in CI
• Plan to remove mock once dependency is stable

Benefits:

• ✅ Parallel development - no waiting for upstream
• ✅ No rewrites - contract defines expectations upfront
• ✅ Safe rollout - feature flag enables gradual migration
• ✅ Early detection - contract sync checks catch breaking changes

5. Update or create tasks/_index.md for global dependency tracking

Deliverables:

• Relevant Files section with FR/NFR mappings
• Test Plan Summary
• Deferred/Skipped Tests section
• Blocked/Prerequisites Table
• Task Dependencies section
• Tasks with parent and sub-task hierarchy

Next Step: Use Phase 4 to execute tasks

Phase 4: Execute Task List

Workflow Phase: Process task list systematically

How to invoke: "Process task list <PATH_TO_TASK_LIST_FILE>" or "Use Phase 4 on tasks/tasks-0001.md"

Sub-Task Level Protocol:

1. Check prerequisites - verify parent not blocked:
   • If sub-task depends on another task, verify it has Readiness Proof
   • Check tasks/_index.md for dependency status (must be ready, not blocking or at-risk)
   • Validate readiness artifacts exist:
     • API contract files exist and are up-to-date
     • Tests pass for the dependency
     • Service/endpoint is deployed and reachable
   • If readiness proof missing: Mark current task as BLOCKED_BY_TASK x.y with details
   • If readiness proof stale/incomplete: Ask for clarification before proceeding
2. Verify CLAUDE.md test requirements - confirm which test types apply
3. Work on ONE sub-task at a time
4. Test-first approach (for REQUIRED test types per CLAUDE.md):
   • Write unit tests first (if required)
   • Write integration tests second (if required)
   • For frontend-backend features: write E2E tests third (if required)
   • Then implement functionality
5. Run targeted tests for current FR(s)
6. "Make Effort" enforcement - fix ALL failures with diligence:
   • Spend significant time solving test setup issues
   • Research test infrastructure requirements
   • Ask for clarification if requirements are ambiguous or issues arise
   • If failures depend on future tasks: Add BLOCKED_BY_TASK x.y notation
   • If infrastructure missing: Document in Deferred/Skipped Tests with resolution plan
   • NEVER skip because "tests are hard to write" - this is anti-pattern
7. Before marking sub-task complete [x]:
   • ALL required tests written for this FR (per CLAUDE.md requirements)
   • Tests either PASSING or explicitly marked BLOCKED_BY_TASK with valid reason
   • No unexplained skips or commented-out tests
   • Test setup challenges resolved (not bypassed)
8. Mark sub-task complete [x] only after validation
9. Include PRD FR/NFR tokens in code and commits
10. Proceed automatically to next sub-task unless:
    • Clarification needed on requirements
    • Blocker encountered that requires user decision
    • Quality gates failed and manual intervention needed

ANTI-PATTERNS TO AVOID: ❌ "CLAUDE.md says E2E required but tests are too hard, skipping" ❌ Commenting out failing tests without BLOCKED_BY_TASK ❌ Only writing unit tests when CLAUDE.md requires integration tests ❌ Giving up on test setup after first attempt ❌ Marking sub-task complete with failing tests ❌ Ignoring CLAUDE.md explicit exclusions and generating tests anyway

CORRECT PATTERNS: ✅ Reading CLAUDE.md Testing Strategy before generating tests ✅ Respecting explicit exclusions ("No E2E" → don't generate E2E) ✅ Investing significant effort to solve test infrastructure issues ✅ Writing all required test types per CLAUDE.md ✅ Properly documenting blocked tests with task references ✅ Researching and implementing test setup (containers, mocks, fixtures)

Parent Task Completion Protocol: When all sub-tasks under a parent are [x]:

1. Run full test suite
2. Apply Quality Gates (lint, type-check, security, coverage)
3. Database Migration Verification (IF applicable - see detection guide below):
   • Execute migrations against real database
   • Verify schema matches expectations
   • Test data population/seed script
   • Test rollback and re-apply
   • Run integration tests against real DB (not mocked)
4. Generate Readiness Proof (IF this task is a dependency for others):
   • API Contracts: Link to OpenAPI/GraphQL schema, protobuf definitions, shared types
   • Test Evidence: Link to passing test suite results, test report URL, coverage report
   • Schema/Model Artifacts: Link to schema.sql, Prisma schema, DB migration version
   • Deployment Status: Service deployed to test/staging environment with health check URL
   • Example: ## Readiness Proof: API v1.2.0 contract (openapi.yaml#L45), Tests passing (CI run #123), Deployed to staging (https://api-staging.example.com/health)
5. ONLY if all gates pass: Stage changes
6. Clean up temporary files/code
7. Commit with conventional format including PRD tokens
8. Mark parent task complete [x]
9. Update tasks/_index.md with:
   • Task status: ready (with readiness proof link)
   • Unblock downstream tasks that were waiting on this
   • Update dependency health indicators

Database Change Detection Guide:

When Database Verification Applies: ✅ PRD includes FRs that modify database schema:

• "Add new table/collection for X"
• "Add column/field to existing entity"
• "Change data type or constraints"
• "Add/modify indexes"
• "Create relationships/foreign keys"

When Database Verification Does NOT Apply: ❌ Pure CRUD operations using existing schema ❌ Business logic changes with no schema impact ❌ Frontend-only changes ❌ Configuration or documentation updates

Database Environment Setup:

If migration system exists in CLAUDE.md:

• Use documented migration tool (Alembic, Flyway, Prisma, Rails migrations, etc.)
• Follow existing migration patterns in codebase

If NO migration system exists:

• Detect database type from CLAUDE.md or dependencies:

  • PostgreSQL/MySQL → Use Alembic (Python), Flyway (Java), Prisma (Node), Sequelize (Node)
  • MongoDB → Use migrate-mongo, migrations package, or manual scripts
  • SQLite → Raw SQL scripts or framework ORM

• Create migration infrastructure:

  • Set up migration tool for the stack
  • Create migration directory structure (migrations/, db/migrate/, prisma/migrations/)
  • Add migration commands to CLAUDE.md

• Track current database state (CRITICAL for dev/test):

  Option 1: Schema Definition File (Recommended)

  • SQL databases: Maintain schema.sql or schema.prisma with current state
  • NoSQL: Maintain model definitions or JSON schema
  • Update file with each new migration
  • Use for initializing fresh test databases

  Option 2: Migration Tracking Table/Collection

  • Create schema_migrations table/collection
  • Record: migration name, applied timestamp, current version
  • Auto-update on each migration run
  • Query to determine current state

  Option 3: Declarative Models (ORM-based)

  • Define models in code (SQLAlchemy, Prisma, Mongoose, etc.)
  • Use ORM auto-sync for development
  • Generate migrations from model changes
  • Models serve as source of truth

  Database State Management Workflow:

  1. Developer adds new feature requiring schema change
  2. Update model/schema definition
  3. Generate migration: `npm run migration:generate` or `alembic revision --autogenerate`
  4. Review generated migration
  5. Apply to dev database: `npm run migrate` or `alembic upgrade head`
  6. Commit migration file + updated schema
  7. CI/Test runs migrations against clean test DB
  8. Current state = all migrations applied + schema file matches
  

  For Test/Development Databases:

  • Fresh setup: Apply all migrations in order OR load schema.sql
  • Incremental: Apply only new migrations since last run
  • Seed data: Maintain seed script for test fixtures (users, products, etc.)
  • Tear down: Drop database or use Testcontainers (auto-cleanup)

Test Database Setup Options (choose based on stack):

1. Testcontainers (recommended - Docker-based isolation)

   • Spins up real database in container for tests
   • Automatically tears down after tests
   • Works for: PostgreSQL, MySQL, MongoDB, Redis, etc.

2. docker-compose (manual but flexible)

   • Define test database service
   • Start before tests: docker-compose up -d test-db
   • Run migrations: npm run migrate or equivalent
   • Stop after tests: docker-compose down

3. In-memory database (fast but limited)

   • SQLite for SQL databases
   • MongoDB Memory Server for MongoDB
   • Good for unit tests, limited for integration tests

Add to CLAUDE.md when setting up:

## Data Stores
- Database: [PostgreSQL 15 | MongoDB 6 | etc.]
- Migration tool: [Alembic | Prisma | Flyway | Rails | Sequelize | etc.]
- Test environment: [Testcontainers | docker-compose test-db service]
- Quick start: `docker-compose up -d test-db && npm run migrate`
- Schema location: [migrations/ | prisma/schema.prisma | db/schema.rb]

Critical Database Verification Mindset:

OLD: Files exist = Work complete
NEW: Files exist + Executed + Verified = Work complete

Phase 5: Audit Test Coverage & Correctness (Optional)

Workflow Phase: Audit test quality and completeness

How to invoke:

• "Audit tests for completed features" - Report only (default)
• "Audit tests and update task files" - Report + auto-append missing tests
• "Audit unit tests in src/auth" - Scoped audit
• "Audit all tests with test execution" - Comprehensive with test runs

Purpose: Dual-purpose audit that verifies BOTH test coverage AND test correctness against specifications.

Two-Phase Workflow:

Phase 5.1 - Generate Audit Report (Always - Read-Only)

1. Analyze codebase for test coverage against PRD requirements
2. Identify missing tests (coverage gaps)
3. Identify incorrect tests (wrong assertions, missing FR/NFR IDs)
4. Generate TEST_AUDIT.md report with findings
5. Present report to user for review

Phase 5.2 - Auto-Append Missing Tests (Optional - Write) After report is generated, prompt user:

Found 3 missing tests for PRD-0001:
- Unit test for special char validation (PRD-0001-FR-3)
- Integration test for POST /signup (PRD-0001-FR-3)
- Performance test for /signup (PRD-0001-NFR-1)

Should I add these as sub-tasks to your task file?
A) Yes - Add all missing tests to tasks/tasks-0001-prd-auth.md
B) Custom - Let me choose which tests to add
C) No - Just show me the report (I'll add manually)

If approved (Option A or B):

1. Determine which parent task should contain each missing test
2. Append new sub-tasks to relevant parent tasks
3. Mark additions with **Added by Test Audit (YYYY-MM-DD):** annotation
4. Update task file checkboxes (unchecked for new tests)
5. Preserve all existing task structure and numbering

Example Auto-Append Output:

### 1.0 [✅] User Registration Implementation
  - [✅] 1.1 Write unit tests for email validation
  - [✅] 1.2 Write integration tests for POST /signup
  - [✅] 1.3 Implement signup logic
  - [✅] 1.4 Run tests and verify passing

  **Added by Test Audit (2025-01-15):**
  - [ ] 1.5 Add missing unit test for special char validation (PRD-0001-FR-3)
  - [ ] 1.6 Fix incorrect email assertion in validation.test.js:42 (PRD-0001-FR-2)

### 2.0 [✅] Performance Optimization
  - [✅] 2.1 Database query optimization

  **Added by Test Audit (2025-01-15):**
  - [ ] 2.2 Add performance test for /signup endpoint (PRD-0001-NFR-1)

Invocation Examples:

• @test-audit - Report only, prompts for test type and scope
• @test-audit unit - Audits all unit tests, report only
• @test-audit unit src/features/auth - Scoped to auth folder
• @test-audit all completed-only with-run - Audit + execute tests for completed FRs
• @test-audit with-update - Report + auto-append prompt

Key Features:

1. Coverage Analysis: Identifies missing tests for specifications
2. Correctness Analysis: Verifies test assertions match spec requirements
3. Traceability Verification: Maps tests to PRD FR/NFR IDs
4. Skip Hygiene Check: Validates BLOCKED_BY_TASK notation
5. Quality Gates Review: Checks lint, type, format, security, coverage
6. Test Execution: Optional targeted or full test runs
7. Auto-Append Missing Tests: Optional task file updates with user approval

Scope Options:

• completed-only (default) - Audit only FRs/NFRs linked to completed tasks [x]
• all-tasks - Audit all FRs/NFRs in PRD (completed + pending)

Run Modes:

• Default: No execution, audit only
• with-run - Execute targeted tests for implemented FRs/NFRs
• full-run - Execute full test suite

Update Modes:

• Default: Report only, no task file changes
• with-update - Prompt to auto-append missing tests to task files

Deliverable: TEST_AUDIT.md report with:

• Coverage gaps (missing tests) with suggested locations
• Correctness issues (wrong assertions) with fix recommendations
• FR/NFR traceability matrix
• Deferred/skipped tests review
• Quality gates summary
• Recommendations (immediate, short-term, long-term)
• Optional: Updated task files with missing test sub-tasks appended

When to Use:

• After completing parent tasks (check for gaps in current work)
• Before marking PRD implementation complete (comprehensive validation)
• When verifying test suite quality (correctness audit)
• During code review process (traceability verification)
• To validate traceability compliance (FR/NFR mapping)

Next Steps:

• Report-only mode: Review TEST_AUDIT.md, manually add missing tests to task files
• Auto-append mode: Review appended sub-tasks, execute them using Phase 4 protocol

Phase 6: Generate Status Report

Workflow Phase: Generate comprehensive PRD status report

How to invoke:

• "Generate status report" - Full report (all PRDs)
• "Show PRD status" - Full report
• "Status report for in-progress PRDs" - Filtered view
• "Status report for PRD-0001" - Single PRD detail

Purpose: Provides at-a-glance visibility into all PRD completion states, progress tracking, and project health.

Process:

1. Read prds/_index.md
   • Parse all PRD entries

…(truncated)