@.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)

---

Quick Reference

Phase	Key Activities	Output	Article
1. Load Context	Validate prerequisites, load spec.md, plan.md, supporting docs	Context loaded	Article IV
2-3. Task Generation	Organize by user story, generate tests/impl/verification	Task phases	Article VII, III
4. Parallelization	Mark [P] for tasks that can run simultaneously	[P] markers added	Article VIII
5. Quality Gate	Automatically invoke /audit for validation	Audit report	Article V
6. Generate tasks.md	Write using template, report completion	tasks.md	All

---

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-3: Task Generation Workflow

See: @.claude/skills/generate-tasks/workflows/task-generation.md

Summary:

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

• Required phase structure: Setup → Foundational → User Story Phases → Polish
• One phase per user story (P1, P2, P3...)
• Within each story: Tests → Implementation → Verification

Phase 3: Generate Tasks

• Setup tasks: Project initialization, dependencies
• Foundational tasks: Blocking prerequisites for ALL stories
• User Story tasks: Test-first approach (Article III)
  • Tests (≥2 per story)
  • Implementation (models, services, endpoints, UI)
  • Verification (run tests, validate independently)
• Polish tasks: Documentation, cleanup

Task Format:

• Task ID: T### (sequential numbering)
• Story Label: [US#] for traceability
• Parallel Marker: [P] for simultaneous execution

---

Phase 4: Parallelization Marking

See: @.claude/skills/generate-tasks/workflows/parallelization.md

Summary:

Mark tasks with [P] if they meet ALL criteria:

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

Common Patterns:

• Test writing (different test files) → Parallel
• Setup tasks (independent config) → Parallel
• Documentation updates (different docs) → Parallel
• Model dependencies (B uses A) → Sequential

Document parallel opportunities per phase in summary.

---

Phase 5: Quality Gate Enforcement

See: @.claude/skills/generate-tasks/workflows/quality-gates.md

Summary:

After tasks.md created, automatically invoke /audit command (Article V requirement).

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

Audit Validates:

1. Article IV compliance (spec → plan → tasks sequence)
2. Article VII compliance (user-story-centric organization)
3. Article III compliance (≥2 ACs per story, tests first)
4. Constitution violations (CRITICAL priority)
5. Requirement coverage (100% expected)
6. Ambiguities and underspecification

On CRITICAL failures: Implementation BLOCKED, user must fix issues and re-run /tasks On successful audit: Ready for /implement plan.md

---

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 & Best Practices

See: @.claude/skills/generate-tasks/references/anti-patterns.md

Critical Anti-Patterns to Avoid:

• ❌ Layer-based organization ("All models", "All services")
• ❌ Tasks without [US#] story labels
• ❌ Skipping test tasks (Article III violation)
• ❌ Mixing multiple stories in one phase
• ❌ Creating <2 tests per story
• ❌ Forgetting [P] parallelization markers

Best Practices:

• ✓ Organize by user story (one phase per story)
• ✓ Label all tasks with [US#]
• ✓ Tests before implementation (TDD)
• ✓ Independent test criteria per story
• ✓ Mark parallel tasks with [P]
• ✓ Verify 100% AC coverage

---

Example Task Breakdown

See: @.claude/skills/generate-tasks/examples/task-examples.md

Complete Example: User Authentication feature with 2 user stories (Registration, Login)

Demonstrates:

• Setup → Foundational → User Story Phases → Polish structure
• Test-first approach (Article III)
• Story-centric organization (Article VII)
• [P] parallelization markers (Article VIII)
• Independent test criteria per story
• 100% AC coverage with test task mapping

---

Prerequisites

Before using this skill:

• ✅ spec.md exists (Article IV: specification-first)
• ✅ plan.md exists (Article IV: plan before tasks)
• ✅ PreToolUse hook validates both files exist (automatic enforcement)
• ✅ User stories with priorities defined in spec.md
• ✅ Acceptance criteria defined in plan.md (≥2 per story)
• ⚠️ Optional: data-model.md exists (for entity-based tasks)
• ⚠️ Optional: contracts/ exist (for API task breakdown)

Dependencies

Depends On:

• specify-feature skill - Provides spec.md with user stories
• create-implementation-plan skill - MUST run before this skill (Article IV)
• clarify-specification skill - Should have resolved ambiguities before planning

Integrates With:

• implement-and-verify skill - Uses tasks.md output as implementation roadmap
• /audit command - Automatically invoked after task generation
• /implement command - Requires tasks.md to exist before execution

Tool Dependencies:

• Read tool (to load spec.md, plan.md, supporting docs)
• Write tool (to create tasks.md)

Next Steps

After task generation completes, automatic workflow progression:

Automatic Chain (no manual intervention):

generate-tasks (creates tasks.md)
    ↓ (auto-invokes /audit)
/audit (validates cross-artifact consistency)
    ↓ (if PASS)
Ready for /implement

User Action Required:

• If audit PASS: Run /implement plan.md to begin implementation
• If audit FAIL: Fix CRITICAL issues in spec.md, plan.md, or tasks.md, then re-run generate-tasks

Outputs Created:

• specs/$FEATURE/tasks.md - User-story-organized task breakdown
• YYYYMMDD-HHMM-audit-$FEATURE.md - Quality gate validation report (automatic)

Commands:

• /implement plan.md - Begin implementation (after audit passes)
• /audit $FEATURE - Re-run audit if changes made to artifacts
• /verify plan.md --story P1 - Verify individual story completion (during implementation)

Agent Integration

This skill operates within the planner agent's workflow but does not directly invoke other agents.

Relationship to Implementation Planner

Context: This skill is typically invoked BY the create-implementation-plan skill as part of automatic workflow progression.

Execution:

• Usually runs in main conversation context (not isolated agent)
• Can run within implementation-planner agent if plan creation and task generation combined
• Inherits context from previous workflow steps (spec.md, plan.md)

Audit Agent (Indirect)

When: Automatically after tasks.md is created

Agent: None directly - /audit command may use specialized validation logic

Delegation Method: This skill automatically invokes /audit command via SlashCommand tool

generate-tasks skill (creates tasks.md)
    ↓ invokes
/audit command (SlashCommand tool)
    ↓ expands to
Validation workflow (constitution checks, consistency analysis)
    ↓ produces
audit report (PASS/FAIL with findings)

Implementation Executor (Next Stage)

When: After audit passes, user runs /implement

Agent: executor-implement-verify

Handover: This skill prepares tasks.md which the executor agent consumes

What Executor Receives (from tasks.md):

• User stories organized by priority (P1, P2, P3...)
• Tasks per story with acceptance criteria
• Dependencies and blocking relationships
• Test strategy and verification approach

Task Tool Usage

This skill does NOT directly use the Task tool. It:

1. Runs in main context or within planner agent
2. Invokes /audit via SlashCommand tool (automatic)
3. Prepares output for executor agent (consumed later)

Design Rationale:

• Task generation is deterministic (doesn't need agent isolation)
• Constitutional checks integrated into generation process
• Workflow orchestration via slash commands (cleaner than nested Task calls)

Failure Modes

Common Failures & Solutions

1. plan.md does not exist (Article IV violation)

• Symptom: PreToolUse hook blocks with "Cannot create tasks without implementation plan"
• Solution: Run create-implementation-plan skill or /plan command first
• Prevention: Follow SDD workflow order: /feature → /plan → /tasks → /implement

2. User stories missing priorities (P1, P2, P3)

• Symptom: Cannot organize tasks by story priority
• Solution: Update spec.md to add priority labels to all user stories
• Guidance: P1 = must-have MVP, P2 = important enhancements, P3 = nice-to-have

3. Acceptance criteria insufficient (< 2 per story)

• Symptom: Article III violation detected during task generation
• Solution: Update plan.md to add ≥2 acceptance criteria per user story
• Requirement: Each AC must be testable and independently verifiable

4. Task organization by layer instead of story

• Symptom: Article VII violation - tasks grouped by "All Models", "All Services", etc.
• Solution: Reorganize tasks by user story: Phase per story, tasks for that story only
• Prevention: Review @constitution.md Article VII before generating tasks

5. Tests missing or after implementation tasks

• Symptom: Article III violation - no test tasks OR test tasks after implementation
• Solution: Add test tasks for each AC, place BEFORE implementation tasks
• Pattern: Tests → Implementation → Verification (always this order)

6. Parallel markers missing or incorrect

• Symptom: Article VIII violation - no [P] markers OR [P] on dependent tasks
• Solution: Add [P] only to tasks with different files and no dependencies
• Check: Can T008 and T009 run simultaneously? Different files + no dependencies = [P]

7. Story independence not verified

• Symptom: User stories depend on each other, cannot be demoed standalone
• Solution: Add "Independent Test" criteria to each story phase
• Requirement: Each story must work without other stories implemented

8. Audit invocation skipped

• Symptom: tasks.md created but audit not run automatically
• Solution: Skill should invoke /audit command automatically (not ask user to run it)
• Enforcement: Article V (Template-Driven Quality) requires automatic quality gates

9. Task IDs not sequential or story labels missing

• Symptom: Tasks numbered T001, T010, T100 (gaps) OR no [US#] labels
• Solution: Use sequential T001, T002, T003... and add [US#] to all story-specific tasks
• Example: T008 [P] [US1] Write test for AC-P1-001

10. Missing verification tasks per story

• Symptom: No tasks to verify story completion, unclear when story is done
• Solution: Add verification phase to each story with tasks to run tests and validate
• Pattern: "Run all US# tests (must pass 100%)", "Test story independently"

Related Skills & Commands

Direct Integration:

• specify-feature skill - Provides spec.md with user stories (required predecessor)
• create-implementation-plan skill - Provides plan.md with ACs and tech details (required predecessor)
• implement-and-verify skill - Uses tasks.md to execute implementation
• /tasks command - User-facing command that invokes this skill
• /audit command - Automatically invoked after this skill completes
• /implement command - Requires tasks.md to exist before running

Workflow Context:

• Position: Phase 3 of SDD workflow (after planning, before implementation)
• Triggers: Automatically invoked by create-implementation-plan skill via SlashCommand tool
• Output: tasks.md with user-story-organized task breakdown

Quality Gates:

• Automatic Audit: /audit runs immediately after task generation
• Article III Enforcement: ≥2 ACs per story, tests before implementation
• Article VII Enforcement: Tasks organized by story (not layer)
• Article VIII Enforcement: [P] markers for parallelizable tasks

---

Success Metrics

Task Organization Quality:

• 100% user-story-centric (Article VII compliance)
• 100% AC coverage (every AC has ≥1 test task)
• ≥2 ACs per user story (Article III requirement)
• All tasks labeled with [US#] for traceability

Progressive Delivery:

• Each story has independent test criteria
• Stories can be demoed without dependencies
• Clear priority order (P1 → P2 → P3)
• MVP (P1) implementable first

Efficiency:

• Parallel opportunities identified ([P] markers)
• Dependencies documented clearly
• Sequential tasks ordered correctly
• Audit passes on first generation

---

Version

Version: 1.1.0 Last Updated: 2025-10-23 Owner: Claude Code Intelligence Toolkit

Change Log:

• v1.1.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
• v1.0.0 (2025-10-22): Initial version with automatic audit enforcement