create-tasks

What this skill does

# 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
3. Use Glob to search for similar filenames:
   - `**/SPEC*.md`
   - `**/*spec*.md`
   - `**/*requirements*.md`
4. If multiple matches found, use AskUserQuestion to let user select
5. 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 stor