task-generation

name	Task Generation
description	Generate user-story-organized task lists from implementation plans. Use when plan exists and user is ready for implementation, mentions "create tasks", "break down work", or asks "what tasks are needed" to implement the feature.
degree-of-freedom	low
allowed-tools	Read, Write

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