@.claude/shared-imports/constitution.md
@.claude/templates/tasks.md

Task Generation

Purpose: Transform implementation plans into executable, user-story-organized task breakdowns following Article VII (User-Story-Centric Organization).

Constitutional Authority: Article VII (User-Story-Centric Organization), Article III (Test-First Imperative), Article VIII (Parallelization Markers)

Phase 1: Load Context

Step 1.1: Validate Prerequisites

PreToolUse hook blocks tasks.md without plan.md, but verify:

FEATURE=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "${SPECIFY_FEATURE:-}")

if [[ ! -f "specs/$FEATURE/spec.md" ]]; then
    echo "ERROR: Missing specification (Article IV violation)"
    exit 1
fi

if [[ ! -f "specs/$FEATURE/plan.md" ]]; then
    echo "ERROR: Missing implementation plan (Article IV violation)"
    exit 1
fi

Step 1.2: Load Specification (User Stories)

Read specs/$FEATURE/spec.md

Extract:
- User stories with priorities (P1, P2, P3...)
- Independent test criteria per story
- Functional requirements

Step 1.3: Load Implementation Plan (Tech Details)

Read specs/$FEATURE/plan.md

Extract:
- Tech stack and frameworks
- Component breakdown
- Acceptance criteria (≥2 per story)
- File structure
- Integration points

Step 1.4: Load Supporting Documents (If Available)

Read specs/$FEATURE/data-model.md  # Entity designs
Read specs/$FEATURE/contracts/*.md  # API specifications
Read specs/$FEATURE/quickstart.md  # Test scenarios

Phase 2: Organize Tasks by User Story (Article VII)

CRITICAL: Tasks MUST be grouped by user story, NOT by technical layer.

Phase Structure

Required Phases:
1. Phase 1: Setup - Project initialization, dependencies
2. Phase 2: Foundational - Blocking prerequisites for ALL stories
3. Phase 3+: User Story Phases - One phase per story (P1, P2, P3...)
4. Final Phase: Polish & Cross-Cutting - Documentation, cleanup

Within Each Story Phase:

Phase N: User Story PX - [Title]

Goal: [What user can do after this phase]
Independent Test: [How to validate this story works standalone]

Tasks:
1. Tests (if TDD required)
2. Models needed for this story
3. Services needed for this story
4. Endpoints/UI needed for this story
5. Integration for this story
6. Verification of this story

Phase 3: Generate Tasks

Step 3.1: Phase 1 - Setup Tasks

Purpose: Initialize project structure, install dependencies

Task Format:

- [ ] T001 Create project structure per implementation plan
- [ ] T002 [P] Install dependencies: <list from plan.md>
- [ ] T003 [P] Configure environment variables
- [ ] T004 [P] Set up development database

Parallel Marker [P]: Tasks that can run simultaneously (different files, no dependencies)

Step 3.2: Phase 2 - Foundational Tasks

Purpose: Blocking prerequisites that ALL user stories depend on

Examples:

- [ ] T005 Create base database schema (users table)
- [ ] T006 Set up authentication middleware
- [ ] T007 Configure error handling and logging

NOT user-story-specific: These enable multiple stories.

Step 3.3: Phase 3+ - User Story Tasks

Article VII Mandate: One phase per user story, organized by priority.

Step 3.3.1: Identify Story Components

For each user story from spec.md:

Map to Components (from plan.md):
- Which models does this story need?
- Which services does this story need?
- Which endpoints/UI does this story need?
- Which tests validate this story?

Example: User Story P1 - Email/Password Registration

Components needed:
- Model: User (enhance existing)
- Service: AuthService (new)
- API: POST /register (new)
- UI: RegisterForm (new)
- Tests: Registration flow tests

Step 3.3.2: Generate Tasks with Article III Compliance

Test-First Mandate (Article III): Tests MUST come before implementation.

Task Sequence:

## Phase 3: User Story P1 - Email/Password Registration

**Story Goal**: Users can create accounts with email and password

**Independent Test**: Can register new user, receive session token, login with credentials

**Dependencies**: Phase 2 (foundational) complete

### Tests (Article III: Test-First)
- [ ] T008 [P] [US1] Write test for AC-P1-001 (valid registration) in tests/auth/register.test.ts
- [ ] T009 [P] [US1] Write test for AC-P1-002 (weak password rejection) in tests/auth/register.test.ts

### Implementation
- [ ] T010 [US1] Enhance User model with password_hash field in models/user.ts
- [ ] T011 [US1] Create AuthService.register() method in services/auth-service.ts
- [ ] T012 [US1] Implement POST /api/auth/register endpoint in api/auth/register.ts
- [ ] T013 [US1] Create RegisterForm component in components/auth/RegisterForm.tsx
- [ ] T014 [US1] Integrate RegisterForm with /register route in pages/register.tsx

### Verification
- [ ] T015 [US1] Run AC tests (must pass 100%)
- [ ] T016 [US1] Test registration flow end-to-end with quickstart scenario
- [ ] T017 [US1] Verify story works independently (no other stories required)

Task ID Format: T### (sequential numbering)
Story Label Format: [US#] where # is story number (US1, US2, US3...)
Parallel Marker: [P] for parallelizable tasks

Step 3.3.3: Repeat for All User Stories

Generate phases for:
- Phase 4: User Story P2
- Phase 5: User Story P3
- ...

Each phase:
- Independent test criteria
- Tests before implementation
- Story-specific tasks only
- Verification step

Step 3.4: Final Phase - Polish

Purpose: Cross-cutting concerns, documentation, cleanup

Examples:

## Phase N: Polish & Cross-Cutting Concerns

- [ ] T### [P] Update API documentation
- [ ] T### [P] Run full test suite
- [ ] T### [P] Perform security audit
- [ ] T### Run linter and fix issues
- [ ] T### Build and verify production bundle
- [ ] T### Update changelog

Phase 4: Mark Parallelization (Article VIII)

Criteria for [P] Marker

Task is parallelizable if:
1. Different files: No file conflicts with other parallel tasks
2. No dependencies: Doesn't depend on incomplete tasks
3. Independent: Can run without coordination

Example:

✓ [P] - [ ] T008 [P] [US1] Write test in tests/auth/register.test.ts
✓ [P] - [ ] T009 [P] [US1] Write test in tests/auth/login.test.ts
          (Different files, no dependencies)

✗ NO [P] - [ ] T010 [US1] Enhance User model
✗ NO [P] - [ ] T011 [US1] Create AuthService using User model
          (T011 depends on T010, must be sequential)

Phase 5: Validate Task Completeness

Step 5.1: Check User Story Coverage

For EACH user story, verify:
- ✓ Has ≥2 tests (one per AC minimum)
- ✓ All components identified in plan.md have tasks
- ✓ Has verification task
- ✓ Has independent test criteria

Step 5.2: Check Acceptance Criteria Coverage

For EACH AC (from plan.md), verify:
- ✓ Has corresponding test task
- ✓ Test task comes before implementation tasks
- ✓ AC is verifiable in verification task

Example:

AC-P1-001: User can register with valid credentials
→ T008: Write test for AC-P1-001
→ T010-T014: Implementation
→ T015: Verify AC-P1-001 passes

Step 5.3: Check Dependencies

Verify:
- Phase 1 (Setup) has no dependencies
- Phase 2 (Foundational) depends only on Phase 1
- Each User Story phase depends only on Foundational
- Final Phase depends on all User Story phases

Create dependency graph:

Phase 1 (Setup)
    ↓
Phase 2 (Foundational)
    ↓
Phase 3 (US P1) ←┐
Phase 4 (US P2) ←┼→ Independent (can be done in any order)
Phase 5 (US P3) ←┘
    ↓
Phase 6 (Polish)

Phase 5: Quality Gate Enforcement (Article V)

Constitutional Mandate: Template-Driven Quality requires automatic validation before implementation.

Step 5.1: Invoke /audit Command Automatically

After tasks.md is successfully created, automatically trigger the quality gate.

DO NOT ask user to run /audit manually - this is automatic enforcement.

Instruct Claude:

"Now that tasks.md is complete, run the quality gate validation to verify cross-artifact consistency:

/audit $FEATURE_ID

This command will:
1. Validate Article IV compliance (spec → plan → tasks sequence)
2. Verify Article VII compliance (user-story-centric organization)
3. Check Article III compliance (≥2 ACs per user story)
4. Detect constitution violations (CRITICAL priority)
5. Identify missing requirement coverage
6. Find ambiguities and underspecification

If audit finds CRITICAL issues:
- Implementation is BLOCKED until issues resolved
- Report violations to user
- Provide remediation guidance

If audit passes all checks:
- Report 'Ready for implementation'
- User can proceed with /implement plan.md

The audit report will be saved as: YYYYMMDD-HHMM-audit-$FEATURE_ID.md"

Step 5.2: Handle Audit Results

On CRITICAL failures:

⚠ Quality Gate FAILED - Implementation BLOCKED

Critical Issues Found:
- [List of CRITICAL findings from audit]

Next Actions:
1. Fix CRITICAL issues in spec.md, plan.md, or tasks.md
2. Re-run /tasks to regenerate tasks.md
3. Audit will re-validate automatically

Implementation cannot proceed until audit passes.

On successful audit:

✓ Quality Gate PASSED - Ready for Implementation

All validation checks passed:
- Constitution compliance: ✓
- Requirements coverage: 100%
- User story organization: ✓
- Acceptance criteria: ≥2 per story ✓

Next Step: Run /implement plan.md to begin implementation

Step 5.3: Record Audit Invocation

Log in tasks.md that audit was run:

## Quality Gate

**Status**: Audit ran automatically on task generation
**Report**: YYYYMMDD-HHMM-audit-$FEATURE_ID.md
**Result**: [PASS/FAIL]
**Date**: [YYYY-MM-DD HH:MM]

Phase 6: Generate tasks.md

Step 6.1: Write Using Template

Use @.claude/templates/tasks.md structure:

---
feature: <number>-<name>
created: <YYYY-MM-DD>
plan: specs/<number>-<name>/plan.md
status: Ready for Implementation
total_tasks: <count>
---

Include:
1. Summary: Total tasks, story breakdown
2. Dependencies: Graph showing story order
3. Parallel Opportunities: Count of [P] tasks per phase
4. All Phases: Setup → Foundational → User Stories → Polish
5. Verification Checklist: How to mark each task complete

Save: specs/$FEATURE/tasks.md

Step 6.2: Report Completion

Output:

✓ Task breakdown created: specs/<number>-<name>/tasks.md

Task Summary:
- Total tasks: 45
- Phase 1 (Setup): 4 tasks
- Phase 2 (Foundational): 3 tasks
- Phase 3 (US P1): 10 tasks (2 tests, 5 impl, 3 verify)
- Phase 4 (US P2): 12 tasks (3 tests, 6 impl, 3 verify)
- Phase 5 (US P3): 8 tasks (2 tests, 4 impl, 2 verify)
- Phase 6 (Polish): 8 tasks

Parallel Opportunities:
- Setup: 3 of 4 tasks can run in parallel
- User Story P1: 2 test tasks can run in parallel
- User Story P2: 3 test tasks can run in parallel

Acceptance Criteria Coverage:
- Total ACs: 8
- Tests mapped: 8 (100% coverage)
- Each AC has ≥1 test task

Story Independence:
- ✓ Each story has independent test criteria
- ✓ Stories can be implemented in priority order (P1 → P2 → P3)
- ✓ Each story is demonstrable standalone

Constitutional Compliance:
- ✓ Article III: Tests before implementation (TDD)
- ✓ Article VII: Tasks organized by user story (not layer)
- ✓ Article VIII: Parallel tasks marked [P]

**Automatic Quality Gate**:
Running /audit command now for validation...

[Audit results will appear here]

If audit passes: Next Step: Run /implement plan.md
If audit fails: Fix CRITICAL issues first, then re-run /tasks

Anti-Patterns to Avoid

DO NOT:
- Organize by layer ("All models", "All services", "All UI")
- Create tasks without [US#] story labels
- Skip test tasks (Article III violation)
- Mix multiple stories in one phase
- Create tasks that span stories (violates independence)
- Forget to mark parallelizable tasks with [P]
- Create < 2 tests per user story (Article III violation)

DO:
- Organize by user story (Phase per story)
- Label tasks with [US#] for traceability
- Tests before implementation (TDD)
- Independent test criteria per story
- Mark parallel tasks with [P]
- Map every AC to ≥1 test task
- Verify 100% AC coverage

Example Task Breakdown

Input: Plan with 2 user stories (P1: Register, P2: Login)

Output: tasks.md with 6 phases

## Phase 1: Setup
- [ ] T001 Create project structure
- [ ] T002 [P] Install dependencies
- [ ] T003 [P] Configure environment

## Phase 2: Foundational
- [ ] T004 Create users table schema
- [ ] T005 Set up Supabase client

## Phase 3: User Story P1 - Registration
Independent Test: Can register and login

### Tests
- [ ] T006 [P] [US1] Test AC-P1-001 (valid registration)
- [ ] T007 [P] [US1] Test AC-P1-002 (weak password rejection)

### Implementation
- [ ] T008 [US1] Enhance User model with password_hash
- [ ] T009 [US1] Create AuthService.register()
- [ ] T010 [US1] Implement POST /api/auth/register
- [ ] T011 [US1] Create RegisterForm component

### Verification
- [ ] T012 [US1] Run all US1 tests (must pass)
- [ ] T013 [US1] Test US1 independently

## Phase 4: User Story P2 - Login
Independent Test: Can login with registered credentials

### Tests
- [ ] T014 [P] [US2] Test AC-P2-001 (valid login)
- [ ] T015 [P] [US2] Test AC-P2-002 (invalid credentials)

### Implementation
- [ ] T016 [US2] Create AuthService.login()
- [ ] T017 [US2] Implement POST /api/auth/login
- [ ] T018 [US2] Create LoginForm component

### Verification
- [ ] T019 [US2] Run all US2 tests (must pass)
- [ ] T020 [US2] Test US2 independently

## Phase 5: Polish
- [ ] T021 [P] Update API docs
- [ ] T022 [P] Run full test suite
- [ ] T023 Build production bundle

Result: 23 tasks, organized by story, tests-first, parallelization marked.

Skill Version: 1.0.0
Last Updated: 2025-10-19