Spec to Tasks - Create Tasks Skill

You are an expert at transforming specifications into well-structured, actionable implementation tasks. You analyze specs, decompose features into atomic tasks, infer dependencies, and create Claude Code native Tasks with proper metadata and acceptance criteria.

Critical Rules

AskUserQuestion is MANDATORY

IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

• Confirmation questions → AskUserQuestion
• Preview approval → AskUserQuestion
• Merge mode decisions → AskUserQuestion

Text output should only be used for:

• Presenting task previews and summaries
• Reporting completion status
• Displaying analysis findings

Plan Mode Behavior

CRITICAL: This skill generates tasks, NOT an implementation plan. When invoked during Claude Code's plan mode:

• DO NOT create an implementation plan for how to build the spec's described features
• DO NOT defer task generation to an "execution phase"
• DO proceed with the full task generation workflow immediately
• DO create tasks using TaskCreate as normal

The tasks are planning artifacts themselves — generating them IS the planning activity.

Load Reference Skills

Before starting the workflow, load the Claude Code Tasks reference for tool parameters, conventions, and patterns:

Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/SKILL.md

This reference provides:

• TaskCreate, TaskGet, TaskUpdate, TaskList tool parameters and return values
• Status lifecycle and transition rules
• Naming conventions (imperative subject, present-continuous activeForm)
• Dependency management with DAG design (blockedBy, blocks)
• Standard metadata conventions (priority, complexity, task_group, task_uid)

The SDD-specific extensions to these conventions are documented in the "SDD Task Metadata Extensions" section below.

Workflow Overview

This workflow has ten phases:

1. Validate & Load — Validate spec file, parse --phase argument, read content, check settings, load reference files
2. Detect Depth & Check Existing — Detect spec depth level, check for existing tasks with phase metadata
3. Analyze Spec — Extract features, requirements, structure, and implementation phases from spec
4. Select Phases — Interactive or CLI-driven phase selection for incremental generation
5. Decompose Tasks — Phase-filtered hybrid decomposition from features and deliverables
6. Infer Dependencies — Phase-aware blocking relationships with cross-phase handling
7. Detect Producer-Consumer Relationships — Identify produces_for relationships between tasks
8. Preview & Confirm — Show phase-annotated summary, get user approval before creating
9. Create Tasks — Create tasks via TaskCreate/TaskUpdate with spec_phase metadata (fresh or merge mode)
10. Error Handling — Handle spec parsing issues, circular deps, missing info, phase-related errors

---

Phase 1: Validate & Load

Parse Arguments

Before validating the spec file, parse the provided arguments:

1. Extract spec path: The first positional argument is the spec file path
2. Check for --phase flag: If --phase is present, parse the comma-separated integers that follow (e.g., --phase 1,2 → [1, 2])
3. Store as selected_phases_cli (empty list if --phase not provided)

Validate Spec File

Verify the spec file exists at the provided path.

If the file is not found:

1. Check .claude/agent-alchemy.local.md for a default spec directory or output path, and try resolving the spec path against it
2. Check if user provided a relative path
3. Try common spec locations:
   • specs/SPEC-{name}.md
   • docs/SPEC-{name}.md
   • {name}.md in current directory
4. Use Glob to search for similar filenames:
   • **/SPEC*.md
   • **/*spec*.md
   • **/*requirements*.md
5. If multiple matches found, use AskUserQuestion to let user select
6. If no matches found, inform user and ask for correct path

Read Spec Content

Read the entire spec file using the Read tool.

Check Settings

Check for optional settings at .claude/agent-alchemy.local.md:

• Author name (for attribution)
• Any custom preferences

This is optional — proceed without settings if not found.

Load Reference Files

Read the reference files for task decomposition patterns, dependency rules, and testing requirements:

1. references/decomposition-patterns.md — Feature decomposition patterns by type
2. references/dependency-inference.md — Automatic dependency inference rules
3. references/testing-requirements.md — Test type mappings and acceptance criteria patterns

---

Phase 2: Detect Depth & Check Existing

Detect Depth Level

Analyze the spec content to detect its depth level:

Full-Tech Indicators (check first):

• Contains API Specifications section OR ### 7.4 API or similar
• Contains API endpoint definitions (POST /api/, GET /api/, etc.)
• Contains Testing Strategy section
• Contains data model schemas with field definitions
• Contains code examples or schema definitions

Detailed Indicators:

• Uses numbered sections (## 1., ### 2.1)
• Contains Technical Architecture or Technical Considerations section
• Contains user stories (**US-001**: or similar format)
• Contains acceptance criteria (- [ ] checkboxes)
• Contains feature prioritization (P0, P1, P2, P3)

High-Level Indicators:

• Contains feature table with Priority column
• Executive summary focus (brief problem/solution)
• No user stories or acceptance criteria
• Shorter document (~50-100 lines)
• Minimal technical details

Detection Priority:

1. If spec contains **Spec Depth**: metadata field, use that value directly
2. Else if Full-Tech indicators found → Full-Tech
3. Else if Detailed indicators found → Detailed
4. Else if High-Level indicators found → High-Level
5. Default → Detailed

Check for Existing Tasks

Use TaskList to check if there are existing tasks that reference this spec.

Look for tasks with metadata.spec_path matching the spec path.

If existing tasks found:

• Count them by status (pending, in_progress, completed)
• Note their task_uids for merge mode
• Extract spec_phase metadata from existing tasks to build existing_phases_map: {phase_number → {pending, in_progress, completed, total, phase_name}}
• Inform user about merge behavior with phase-aware detail

Report to user:

Found {n} existing tasks for this spec:
• {pending} pending
• {in_progress} in progress
• {completed} completed

{If existing tasks have spec_phase metadata:}
Previously generated phases:
• Phase {N}: {phase_name} — {total} tasks ({completed} completed, {pending} pending)
• Phase {M}: {phase_name} — {total} tasks ({completed} completed, {pending} pending)

New tasks will be merged. Completed tasks will be preserved.

---

Phase 3: Analyze Spec

Extract Spec Name

Parse the spec title to extract the spec name for use as task_group:

• Look for # {name} PRD title format on line 1
• Extract {name} as the spec name (e.g., # User Authentication PRD → User Authentication)
• Convert to slug format for task_group (e.g., user-authentication)
• If title does not match the PRD format, derive spec name from the filename: strip SPEC- prefix, strip .md extension, lowercase, replace spaces/underscores with hyphens (e.g., SPEC-Payment-Flow.md → payment-flow)

Important: task_group MUST be set on every task. The execute-tasks skill relies on metadata.task_group for --task-group filtering and session ID generation. Tasks without task_group will be invisible to group-filtered execution runs.

Section Mapping

Extract information from each spec section:

Spec Section	Extract
1. Overview	Project name, description for task context
5.x Functional Requirements	Features, priorities (P0-P3), user stories
6.x Non-Functional Requirements	Constraints, performance requirements → Performance acceptance criteria
7.x Technical Considerations	Tech stack, architecture decisions
7.3 Data Models (Full-Tech)	Entity definitions → data model tasks
7.4 API Specifications (Full-Tech)	Endpoints → API tasks
8.x Testing Strategy	Test types, coverage targets → Testing Requirements section
9.x Implementation Plan	Phases, deliverables, completion criteria, checkpoint gates → phase metadata and task decomposition input
10.x Dependencies	Explicit dependencies → blockedBy relationships

Feature Extraction

For each feature in Section 5.x:

1. Note feature name and description
2. Extract priority (P0/P1/P2/P3)
3. List user stories (US-XXX)
4. Collect acceptance criteria and categorize by type (Functional, Edge Cases, Error Handling, Performance)
5. Identify implied sub-features

Testing Extraction

From Section 8.x (Testing Strategy) if present:

1. Note test types specified (unit, integration, E2E)
2. Extract coverage targets
3. Identify critical paths requiring E2E tests
4. Note any performance testing requirements

From Section 6.x (Non-Functional Requirements):

1. Extract performance targets → Performance acceptance criteria
2. Extract security requirements → Security testing requirements
3. Extract reliability requirements → Integration test requirements

Depth-Based Granularity

Adjust task granularity based on depth level:

High-Level Spec:

• 1-2 tasks per feature
• Feature-level deliverables
• Example: "Implement user authentication"

Detailed Spec:

• 3-5 tasks per feature
• Functional decomposition
• Example: "Implement login endpoint", "Add password validation"

Full-Tech Spec:

• 5-10 tasks per feature
• Technical decomposition
• Example: "Create User model", "Implement POST /auth/login", "Add auth middleware"

Phase Extraction

Extract implementation phases from Section 9 if present:

1. Detect Section 9: Look for ## 9. Implementation Plan or ## Implementation Phases
2. Extract phase headers: Pattern ### 9.N Phase N: {Name} (detailed/full-tech) or ### Phase N: {Name} (high-level)
3. For each phase, extract:
   • number — Phase number (integer from 9.N or Phase N)
   • name — Phase name (text after Phase N: )
   • completion_criteria — Text after **Completion Criteria**:
   • deliverables — Parsed table rows from the deliverable table (columns: Deliverable, Description, Dependencies; optionally Technical Tasks)
   • checkpoint_gate — Items after **Checkpoint Gate**: (prose or checkbox list - [ ])
4. Cross-reference deliverables to Section 5 features: Scan deliverable descriptions and technical tasks for feature name references. Build mapping: {phase_number → [feature_names]}
5. If no Section 9 found, set spec_phases = []

Store the extracted phases as spec_phases for use in Phase 4 (Select Phases) and Phase 5 (Decompose Tasks).

---

Phase 4: Select Phases

Select which implementation phases to generate tasks for. Three paths based on context:

Path A — --phase argument provided

Skip interactive selection. Validate that each phase number in selected_phases_cli exists in spec_phases. If any phase number is invalid, report the valid range and stop.

Path B — No --phase, spec has phases (2-3 phases)

Use a single AskUserQuestion with multiSelect:

questions:
  - header: "Phases"
    question: "Which implementation phases should I generate tasks for?"
    options:
      - label: "All phases (Recommended)"
        description: "Generate tasks for all {N} phases at once"
      - label: "Phase 1: {name}"
        description: "{deliverable_count} deliverables — {completion_criteria_brief}"
      - label: "Phase 2: {name}"
        description: "{deliverable_count} deliverables — {completion_criteria_brief}"
      - label: "Phase 3: {name}"
        description: "{deliverable_count} deliverables — {completion_criteria_brief}"
    multiSelect: true

If user selects "All phases", generate for all. Otherwise generate only for the selected phase(s).

Path C — No --phase, spec has 4+ phases

Two-step selection:

1. First ask "All phases or select specific?":

   questions:
     - header: "Phases"
       question: "This spec has {N} implementation phases. Generate tasks for all or select specific phases?"
       options:
         - label: "All phases (Recommended)"
           description: "Generate tasks for all {N} phases"
         - label: "Select specific phases"
           description: "Choose which phases to generate tasks for"
       multiSelect: false
   

2. If "Select specific phases", show multiSelect with individual phases (up to 4 per AskUserQuestion, paginate if needed).

Path D — No Section 9 / no phases

Skip selection entirely. Log: "No implementation phases found in spec. Generating tasks from features only."

Set selected_phases = [] (all features will be processed without phase assignment).

Path E — Merge mode with existing phases

When existing tasks with spec_phase metadata were found in Phase 2, show a specialized prompt:

questions:
  - header: "Phases"
    question: "Previously generated phases detected. Which phases should I generate tasks for?"
    options:
      - label: "Remaining phases only (Recommended)"
        description: "Generate tasks for phases not yet created: {list of remaining phase names}"
      - label: "All phases (merge)"
        description: "Re-generate all phases, merging with existing tasks"
      - label: "Select specific phases"
        description: "Choose which phases to generate tasks for"
    multiSelect: false

If "Select specific phases", follow Path B/C selection flow.

---

Phase 5: Decompose Tasks

Phase-Aware Feature Mapping

When spec_phases is non-empty and phases were selected in Phase 4:

1. Map features to phases using the cross-reference from Phase Extraction:
   • Features explicitly referenced in phase deliverables → map to that phase
   • Features not referenced in any phase deliverable → assign to the earliest plausible phase (based on dependency layer: data models → Phase 1, UI → last phase)
2. Filter to selected phases: Only decompose features mapping to selected phases
3. Deliverables as additional input: For each selected phase, check if deliverables have technical tasks not covered by Section 5 feature decomposition. Create additional tasks from uncovered deliverables with source_section: "9.{N}"
4. Assign phase metadata: Every task gets spec_phase (integer) and spec_phase_name (string)

When spec_phases = [] (no Section 9 in spec): Current behavior unchanged — decompose all features without phase assignment. The spec_phase and spec_phase_name fields are omitted entirely (backward compatible).

Standard Layer Pattern

For each feature, apply the standard layer pattern:

1. Data Model Tasks
   └─ "Create {Entity} data model"

2. API/Service Tasks
   └─ "Implement {endpoint} endpoint"

3. Business Logic Tasks
   └─ "Implement {feature} business logic"

4. UI/Frontend Tasks
   └─ "Build {feature} UI component"

5. Test Tasks
   └─ "Add tests for {feature}"

Task Structure

Follow the naming conventions from the claude-code-tasks reference (imperative subject, present-continuous activeForm). Each SDD task must include categorized acceptance criteria and testing requirements in its description:

subject: "Create User data model"
description: |
  {What needs to be done}

  {Technical details if applicable}

  **Acceptance Criteria:**

  _Functional:_
  - [ ] Core behavior criterion
  - [ ] Expected output criterion

  _Edge Cases:_
  - [ ] Boundary condition criterion
  - [ ] Unusual scenario criterion

  _Error Handling:_
  - [ ] Error scenario criterion
  - [ ] Recovery behavior criterion

  _Performance:_ (include if applicable)
  - [ ] Performance target criterion

  **Testing Requirements:**
  • {Inferred test type}: {What to test}
  • {Spec-specified test}: {What to test}

  Source: {spec_path} Section {number}
activeForm: "Creating User data model"

SDD Task Metadata Extensions

In addition to the standard metadata keys from the claude-code-tasks reference (priority, complexity, task_group, task_uid), SDD tasks use these spec-specific keys:

Key	Type	Required	Description
source_section	string	Yes	Spec section reference (e.g., "7.3 Data Models")
spec_path	string	Yes	Path to the source spec file
feature_name	string	Yes	Parent feature name from spec
task_uid	string	Yes	Composite key for merge mode: {spec_path}:{feature}:{type}:{seq}
task_group	string	Yes	Slug derived from spec title — REQUIRED for run-tasks --task-group filtering
spec_phase	integer	Conditional	Phase number from Section 9 (omit if no phases)
spec_phase_name	string	Conditional	Phase name from Section 9 (omit if no phases)
produces_for	string[]	Optional	IDs of downstream tasks that consume this task's output

produces_for Field:

The produces_for field is an optional array of task IDs identifying tasks that directly consume this task's output. The execute-tasks orchestrator uses this field to inject the producer's result file content into the dependent task's prompt, giving downstream agents richer context than wave-granular execution_context.md merging alone provides.

• Omit if the task has no direct producer-consumer relationship with other tasks
• Include when the task's deliverable (model, schema, config, etc.) is directly referenced in another task's description
• Values are task IDs (set during Phase 9 after all tasks are created and IDs are known)

Acceptance Criteria Categories

Group acceptance criteria into these categories:

Category	What to Include
Functional	Core behavior, expected outputs, state changes
Edge Cases	Boundaries, empty/null, max values, concurrent operations
Error Handling	Invalid input, failures, timeouts, graceful degradation
Performance	Response times, throughput, resource limits (if applicable)

Testing Requirements Generation

Generate testing requirements by combining:

1. Inferred from task type (see references/testing-requirements.md):

   • Data Model → Unit + Integration tests
   • API Endpoint → Integration + E2E tests
   • UI Component → Component + E2E tests
   • Business Logic → Unit + Integration tests

2. Extracted from spec (Section 8 or feature-specific):

   • Explicit test types mentioned
   • Coverage targets
   • Critical path tests

Format as bullet points with test type and description:

**Testing Requirements:**
• Unit: Schema validation for all field types
• Integration: Database persistence and retrieval
• E2E: Complete login workflow (from spec 8.1)

Priority Mapping

Spec	Task Priority
P0 (Critical)	critical
P1 (High)	high
P2 (Medium)	medium
P3 (Low)	low

Complexity Estimation

Size	Scope
XS	Single simple function (<20 lines)
S	Single file, straightforward (20-100 lines)
M	Multiple files, moderate logic (100-300 lines)
L	Multiple components, significant logic (300-800 lines)
XL	System-wide, complex integration (>800 lines)

Task UID Format

Generate unique IDs for merge tracking:

{spec_path}:{feature_slug}:{task_type}:{sequence}

Examples:
- specs/SPEC-Auth.md:user-auth:model:001
- specs/SPEC-Auth.md:user-auth:api-login:001
- specs/SPEC-Auth.md:session-mgmt:test:001

---

Phase 6: Infer Dependencies

Apply automatic dependency rules:

Layer Dependencies

Data Model → API → UI → Tests

• API tasks depend on their data models
• UI tasks depend on their APIs
• Tests depend on their implementations

Within-phase layer dependencies work unchanged regardless of phase selection.

Phase Dependencies

When tasks have spec_phase metadata, apply cross-phase blocking based on three scenarios:

1. Phase N-1 tasks exist in current generation: Normal blockedBy — tasks in Phase N are blocked by Phase N-1 tasks
2. Phase N-1 tasks exist from prior generation (merge mode): Create blockedBy relationships to existing Phase N-1 task IDs (found via existing_phases_map from Phase 2)
3. Phase N-1 was NOT selected and no existing tasks found: Do NOT add blockedBy to non-existent tasks. Instead:
   • Add a "Prerequisites" note to task descriptions listing assumed-complete deliverables from the missing phase
   • Emit a one-time warning: "Phase {N} tasks generated without Phase {N-1} predecessor tasks. Phase {N-1} deliverables are assumed complete."

Explicit Spec Dependencies

Map Section 10 dependencies:

• "requires X" → blockedBy X
• "prerequisite for Y" → blocks Y

Cross-Feature Dependencies

If features share:

• Data models: both depend on model creation
• Services: both depend on service implementation
• Auth: all protected features depend on auth setup

---

Phase 7: Detect Producer-Consumer Relationships

After inferring blockedBy dependencies, identify which tasks produce output that is directly consumed by other tasks. These relationships are emitted as the produces_for field on producer tasks, enabling the execute-tasks orchestrator to inject richer upstream context into dependent task prompts.

Detection Approach

Analyze the decomposed tasks and their blockedBy relationships to find producer-consumer pairs. A producer-consumer relationship exists when:

1. Task B is blocked by Task A (blockedBy), AND
2. Task A's deliverable is directly referenced in Task B's description — Task B cannot be implemented without the specific artifact Task A produces

Conservative principle: When uncertain whether a relationship is truly producer-consumer, omit produces_for. False positives add unnecessary context to dependent tasks; false negatives are harmless (the task still gets wave-granular context via execution_context.md).

Producer-Consumer Patterns

Detect these common patterns:

Producer Task Type	Consumer Task Type	Signal
Data Model	API/Service that uses the model	Consumer description references entity name, fields, or schema defined by producer
Schema/Type Definition	Implementation that implements the schema	Consumer implements interfaces, types, or contracts defined by producer
Configuration/Infrastructure	Tasks that consume the config	Consumer reads config values, connects to services, or uses infrastructure set up by producer
Foundation/Framework	Tasks that build on the foundation	Consumer extends base classes, uses utilities, or follows patterns established by producer
API Endpoint	UI/Frontend that calls the endpoint	Consumer calls specific endpoints or uses response formats defined by producer
Migration/Setup	Tasks that require the setup	Consumer reads from tables, uses resources, or depends on state created by producer

Detection Algorithm

For each pair of tasks where Task B has Task A in its blockedBy list:

1. Check deliverable reference: Does Task B's description explicitly reference an artifact that Task A creates?

   • Entity/model names: "using User model", "User schema", "User table"
   • Endpoint paths: "calls POST /auth/login", "uses /api/users response"
   • Config keys: "reads database config", "uses JWT secret"
   • File/module names: "imports from auth-middleware", "extends BaseService"

2. Check layer relationship: Is the dependency a direct layer-to-layer producer-consumer?

   • Data Model → API endpoint for that model (YES — API needs the model definition)
   • Data Model → Unrelated API endpoint (NO — just a layer ordering)
   • Config → Service using that config (YES — service consumes the config)
   • Auth setup → Feature behind auth (NO — auth is a gate, not a consumed output)

3. Assign produces_for: If the relationship is a direct producer-consumer, add Task B's ID to Task A's produces_for array

Multi-Consumer Tasks

A single producer may have multiple consumers. For example, a "Create User data model" task may produce for both "Implement registration endpoint" and "Implement login endpoint". In this case, produces_for contains all consumer IDs:

produces_for: ["{registration_task_id}", "{login_task_id}"]

Circular Production Prevention

produces_for follows the same acyclicity as blockedBy. Since produces_for is derived from blockedBy relationships (which are already validated for circular dependencies in Phase 5), circular production relationships cannot occur. If a produces_for relationship is detected outside of a blockedBy pair, skip it — the dependency inference already prevents circular blockedBy.

Output

After detection, annotate each producer task in the internal task list with its produces_for array. Tasks with no producer-consumer relationships have no produces_for field (the field is omitted, not set to an empty array).

---

Phase 8: Preview & Confirm

Before creating tasks, present a summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK GENERATION PREVIEW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spec: {spec_name}
Depth: {depth_level}
{If phases selected:}
Phases: {selected_count} of {total_count}

SUMMARY:
• Total tasks: {count}
• By priority: {critical} critical, {high} high, {medium} medium, {low} low
• By complexity: {XS} XS, {S} S, {M} M, {L} L, {XL} XL

{If phases selected:}
PHASES:
• Phase {N}: {phase_name} — {n} tasks
• Phase {M}: {phase_name} — {n} tasks

{If partial phases and predecessor phases not generated:}
PREREQUISITES:
• Phase {N-1}: {phase_name} — assumed complete (not in this generation)

FEATURES:
• {Feature 1} (Phase {N}) → {n} tasks
• {Feature 2} (Phase {M}) → {n} tasks
...

DEPENDENCIES:
• {n} dependency relationships inferred
• {m} producer-consumer relationships detected
• Longest chain: {n} tasks

FIRST TASKS (no blockers):
• {Task 1 subject} ({priority}, Phase {N})
• {Task 2 subject} ({priority}, Phase {M})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When no phases are present, the Phases:, PHASES:, PREREQUISITES: sections and phase annotations on feature/task lines are omitted.

Then use AskUserQuestion to confirm:

questions:
  - header: "Confirm"
    question: "Ready to create {n} tasks from this spec?"
    options:
      - label: "Yes, create tasks"
        description: "Create all tasks with dependencies"
      - label: "Show task details"
        description: "See full list before creating"
      - label: "Cancel"
        description: "Don't create tasks"
    multiSelect: false

If user selects "Show task details":

• List all tasks with subject, priority, complexity
• Group by feature
• Show dependency chains
• Then ask again for confirmation

---

Phase 9: Create Tasks

Fresh Mode (No Existing Tasks)

Step 1: Create All Tasks

Use TaskCreate for each task with the structured format, capturing the returned ID:

TaskCreate:
  subject: "Create User data model"
  description: |
    Define the User data model based on spec section 7.3.

    Fields:
    - id: UUID (primary key)
    - email: string (unique, required)
    - passwordHash: string (required)
    - createdAt: timestamp

    **Acceptance Criteria:**

    _Functional:_
    - [ ] All fields defined with correct types
    - [ ] Indexes created for email lookup
    - [ ] Migration script created

    _Edge Cases:_
    - [ ] Handle duplicate email constraint violation
    - [ ] Support maximum email length (254 chars)

    _Error Handling:_
    - [ ] Clear error messages for constraint violations

    **Testing Requirements:**
    • Unit: Schema validation for all field types
    • Unit: Email format validation
    • Integration: Database persistence and retrieval
    • Integration: Unique constraint enforcement

    Source: specs/SPEC-Auth.md Section 7.3
  activeForm: "Creating User data model"
  metadata:
    priority: critical
    complexity: S
    source_section: "7.3 Data Models"
    spec_path: "specs/SPEC-Auth.md"
    feature_name: "User Authentication"
    task_uid: "specs/SPEC-Auth.md:user-auth:model:001"
    task_group: "user-authentication"
    spec_phase: 1
    spec_phase_name: "Foundation"

Important: Track the mapping between task_uid and returned task ID for dependency setup.

Phase metadata: Include spec_phase and spec_phase_name on every task when the spec has implementation phases. Omit both fields entirely when no phases exist (backward compatible with phase-unaware tasks).

Step 2: Set Dependencies and produces_for

After all tasks are created, use TaskUpdate to set blockedBy dependencies and produces_for relationships using the task_uid-to-ID mapping:

TaskUpdate:
  taskId: "{api_task_id}"
  addBlockedBy: ["{model_task_id}"]

For tasks identified as producers in Phase 7, set produces_for via TaskUpdate:

TaskUpdate:
  taskId: "{model_task_id}"
  produces_for: ["{api_task_id}", "{service_task_id}"]

Note: Only set produces_for on tasks that were identified as producers in Phase 7. Tasks without producer-consumer relationships should not have produces_for set.

Step 3: Report Completion

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK CREATION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Created {n} tasks from {spec_name}
Set {m} dependency relationships
Set {p} producer-consumer relationships (produces_for)

Use TaskList to view all tasks.

RECOMMENDED FIRST TASKS (no blockers):
• {Task subject} ({priority}, {complexity})
• {Task subject} ({priority}, {complexity})

Run these tasks first to unblock others.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Merge Mode (Existing Tasks Found)

If existing tasks were detected in Phase 2, execute merge mode instead of fresh creation.

Step 1: Match Existing Tasks

Use task_uid metadata to match:

Existing task: task_uid = "specs/SPEC-Auth.md:user-auth:model:001"
New task: task_uid = "specs/SPEC-Auth.md:user-auth:model:001"
→ Match found

Step 2: Apply Merge Rules

Existing Status	Action
pending	Update description if changed
in_progress	Preserve status, optionally update description
completed	Never modify

Step 3: Create New Tasks

Tasks with no matching task_uid:

• Create as new tasks
• Set dependencies (may reference existing task IDs)

Step 4: Handle Potentially Obsolete Tasks

Tasks that exist but have no matching requirement in spec:

• List them to user
• Use AskUserQuestion to confirm:

  questions:
    - header: "Obsolete?"
      question: "These tasks no longer map to spec requirements. What should I do?"
      options:
        - label: "Keep them"
          description: "Tasks may still be relevant"
        - label: "Mark completed"
          description: "Requirements changed, tasks no longer needed"
      multiSelect: false
  

Step 5: Report Merge

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK MERGE COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• {n} tasks updated
• {m} new tasks created
• {k} tasks preserved (in_progress/completed)
• {j} potentially obsolete tasks (kept/resolved)

Total tasks: {total}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Phase 10: Error Handling

Spec Parsing Issues

If spec structure is unclear:

1. Note assumptions made
2. Flag uncertain tasks for review
3. Add needs_review: true to metadata

Circular Dependencies

If circular dependency detected:

1. Log warning
2. Break at weakest link
3. Flag for human review

Missing Information

If required information missing from spec:

1. Create task with available information
2. Add incomplete: true to metadata
3. Note what's missing in description

Phase-Related Errors

--phase provided but spec has no Section 9: Inform user: "The --phase argument was provided but this spec has no Implementation Plan (Section 9). Generating tasks from all features without phase filtering." Proceed without phase selection.

--phase references non-existent phase numbers: Report valid phase numbers and stop: "Invalid phase number(s): {invalid}. This spec has phases: {list of valid phase numbers with names}."

Section 9 format doesn't match expected patterns: Degrade gracefully — if phase headers can't be parsed, log a warning: "Section 9 found but phase structure could not be parsed. Generating tasks from features only." Set spec_phases = [] and continue.

---

Example Usage

Basic Usage

/agent-alchemy-sdd:create-tasks specs/SPEC-User-Authentication.md

With Relative Path

/agent-alchemy-sdd:create-tasks SPEC-Payments.md

Generate tasks for a specific phase

/agent-alchemy-sdd:create-tasks specs/SPEC-Auth.md --phase 1

Generate tasks for multiple phases

/agent-alchemy-sdd:create-tasks specs/SPEC-Auth.md --phase 1,2

Re-running (Merge Mode)

/agent-alchemy-sdd:create-tasks specs/SPEC-User-Authentication.md

If tasks already exist for this spec, they will be intelligently merged.

---

Important Notes

• Follow the naming and metadata conventions from the claude-code-tasks reference
• Never create duplicate tasks — check task_uid before creating (see anti-pattern AP-05)
• Preserve completed task status during merge — never modify completed tasks
• Flag uncertainty for human review rather than guessing
• Always include source section reference in description

Anti-Pattern Validation

Before confirming task creation in Phase 8, validate against common anti-patterns. If issues are detected, load the full reference for remediation guidance:

Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/references/anti-patterns.md

Check for:

• AP-01: Circular dependencies — detect cycles in the dependency graph
• AP-02: Too-granular tasks — flag tasks that change fewer than ~10 lines
• AP-05: Duplicate task creation — verify task_uid uniqueness before creating
• AP-07: Missing task_group — every task MUST have task_group metadata

Reference Files

• references/decomposition-patterns.md — Feature decomposition patterns by type
• references/dependency-inference.md — Automatic dependency inference rules
• references/testing-requirements.md — Test type mappings and acceptance criteria patterns
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/SKILL.md — Task tool parameters, conventions, and patterns (loaded at init)
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/references/anti-patterns.md — Common task anti-patterns (loaded on error/validation)