# Prd Driven Development

> Systematic PRD-driven software development workflow for Claude Code. Use when the user wants to (1) Import/parse feature bundles into draft PRDs with dependency analysis, (2) Create comprehensive Product Requirements Documents from feature descriptions, (2b) Extend existing PRDs with new requirements (version increment), (3) Break down PRDs into structured task lists with dependencies and test plans, (4) Systematically execute task lists with quality gates and verification protocols, (5) Audit test coverage and correctness against specifications, (6) Generate comprehensive PRD status reports showing completion states and progress tracking, or build complete applications from requirements through to tested implementation following enterprise-grade practices.

- Skill: `majiayu000/prd-driven-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/prd-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/prd-driven-development/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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):**
```markdown
## 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):**
```markdown
### 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):**
```javascript
// 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):**
```javascript
// 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):**
```javascript
// routes/health.js
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    uptime: Math.floor(process.uptime())
  });
});
```

**Sub-task 1.4 (Run Tests):**
```bash
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):**
```markdown
## 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):**
```markdown
## 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:**
```markdown
### 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:**
```markdown
| 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):
```javascript
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):
```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):
```javascript
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**
```bash
# 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**
```javascript
// 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**
```bash
# 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:
```javascript
// 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:**
```markdown
## 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:**

```markdown
### 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)