---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
handoffs: 
  - label: Analyze For Consistency
    agent: speckit.analyze
    prompt: Run a project analysis for consistency
    send: true
  - label: Implement Project
    agent: speckit.implement
    prompt: Start the implementation in phases
    send: true
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

1. **Setup**: Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

2. **Load design documents**: Read from FEATURE_DIR:
   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
   - Note: Not all projects have all documents. Generate tasks based on what's available.

3. **Execute task generation workflow**:
   - Load plan.md and extract tech stack, libraries, project structure
   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
   - If data-model.md exists: Extract entities and map to user stories
   - If contracts/ exists: Map endpoints to user stories
   - If research.md exists: Extract decisions for setup tasks
   - Generate tasks organized by user story (see Task Generation Rules below)
   - Generate dependency graph showing user story completion order
   - Create parallel execution examples per user story
   - Validate task completeness (each user story has all needed tasks, independently testable)

4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
   - Correct feature name from plan.md
   - Phase 1: Setup tasks (project initialization)
   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
   - Phase 3+: One phase per user story (in priority order from spec.md)
   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
   - Final Phase: Polish & cross-cutting concerns
   - All tasks must follow the strict checklist format (see Task Generation Rules below)
   - Clear file paths for each task
   - Dependencies section showing story completion order
   - Parallel execution examples per story
   - Implementation strategy section (MVP first, incremental delivery)

5. **Report**: Output path to generated tasks.md and summary:
   - Total task count
   - Task count per user story
   - Parallel opportunities identified
   - Independent test criteria for each story
   - Suggested MVP scope (typically just User Story 1)
   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)

Context for task generation: $ARGUMENTS

The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

## Implementation Context Requirements

**CRITICAL**: The tasks.md will be executed by a DIFFERENT model than the one generating it. The generating model (you) has deep reasoning capability and can infer implementation details from sparse descriptions. The implementing model does NOT — it needs explicit, self-contained context embedded directly in each task. Every task must be a standalone implementation brief, not a summary that requires the reader to independently analyze the codebase.

### Per-Task Context Blocks

For every non-trivial task (anything beyond creating an empty file or adding a simple field), include an indented **Context** block immediately below the task checkbox line. This block MUST contain:

1. **Existing code references**: Quote the exact current function signatures, struct definitions, or interface methods that the task modifies or depends on. Use fenced code blocks with the language identifier.

2. **Target file state**: Describe what already exists in the target file that the implementer needs to know about (imports, adjacent functions, package conventions).

3. **Expected implementation pattern**: Show a concrete code skeleton or pseudocode of what the implementation should look like. Reference similar patterns already in the codebase by quoting them. For example: "Follow the same pattern as `computeDatasetAnalytics()` in `engine.go` lines 245-310, which iterates entries and accumulates stats."

4. **Key decisions and gotchas**: Non-obvious constraints, edge cases, or design decisions from the spec/research that affect this task. Example: "Must use `int64` not `int` for file sizes to handle >2GB files on 32-bit systems" or "The profile may have RecursiveAnalysis disabled — check `opts.Profile.RecursiveAnalysis` before accumulating subdirectory maps."

5. **Acceptance signal**: A concrete, verifiable statement of what "done" looks like. Example: "`go test ./internal/engine/... -run TestRegistryResolve` passes with all 6 subcases green."

### Example Task WITH Context (REQUIRED format for all non-trivial tasks)

```markdown
- [ ] T009 [US1] Create template analysis module in `internal/engine/module_template.go`

  **Context**:
  - **Implements**: `AnalysisModule` interface from `internal/engine/module.go`:
    ```go
    type AnalysisModule interface {
        Name() string
        Description() string
        ProcessEntry(entry *types.ManifestEntry)
        Finalize(ctx *FinalizationContext) (*ModuleResult, error)
    }
    ```
  - **Depends on**: `ContainerMatcher` from `internal/discovery/matcher.go` — call `matcher.Match(entry.Path)` to identify containers. The matcher is initialized from `profile.ContainerPatterns` (see `engine.go:initContainerMatcher()`).
  - **Accumulation pattern**: Follow the same accumulator pattern as `DatasetAnalyticsAccumulator` in `pipeline.go` — use maps keyed by container path to accumulate file counts, total sizes, and date ranges incrementally during `ProcessEntry()`.
  - **Key struct fields to accumulate**:
    ```go
    type templateModule struct {
        matcher      *discovery.ContainerMatcher
        profile      *config.Profile
        accumulators map[string]*containerAccumulator  // keyed by container path
        seen         map[string]bool                    // for nesting exclusion
        subdirs      map[string]map[string]bool         // container -> subdirs (only if recursive enabled)
        filesByPath  map[string]map[string]int          // container -> subdir -> file count
        sizeByPath   map[string]map[string]int64        // container -> subdir -> total size
    }
    ```
  - **Gotcha**: Nesting exclusion — if `/projects/foo` is a container, `/projects/foo/bar` should NOT also be identified as a separate container even if it matches. Use the `seen` set: before adding a new container, check if any prefix of its path is already in `seen`.
  - **Acceptance**: Module registers successfully, `ProcessEntry()` populates accumulators for test entries, `Name()` returns `"template"`.
```

### Example Task WITHOUT Context (WRONG — never do this)

```markdown
- [ ] T009 [US1] Create template analysis module in `internal/engine/module_template.go` — implement AnalysisModule interface, accumulate container stats during ProcessEntry(), handle nesting exclusion
```

The second example forces the implementing model to independently figure out what `AnalysisModule` looks like, how `ContainerMatcher` works, what fields to accumulate, and how nesting exclusion works. This results in incorrect or incomplete implementations.

### Per-Phase Context Summary

At the start of each phase (after the **Goal** line), include a **Phase Context** block listing:

- **Files modified in this phase**: Full paths with a one-line description of each file's current purpose
- **Key types/interfaces used**: Quoted signatures of types that tasks in this phase depend on
- **Codebase conventions to follow**: Naming patterns, error handling style, import grouping, or test patterns observed in the project (reference specific files as examples)

### Context Sourcing Strategy — Plan Artifacts First

The design documents produced by `/speckit.plan` (contracts, data-model, research, quickstart) already contain most of the information that Context blocks need: interface signatures, struct definitions, design decisions, gotchas, error messages, and acceptance scenarios. **Use these artifacts as your primary source for Context blocks instead of re-reading source files.**

**For tasks that CREATE new files** (new modules, new types, new test files):
- Pull interface signatures, struct definitions, and method contracts from **contracts/** and **data-model.md** — these already contain the exact code the implementer needs
- Pull design decisions, accumulation patterns, and gotchas from **research.md** — cite the specific research item (e.g., "See R3: Container Identification During Streaming")
- Pull acceptance scenarios from **quickstart.md** — map CLI examples to verifiable acceptance signals
- **Do NOT read source files** unless the plan artifacts reference an existing pattern that needs to be matched (e.g., "follows the existing `plugin.Registry` pattern") — in that case, read only the referenced file to quote the specific pattern

**For tasks that MODIFY existing files** (adding fields, rewiring functions, updating existing logic):
- Still use plan artifacts for the **target design** (what the code should become)
- Read the **specific function/struct being modified** from the source file to quote its **current state** — the implementer needs to see both "what exists now" and "what it should become"
- Do NOT read the entire file — read only the function/struct being changed plus its immediate dependencies

**For test tasks**:
- Read **one existing test file** in the same package to capture test conventions (table-driven patterns, setup/teardown helpers, assertion style). Quote a representative test function as a pattern to follow.
- Pull test scenarios from contracts and quickstart — these define expected inputs/outputs

**Always**:
- Read **copilot-instructions.md** or equivalent project guidelines (once, at the start of task generation) for language version constraints, banned patterns, build requirements, and protected code paths
- If the project has a design system or style guide referenced in the plan, read it (once)

**Do NOT**:
- Read full source files for every task — the plan artifacts already distill the relevant information
- Re-derive information that exists in contracts or research — reference those documents directly
- Generate tasks with placeholder signatures — every code reference must come from either plan artifacts or a targeted source file read

## Task Generation Rules

**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.

**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.

### Checklist Format (REQUIRED)

Every task MUST strictly follow this format:

```text
- [ ] [TaskID] [P?] [Story?] Description with file path
```

**Format Components**:

1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
4. **[Story] label**: REQUIRED for user story phase tasks only
   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
   - Setup phase: NO story label
   - Foundational phase: NO story label  
   - User Story phases: MUST have story label
   - Polish phase: NO story label
5. **Description**: Clear action with exact file path

**Examples**:

- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)

### Task Organization

1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
   - Each user story (P1, P2, P3...) gets its own phase
   - Map all related components to their story:
     - Models needed for that story
     - Services needed for that story
     - Endpoints/UI needed for that story
     - If tests requested: Tests specific to that story
   - Mark story dependencies (most stories should be independent)

2. **From Contracts**:
   - Map each contract/endpoint → to the user story it serves
   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase

3. **From Data Model**:
   - Map each entity to the user story(ies) that need it
   - If entity serves multiple stories: Put in earliest story or Setup phase
   - Relationships → service layer tasks in appropriate story phase

4. **From Setup/Infrastructure**:
   - Shared infrastructure → Setup phase (Phase 1)
   - Foundational/blocking tasks → Foundational phase (Phase 2)
   - Story-specific setup → within that story's phase

### Phase Structure

- **Phase 1**: Setup (project initialization)
- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
  - Each phase should be a complete, independently testable increment
- **Final Phase**: Polish & Cross-Cutting Concerns
