create-tasks

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:
4. specs/SPEC-{name}.md
5. docs/SPEC-{name}.md
6. {name}.md in current directory
7. Use Glob to search for similar filenames:
8. **/SPEC*.md
9. **/spec.md
10. **/requirements.md
11. If multiple matches found, use AskUserQuestion to let user select
12. 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 stori