Specification to Tasks

Converts a functional specification into a list of executable, trackable tasks. This is the bridge between WHAT (specification) and HOW (implementation).

Overview

This command reads a functional specification generated by /developer-kit:devkit.brainstorm and converts it into atomic, executable tasks.

Input: docs/specs/[id]/YYYY-MM-DD--feature-name.md (preferred) or legacy docs/specs/[id]/YYYY-MM-DD--feature-name-specs.md Output:

• Task list: docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md
• Individual tasks: docs/specs/[id]/tasks/TASK-XXX.md

Task Structure

Each task includes:

• Title: Descriptive name for the task
• Description: Functional description of what to implement
• Acceptance Criteria: Testable conditions for completion
• Dependencies: Other tasks that must complete first (if any)
• Implementation Command: Pre-filled command to execute this task

Workflow Position

Idea → Functional Specification → Tasks → Implementation
              (devkit.brainstorm)   (this)   (devkit.task-implementation)

Usage

# Basic usage - specify spec file or folder
/developer-kit:devkit.spec-to-tasks docs/specs/001-hotel-search-aggregation/
/developer-kit:devkit.spec-to-tasks docs/specs/001-hotel-search-aggregation/2026-03-07--hotel-search-aggregation.md

# With language specification
/developer-kit:devkit.spec-to-tasks --lang=spring docs/specs/001-user-auth/
/developer-kit:devkit.spec-to-tasks --lang=typescript docs/specs/001-user-auth/
/developer-kit:devkit.spec-to-tasks --lang=nestjs docs/specs/001-user-auth/
/developer-kit:devkit.spec-to-tasks --lang=react docs/specs/001-user-auth/
/developer-kit:devkit.spec-to-tasks --lang=python docs/specs/001-user-auth/
/developer-kit:devkit.spec-to-tasks --lang=general docs/specs/001-user-auth/

Arguments

Argument	Required	Description
--lang	Recommended	Target language/framework: java, spring, typescript, nestjs, react, python, php, general. Required for codebase analysis and technical task generation
spec-file	No	Path to spec file or spec folder (e.g., docs/specs/001-feature-name/, docs/specs/001-feature-name/2026-03-07--feature-name.md, or legacy *-specs.md)

Current Context

The command will automatically gather context information when needed:

• Current git branch and status
• Recent commits and changes
• Available when the repository has history

---

You are converting a functional specification into executable tasks. Follow a systematic approach: analyze requirements, identify dependencies, generate atomic tasks, and create a trackable task list.

Core Principles

• Atomic tasks: Each task should be implementable in a single focused effort
• Clear dependencies: Explicitly state which tasks depend on others
• Testable criteria: Each task must have clear acceptance criteria
• Technical detail: Tasks include technical context from codebase analysis
• Codebase-aware: Tasks reference existing patterns, APIs, and structures in the project
• Use TodoWrite: Track all progress throughout
• No time estimates: DO NOT provide or request time estimates
• Test instructions: Each task MUST include explicit and detailed instructions on what to test, specifying test types (unit, integration) and behaviors to verify, NEVER including test code.

---

Phase 1: Specification Analysis

Goal: Read and understand the functional specification

Input: $ARGUMENTS (spec file or folder path)

Actions:

1. Create todo list with all phases

2. Parse $ARGUMENTS to extract:

   • --lang parameter (language/framework for implementation)
   • spec-path (path to spec file or folder)

3. Determine the spec folder:

   • If a file path is provided: use its parent directory and that file as the specification
   • If a folder path is provided: use the folder directly
   • Resolve the specification file with this priority:
     1. YYYY-MM-DD--feature-name.md
     2. legacy YYYY-MM-DD--feature-name-specs.md
     3. the only dated spec-like markdown file in the folder excluding --tasks.md, decision-log.md, traceability-matrix.md, user-request.md, and brainstorming-notes.md

4. Read the resolved functional specification file

5. CRITICAL: Look for user context files in the spec folder:

   • Search for these specific files that contain the original user request:
     • user-request.md - Original user request (from brainstorming - PRIMARY)
     • brainstorming-notes.md - Notes from brainstorming session (SECONDARY)
   • Read these files and incorporate their content into your analysis
   • These files are created by the brainstorming command and contain critical context

6. Extract the spec ID from folder name (e.g., 001-hotel-search-aggregation)

7. Verify the specification exists and is valid

8. If file not found:

   • First auto-detect from the folder using the rules above
   • Only ask the user if multiple plausible spec files exist or none can be resolved

9. Quality Pre-Check (Soft Gate):

   • Check for section ## Clarifications in the spec file (added by spec-review)
   • Search for vague terms: grep for "robusto|intuitivo|veloce|appropriato|suitable|efficient|robust|fast|intuitive"
   • If Clarifications section is missing AND vague terms are found:
     • Warning: "Spec not reviewed. Vague terms detected: [list terms found]"
     • Ask via AskUserQuestion:
       • Options:
         • "Continue anyway" (proceed at user risk)
         • "Run spec-review first" (recommended: /devkit.spec-review docs/specs/[id]/)
   • If Clarifications section exists OR no vague terms found: proceed without warning

---

Phase 2: Requirement Extraction

Goal: Extract and organize requirements from the specification

Actions:

1. Analyze the specification for:

   • User stories and use cases
   • Business rules
   • Acceptance criteria
   • Integration requirements

2. CRITICAL: Include technical requirements from context files:

   • Review user-request.md and brainstorming-notes.md found in Phase 1
   • Extract technical details that were provided during brainstorming:
     • Architecture patterns (message queues, caching, async processing)
     • Specific technologies mentioned (Redis, RabbitMQ, specific databases)
     • Integration patterns and external services
     • Any implementation hints or technical constraints
   • These technical requirements must be reflected in the task decomposition
   • Example: If context mentions "RabbitMQ queues", there must be tasks for queue configuration and consumers

3. Group related requirements:

   • Identify naturally atomic units of work
   • Note dependencies between requirements
   • Prioritize based on dependencies (what can be done first)

4. CRITICAL: Verify against original user request:

   • Using the user-request.md content already read in Phase 1
   • Compare the extracted requirements against the original user request
   • Identify any requirements that are mentioned in the original request but NOT captured in the specification
   • If discrepancies found, use AskUserQuestion to present them to the user:
     • "I found requirements from your original request that may not be in the specification:"
       • [list missing requirements]
     • Options:
       • "Add missing requirements to task list" (recommended)
       • "Regenerate specification to include them"
       • "Continue with current specification"

5. Present the extracted requirements structure (including technical requirements) to user for confirmation

6. Assign unique REQ-IDs to each extracted requirement:

   • For each requirement identified (from user stories, business rules, acceptance criteria), assign a unique identifier: REQ-001, REQ-002, etc.
   • Document REQ-IDs in a requirements list for later traceability:

     REQ-001: [User story / requirement text]
     REQ-002: [Business rule / requirement text]
     REQ-003: [Acceptance criterion / requirement text]
     ...
     

   • These REQ-IDs will be used in the Traceability Matrix to map requirements → tasks → tests → code

---

Phase 2.5: Check/Load Knowledge Graph

Goal: Check if cached codebase analysis exists from previous runs

Prerequisite: Requires --lang parameter and spec folder path

Actions:

1. Check for existing Knowledge Graph:

   • Look for knowledge-graph.json in the spec folder
   • If file doesn't exist, skip to Phase 3 (Codebase Analysis)

2. If Knowledge Graph exists:

   • Read metadata.updated_at timestamp
   • Calculate age: current_time - updated_at
   • Load and summarize key findings:
     • Count of patterns discovered
     • Count of components (controllers, services, repositories)
     • Count of APIs (internal/external)
     • Technology stack identified

3. Present summary to user:

   Found cached codebase analysis from X days ago:
   - Y architectural patterns (Repository, Service Layer, etc.)
   - Z components (N controllers, M services, K repositories)
   - Q API endpoints documented
   - Technology stack: [framework] [version]
   
   The analysis is [fresh/getting stale/old].
   

4. Choose reuse strategy automatically unless the case is borderline:

   • If KG is < 7 days old: use cached analysis automatically
   • If KG is > 30 days old: re-explore automatically
   • If KG is 7-30 days old: ask user via AskUserQuestion whether to reuse or refresh

5. Based on the chosen strategy:

   • Use cached: Load full KG into context, skip Phase 3, proceed to Phase 4
   • Re-explore: Proceed to Phase 3 (Codebase Analysis)

6. If using cached KG:

   • Query KG for all patterns: query knowledge-graph [spec-folder] patterns
   • Query KG for all components: query knowledge-graph [spec-folder] components
   • Query KG for all APIs: query knowledge-graph [spec-folder] apis
   • Store results in context for Phase 4 (Task Decomposition)
   • Note: "Proceeding with cached analysis from X days ago"

7. Check and Load Global Knowledge Graph (if exists):

   • Look for docs/specs/.global-knowledge-graph.json
   • If file exists:
     • Extract project-level patterns that apply across all specs
     • Load patterns.architectural and patterns.conventions
     • Note: "Also loaded N global patterns from project-level analysis"
     • Use global patterns as supplementary context (project conventions to consider)

---

Phase 3: Codebase Analysis

Goal: Understand existing codebase to generate technically accurate tasks

Prerequisite: This phase requires --lang parameter to select appropriate agents

Actions:

1. Based on --lang parameter, select appropriate codebase exploration agent:

Language	Agent
java / spring	developer-kit-java:java-software-architect-review
typescript / nestjs	developer-kit-typescript:typescript-software-architect-review
react	developer-kit-typescript:react-software-architect-review
python	developer-kit-python:python-software-architect-expert
php	developer-kit-php:php-software-architect-expert
general	developer-kit:general-code-explorer

2. Launch the agent with a language-specific prompt to explore the codebase:

For java / spring:

Explore the Java/Spring Boot codebase to understand:

1. **Project Structure**:
   - Package organization (domain-driven, layered, etc.)
   - Build configuration (Maven/Gradle, pom.xml/build.gradle)
   - Main application class and entry points

2. **Spring Patterns**:
   - Spring Data JPA repositories and entity mapping
   - Spring Security configuration and auth patterns
   - REST controller conventions (@RestController, @RequestMapping)
   - Service layer patterns (@Service, transaction management)
   - Configuration properties (@ConfigurationProperties)

3. **Data Layer**:
   - Entity/DTO patterns
   - Database migrations (Flyway, Liquibase)
   - ORM patterns (Hibernate)

4. **Testing Patterns**:
   - Test directory structure
   - Testing conventions (JUnit 5, Mockito)
   - Integration test setup

Provide a summary that will inform task generation with Spring-specific context.

For typescript / nestjs:

Explore the TypeScript/NestJS codebase to understand:

1. **Project Structure**:
   - Module organization
   - TypeScript configuration (tsconfig.json)
   - NestJS module structure

2. **NestJS Patterns**:
   - Controller conventions (@Controller, @Get, @Post, etc.)
   - Service layer patterns (@Injectable, providers)
   - Module organization (@Module)
   - Dependency injection setup
   - Guards and interceptors

3. **Data Access**:
   - ORM usage (TypeORM, Drizzle, Prisma)
   - Repository patterns
   - Database migrations

4. **Testing Patterns**:
   - Jest configuration
   - Unit vs integration test structure

Provide a summary that will inform task generation with NestJS-specific context.

For react:

Explore the React codebase to understand:

1. **Project Structure**:
   - App organization (Next.js, Remix, or CRA/Vite)
   - Routing structure
   - Component directory layout

2. **React Patterns**:
   - Component patterns (functional, hooks)
   - State management (Context, Redux, Zustand, etc.)
   - API communication (React Query, SWR, fetch)
   - Form handling patterns

3. **Styling**:
   - CSS approach (CSS modules, Tailwind, styled-components)
   - Component library usage

4. **Testing Patterns**:
   - Testing library (Jest, Vitest, React Testing Library)
   - Component testing conventions

Provide a summary that will inform task generation with React-specific context.

For python:

Explore the Python codebase to understand:

1. **Project Structure**:
   - Package organization
   - requirements.txt, setup.py, or pyproject.toml
   - Entry points (main.py, __main__.py)

2. **Python Patterns**:
   - Web framework (Django, FastAPI, Flask)
   - Data models (SQLAlchemy, Pydantic, Django ORM)
   - API patterns (REST, GraphQL)
   - Authentication patterns

3. **Testing Patterns**:
   - pytest configuration
   - Test directory structure
   - Mocking conventions

Provide a summary that will inform task generation with Python-specific context.

For php:

Explore the PHP codebase to understand:

1. **Project Structure**:
   - Composer-based project organization
   - Laravel directory structure or custom MVC

2. **PHP Patterns**:
   - Framework conventions (Laravel, Symfony)
   - ORM usage (Eloquent, Doctrine)
   - Controller patterns
   - Routing and middleware

3. **Testing Patterns**:
   - PHPUnit configuration
   - Feature vs unit test structure

Provide a summary that will inform task generation with PHP-specific context.

For general:

Explore the codebase to understand:

1. **Project Structure**:
   - Main directories and their purpose
   - Configuration files (package.json, pom.xml, requirements.txt, etc.)
   - Entry points and main modules

2. **Existing Patterns**:
   - Data models/schemas used
   - API patterns (REST, GraphQL, etc.)
   - Authentication/authorization patterns
   - Database access patterns (ORM, raw queries, etc.)
   - Error handling patterns
   - Logging and monitoring approaches

3. **Technology Stack**:
   - Frameworks and libraries used
   - Database systems
   - External service integrations
   - Build and deployment tools

4. **Integration Points**:
   - Existing APIs the new feature must integrate with
   - Shared utilities or helper functions
   - Common components or services
   - Configuration management

5. **Code Organization**:
   - Layered architecture (if any)
   - Module boundaries
   - Dependency injection patterns
   - Testing patterns and conventions

Provide a comprehensive summary that will inform task generation.

3. Collect and synthesize the codebase analysis
4. Document key findings that will influence task generation:
   • Existing patterns to follow
   • APIs to integrate with
   • Shared components to use
   • Conventions to respect

---

Phase 3.5: Update Knowledge Graph

Goal: Persist agent discoveries into the Knowledge Graph for future reuse

Prerequisite: Phase 3 (Codebase Analysis) must have completed

Actions:

1. Extract structured findings from agent analysis:

   • Parse the agent's comprehensive analysis output
   • Map findings to KG schema sections:
     • patterns.architectural: Design patterns discovered (Repository, Service Layer, etc.)
     • patterns.conventions: Coding conventions (naming, testing, etc.)
     • components: Code components identified (controllers, services, repositories, entities)
     • apis.internal: REST endpoints and API structure
     • apis.external: External service integrations
     • integration_points: Database, cache, message queues, etc.

2. Construct KG update object:

   {
     "metadata": {
       "spec_id": "[extracted from folder]",
       "feature_name": "[extracted from folder]",
       "updated_at": "[current ISO timestamp]",
       "analysis_sources": [
         {
           "agent": "[agent-type-used]",
           "timestamp": "[current ISO timestamp]",
           "focus": "codebase analysis for task generation"
         }
       ]
     },
     "codebase_context": {
       "project_structure": { /* from agent analysis */ },
       "technology_stack": { /* from agent analysis */ }
     },
     "patterns": {
       "architectural": [ /* patterns discovered */ ],
       "conventions": [ /* conventions identified */ ]
     },
     "components": {
       "controllers": [ /* controllers found */ ],
       "services": [ /* services found */ ],
       "repositories": [ /* repositories found */ ],
       "entities": [ /* entities found */ ],
       "dtos": [ /* DTOs found */ ]
     },
     "apis": {
       "internal": [ /* endpoints discovered */ ],
       "external": [ /* external integrations */ ]
     },
     "integration_points": [ /* databases, caches, etc. */ ]
   }
   

3. Update Knowledge Graph using spec-quality command:

   • Call: /developer-kit:devkit.spec-quality [spec-folder] --update-kg-only
   • The spec-quality command will:
     • Create/update knowledge-graph.json with discovered patterns
     • Document components, APIs, and integration points
     • Update metadata.updated_at and metadata.analysis_sources
     • Generate summary report of changes

4. Log and report:

   Knowledge Graph updated via spec-quality:
   - X architectural patterns documented
   - Y coding conventions identified
   - Z components catalogued (N controllers, M services, K repositories)
   - Q API endpoints documented
   - R integration points mapped
   
   Saved to: docs/specs/[ID]/knowledge-graph.json
   

5. Verify update:

   • Read back the updated KG to confirm write succeeded
   • Check that metadata was updated correctly
   • If write failed, log warning but continue (non-blocking)

Note: If user chose to use cached KG in Phase 2.5, skip this phase and proceed directly to Phase 4.

---

Phase 4: Technical Task Decomposition

Goal: Break down requirements into atomic, executable tasks

Actions:

1. If Knowledge Graph context is available (from Phase 2.5 cached or Phase 3.5 updated):

   • Review KG patterns: Architectural patterns to follow in each task
   • Review KG components: Existing components to reuse or integrate with
   • Review KG APIs: Internal/external APIs relevant to tasks
   • Review KG conventions: Naming, testing, and coding standards
   • Use KG context to enrich "Technical Context" section of each task
   • Example: "Follow existing Repository Pattern - extend JpaRepository"
   • Example: "Integrate with existing HotelService.searchHotels() method"

2. For each requirement group, create one or more tasks:

   • Each task should be implementable in 1-2 hours max
   • Tasks should have clear, testable completion criteria
   • Avoid tasks that span multiple user stories

3. For each task, define:

   • Title: Concise, descriptive name (e.g., "User login functionality")
   • Description: What the task covers functionally
   • Acceptance Criteria: 2-4 testable conditions
   • Dependencies: List task IDs this depends on (if any)

4. Map dependencies explicitly:

   • Identify which tasks must complete before others can start
   • CRITICAL: List ALL dependencies explicitly for each task BEFORE generating files
   • For each task, document: "This task depends on: [TASK-ID-1, TASK-ID-2] (or 'None')"
   • Identify potential circular dependencies (Task A depends on B, B depends on A)
   • Order tasks accordingly

5. Validate dependencies before generating files:

   • Present the dependency structure in a clear table format:

   Task ID	Title	Dependencies
   TASK-001	[Title]	None
   TASK-002	[Title]	TASK-001
   TASK-003	[Title]	TASK-001, TASK-002
   ...	...	...

   • If there are circular dependencies, high coupling, or unclear ordering, use AskUserQuestion to confirm a fix
   • Otherwise proceed directly and include the dependency table in the generated summary

6. Identify Test Requirements for Each Task: For each identified task, you must now precisely and mandatorily define what needs to be tested. This analysis will guide the generation of the "Test Instructions" section in the task file.

   • Analyze involved classes/components: For each file that the task will create or modify, determine its complexity level and testing importance.

     • High Priority (Mandatory Tests): Classes with business logic, state management, validation rules, complex calculations, algorithms, interactions with external services (API, database). Examples: Service, UseCase, Controller/Handler, Validator, complex Entities.
     • Medium Priority (Recommended Tests): Utility classes, helpers, simple data transformers, repositories (if not auto-generated).
     • Low Priority (Optional Tests): Simple DTOs, POCOs, configurations.

   • Define behaviors to test: For each high-priority component, list specific test scenarios. Do not generate code, but describe the behavior.

     • Unit Tests: Verify the behavior of a single unit in isolation.
       • Example (user registration task): "Test that the register(userData) method in UserService calls UserRepository.save() only if the email is unique and valid."
       • Example (price calculation task): "Test that the calculateTotal(price, tax, discount) function returns the correct value for valid inputs, for zero taxes, and for maximum discounts."
     • Integration Tests: Verify the interaction between multiple components (e.g., controller, service, database).
       • Example (user registration task): "Test that a POST request to the /api/register endpoint with valid data saves a new user in the database and returns status 201."
       • Example (payment integration task): "Test that the complete 'checkout' flow correctly calls the mock payment gateway and handles a success response."

   • Suggest test files to create: For each source file requiring tests, indicate the corresponding test file according to language conventions.

     • Java: UserService.java → UserServiceTest.java
     • TypeScript/NestJS: user.service.ts → user.service.spec.ts
     • Python: user_service.py → test_user_service.py

   • Link Tests to Acceptance Criteria: Ensure that for each functional acceptance criterion, there is at least one test scenario that verifies it. This step is critical for guaranteeing traceability.

7. Present task structure to the user only if major restructuring, optional tasks, or scope gaps were detected. Otherwise generate the files directly and summarize the resulting plan.

---

Phase 5: Task List Generation

Goal: Generate the task list markdown file and individual task files with technical details

Actions:

1. Generate a unique task ID for each task (e.g., TASK-001, TASK-002)

2. Extract feature name from folder (remove ID prefix, e.g., 001-hotel-search-aggregation → hotel-search-aggregation)

3. Create tasks directory: docs/specs/[id]/tasks/

4. For each task, create an individual task file with technical details from codebase analysis:

   IMPORTANT: Always include test files in "Files to Create" section for any class that contains business logic, state management, validation, or complex behavior. Test files should be listed alongside source files with clear descriptions of what to test (e.g., "test state transitions", "test validation logic").

---
id: TASK-XXX
title: "[Task Title]"
spec: [resolved spec file path]
lang: [java|spring|typescript|nestjs|react|python|general]
dependencies: [TASK-YYY if applicable]
---

# TASK-XXX: [Task Title]

**Functional Description**: [Functional description of what this task covers]

## Technical Context (from Codebase Analysis)

- **Existing Patterns to Follow**: [patterns from codebase analysis]
- **APIs to Integrate With**: [existing APIs or services]
- **Shared Components**: [existing utilities, services, or modules to use]
- **Conventions**: [coding conventions, naming, structure, framework-specific patterns]

## Implementation Details (File names only, no code)

**Files to Create**:
- `[path/source/1]` - [brief description of its purpose]
- `[path/source/2]` - [brief description of its purpose]
- `[path/test/1]` - [e.g., user.service.spec.ts]
- `[path/test/2]` - [e.g., user.controller.integration.spec.ts]

**Files to Modify** (if applicable):
- `[path/existing/1]` - [what modifications are needed]

## Test Instructions

This section describes **what** to test, not **how** to implement test code.

**1. Mandatory Unit Tests:**
   - `[Source Class/File Name 1]`:
     - [ ] Verify that [method/unit] correctly handles [success scenario].
     - [ ] Verify that [method/unit] throws an exception/error when [error scenario].
     - [ ] Verify that the [specific business rule] logic works as described in the specification.
   - `[Source Class/File Name 2]`:
     - [ ] Test validation of [specific field] with valid, invalid, and borderline values.

**2. Mandatory Integration Tests:**
   - `[Flow/Component Name]`:
     - [ ] Verify that the `[API endpoint]` endpoint with valid data correctly interacts with the database and returns the expected response (e.g., status 201, correct body).
     - [ ] Verify that a call to the `[API endpoint]` endpoint with invalid data **does not** modify the database state and returns an appropriate error (e.g., status 400).

**3. Edge Cases and Error Conditions to Test:**
   - [ ] Send missing or malformed data.
   - [ ] Simulate timeout or failure of an external service.
   - [ ] Test race conditions (if relevant, e.g., double booking).
   - [ ] Test with high data loads or boundary values (e.g., maximum length strings).

**Test Acceptance Criteria**:
   - [ ] All tests described above are implemented and pass.
   - [ ] Test coverage for classes with business logic is >= 80%.

**Dependencies**: [TASK-YYY if applicable, otherwise "None"]

**Implementation Command**:
/developer-kit:devkit.task-implementation --lang=[language] --task="docs/specs/[id]/tasks/TASK-XXX.md"

5. Create the task list index file: docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md

# Task List: [Feature Name]

**Specification**: [resolved spec file path]
**Generated**: [current date]
**Language**: [language]

## Codebase Analysis Summary

- **Project Structure**: [summary from codebase analysis]
- **Key Patterns**: [patterns identified]
- **Integration Points**: [APIs/services to integrate with]

## Task Index

| Task ID | Title | Technical Focus | Status | Dependencies |
|---------|-------|-----------------|--------|--------------|
| [TASK-001](tasks/TASK-001.md) | Task title | [files/components] | [ ] | - |
| [TASK-002](tasks/TASK-002.md) | Task title | [files/components] | [ ] | TASK-001 |

## Tasks

Each task has its own detailed file with technical context:
- [TASK-001](tasks/TASK-001.md): Task title
- [TASK-002](tasks/TASK-002.md): Task title

6. Save all files (including traceability-matrix.md from Phase 5.5)

---

Phase 5.5: Traceability Matrix Generation

Goal: Generate traceability matrix mapping requirements to tasks

Prerequisite: Phase 2 (Requirement Extraction with REQ-IDs) and Phase 4 (Technical Task Decomposition) completed

Actions:

1. Map REQ-IDs to tasks:

   • For each REQ-ID assigned in Phase 2, identify which TASK-XXX covers it
   • A single requirement may be covered by multiple tasks
   • A single task may cover multiple requirements

2. Generate traceability matrix file: Create docs/specs/[id]/traceability-matrix.md:

   # Traceability Matrix: [Feature Name]
   
   **Spec**: [resolved spec file path]
   **Generated**: YYYY-MM-DD
   **Last Updated**: YYYY-MM-DD
   
   ## Coverage Summary
   
   - **Requirements**: N total
   - **Covered by Tasks**: N/N (100%)
   - **With Tests**: N/N (X%)
   - **Implemented**: N/N (X%)
   
   ## Matrix
   
   | REQ ID | Requirement | Task(s) | Test Files | Code Files | Status |
   |--------|-------------|---------|------------|------------|--------|
   | REQ-001 | User can search by destination | TASK-001, TASK-003 | - | - | Pending |
   | REQ-002 | Results paginated | TASK-005 | - | - | Pending |
   

3. Initialize matrix columns:

   • REQ ID: Identifier from Phase 2
   • Requirement: Brief description (first 50 chars)
   • Task(s): Comma-separated TASK-XXX list that cover this requirement
   • Test Files: Leave empty "-" (will be filled by task-review)
   • Code Files: Leave empty "-" (will be filled by task-review)
   • Status: "Pending" until implementation, then "Implemented" after task-review

4. Calculate coverage summary:

   • Total requirements count (from REQ-IDs assigned)
   • Count requirements covered by at least one task (should be 100%)
   • Report coverage percentage in summary section

Phase 6: Review and Confirmation

Goal: Verify the task list quality

Actions:

1. Present the generated task structure to the user:

   • Task list index: docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md
   • Individual tasks: docs/specs/[id]/tasks/TASK-XXX.md

2. Ask for confirmation via AskUserQuestion:

   • Option A: Task list looks good, proceed to summary
   • Option B: Modify specific tasks (specify which)
   • Option C: Regenerate with different decomposition

3. If modifications needed, return to Phase 3

---

Phase 7: Summary

Goal: Document what was accomplished

Actions:

1. Mark all todos complete

2. Summarize:

   • Specification Used: Path to input specification
   • Codebase Analyzed: Yes (language: [language])
   • Key Findings: [patterns, integration points, conventions]
   • Tasks Generated: Number of tasks created
   • Dependency Structure: Brief overview of task dependencies
   • Output Files:
     • Task list: docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md
     • Individual tasks: docs/specs/[id]/tasks/TASK-XXX.md (with technical context)
   • Next Step: Execute tasks using devkit.task-implementation command

3. Provide example commands for implementing tasks:

# Example: Implement a specific task
/developer-kit:devkit.task-implementation --lang=[language] --task="docs/specs/001-feature-name/tasks/TASK-001.md"

# Example: List available tasks in the folder
ls docs/specs/001-feature-name/tasks/

---

Task Dependencies

When tasks have dependencies, the workflow is:

1. Implement tasks with no dependencies first
2. After completing a task, check if dependent tasks can now proceed
3. Use the task list to track progress
4. Each task file contains its dependencies in the frontmatter

Example Dependency Flow

docs/specs/001-user-auth/tasks/TASK-001.md (no dependencies)
    ↓
docs/specs/001-user-auth/tasks/TASK-002.md (depends on TASK-001)
    ↓
docs/specs/001-user-auth/tasks/TASK-003.md (depends on TASK-001)
    ↓
docs/specs/001-user-auth/tasks/TASK-004.md (depends on TASK-002)

---

Language Parameter Effects

The --lang parameter affects only the Implementation Command in each task file:

Language	Implementation Command
java	devkit.task-implementation --lang=java --task="docs/specs/[id]/tasks/TASK-XXX.md"
spring	devkit.task-implementation --lang=spring --task="docs/specs/[id]/tasks/TASK-XXX.md"
typescript	devkit.task-implementation --lang=typescript --task="docs/specs/[id]/tasks/TASK-XXX.md"
nestjs	devkit.task-implementation --lang=nestjs --task="docs/specs/[id]/tasks/TASK-XXX.md"
react	devkit.task-implementation --lang=react --task="docs/specs/[id]/tasks/TASK-XXX.md"
python	devkit.task-implementation --lang=python --task="docs/specs/[id]/tasks/TASK-XXX.md"
php	devkit.task-implementation --lang=php --task="docs/specs/[id]/tasks/TASK-XXX.md"
general	devkit.task-implementation --lang=general --task="docs/specs/[id]/tasks/TASK-XXX.md"

---

Examples

Example 1: User Authentication (Spring Boot)

# Convert specification to tasks
/developer-kit:devkit.spec-to-tasks --lang=spring --task=docs/specs/001-user-auth/

Output structure:

docs/specs/001-user-auth/
├── 2026-03-07--user-auth-specs.md
├── 2026-03-07--user-auth--tasks.md
└── tasks/
    ├── TASK-001.md
    ├── TASK-002.md
    ├── TASK-003.md
    ├── TASK-004.md
    ├── TASK-005.md
    └── TASK-006.md

Sample task file (TASK-001.md):

---
id: TASK-001
title: "User registration endpoint"
spec: docs/specs/001-user-auth/2026-03-07--user-auth-specs.md
lang: spring
dependencies: []
---

# TASK-001: User registration endpoint

**Functional Description**: Implement user registration with email validation

## Technical Context (from Codebase Analysis)
- **Existing Patterns to Follow**: REST controllers in src/main/java/.../controller/
- **APIs to Integrate With**: Existing UserRepository
- **Conventions**: @RestController, @Valid annotations

## Implementation Details (File names only, no code)

**Files to Create**:
- `src/main/java/.../controller/AuthController.java` - Controller for registration
- `src/main/java/.../service/UserService.java` - Business logic service
- `src/test/java/.../controller/AuthControllerTest.java` - Controller tests
- `src/test/java/.../service/UserServiceTest.java` - Service tests

**Files to Modify**:
- `src/main/java/.../config/SecurityConfig.java` - Add public endpoint

## Test Instructions

This section describes **what** to test, not **how** to implement test code.

**1. Mandatory Unit Tests:**
   - `UserService`:
     - [ ] Verify that the `register(userData)` method calls `UserRepository.save()` only if the email is unique.
     - [ ] Verify that `EmailAlreadyExistsException` is thrown when the email is already registered.
     - [ ] Verify that the password is encoded before saving.
   - `AuthController`:
     - [ ] Test email validation with valid, invalid, and missing formats.
     - [ ] Verify that the controller returns status 201 for successful registration.

**2. Mandatory Integration Tests:**
   - `Registration Flow`:
     - [ ] Verify that a POST request to the `/api/v1/users/register` endpoint with valid data saves a new user in the database and returns status 201.
     - [ ] Verify that a request with duplicate email returns status 409 and does not modify the database.

**3. Edge Cases and Error Conditions to Test:**
   - [ ] Send malformed email (e.g., without @).
   - [ ] Send too short password (e.g., less than 8 characters).
   - [ ] Send malformed JSON payload.

**Test Acceptance Criteria**:
   - [ ] All tests described above are implemented and pass.
   - [ ] Test coverage for UserService is >= 80%.

**Implementation Command**:
/developer-kit:devkit.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"

Example 2: E-commerce Checkout (TypeScript)

/developer-kit:devkit.spec-to-tasks --lang=typescript docs/specs/005-checkout-flow/

Example 3: API Integration (Python)

/developer-kit:devkit.spec-to-tasks --lang=python docs/specs/010-payment-integration/

Example 4: Full Workflow (after task generation)

# Step 1: Generate tasks from specification
/developer-kit:devkit.spec-to-tasks --lang=nestjs docs/specs/003-notification-system/

# Step 2: Implement tasks in dependency order
/developer-kit:devkit.task-implementation --lang=nestjs --task="docs/specs/003-notification-system/tasks/TASK-001.md"
/developer-kit:devkit.task-implementation --lang=nestjs --task="docs/specs/003-notification-system/tasks/TASK-002.md"

---

Integration with devkit.task-implementation

The task list generated by this command feeds directly into /developer-kit:devkit.task-implementation:

# After generating tasks, implement each one:

# Option 1: Implement all tasks (sequentially)
/developer-kit:devkit.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"
# (complete, then)
/developer-kit:devkit.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-002.md"
# ...

# Option 2: Implement tasks in dependency order
# Start with tasks that have no dependencies
# Progress through the dependency graph

# Option 3: Pick specific task to work on
/developer-kit:devkit.task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-003.md"

---

Todo Management

Throughout the process, maintain a todo list like:

[ ] Phase 1: Specification Analysis
[ ] Phase 2: Requirement Extraction
[ ] Phase 3: Codebase Analysis
[ ] Phase 4: Technical Task Decomposition
[ ] Phase 5: Task List Generation
[ ] Phase 6: Review and Confirmation
[ ] Phase 7: Summary

Update the status as you progress through each phase.

---

Note: This command follows the "divide et impera" (divide and conquer) principle — splitting complex problems into simpler, manageable tasks. Each task can be implemented independently, with clear dependencies and acceptance criteria.