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, taskgroup, taskuid)

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

1. Use Glob to search for similar filenames:

• **/SPEC*.md
• **/*spec*.md
• **/*requirements*.md

1. If multiple matches found, use AskUserQuestion to let user select
2. 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 - [ ])

1. Cross-reference deliverables to Section 5 features: Scan deliverable descriptions and technical tasks for feature name references. Build mapping: {phase_number → [feature_names]}
2. 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?":

```yaml 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 ```

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

1. Filter to selected phases: Only decompose features mapping to selected phases
2. 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}"
3. 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 applica

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sequenzia](https://github.com/sequenzia)
- **Source:** [sequenzia/agent-alchemy](https://github.com/sequenzia/agent-alchemy)
- **License:** MIT
- **Homepage:** https://sequenzia.github.io/agent-alchemy

Install and usage instructions live in the source repository linked above.