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 /skill:specs-kit-brainstorm and converts it into atomic, executable tasks.
Input: docs/specs/[id]/YYYY-MM-DD--feature-name.md
Output:
- Task list:
docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md - Data model:
docs/specs/[id]/data-model.md - Contracts:
docs/specs/[id]/contracts/* - 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 → Architecture & Ontology Definition → Tasks → Implementation → Review → Code Cleanup → Done
(brainstorm) (this: Phase 1.5) (this) (task-implementation) (task-review) (code-cleanup)
Task Count Limit
CRITICAL: If task decomposition produces more than 15 implementation tasks, the specification is too large for a single implementation cycle and MUST be rejected:
-
Detect oversized spec: After Phase 4 (Task Decomposition), count implementation tasks (excluding documentation and cleanup tasks)
-
If > 15 tasks:
- STOP task generation immediately
- Inform the user with this message:
Specification Too Large This specification would generate X implementation tasks, which exceeds the maximum of 15. The scope is too large for a single implementation cycle. Recommended action: 1. Return to /skill:specs-kit-brainstorm 2. Split your idea into 2 or more smaller, focused specifications 3. Run /skill:specs-kit-spec-to-tasks for each specification separately Example split strategy: - Spec Part 1: Core functionality (must-have for initial release) - Spec Part 2: Extended features (phase 2 or nice-to-have) - Spec Part 3: Additional capabilities (future iterations) This ensures each specification has a clear functional scope and manageable implementation scope.- Use ask_user_question to offer options:
- Options:
- "Return to /skill:specs-kit-brainstorm to split this idea" (recommended)
- "Continue anyway with this large specification" (not recommended - proceed at user risk)
- Options:
- If user chooses "Return to brainstorm": abort task generation and suggest running
/skill:specs-kit-brainstormwith the split idea - If user chooses "Continue anyway": proceed with warning logged in summary
-
If <= 15 tasks: Proceed normally with task generation
Per-Task Size Limit
CRITICAL: The spec-level ceilings above do not measure the size of a single task, and an oversized task is what makes a loop run retry the same work over and over. From the measured runs (getokens specs 011–015): tasks that passed review at the first attempt declare a median of 5 files; tasks that needed 3 or more attempts declare a median of 8 files, and no task declaring more than 8 files passed at the first attempt. Acceptance-criteria count is a weaker signal (median 4 in both groups), so it guards against ambiguity rather than size.
Before writing any task file (Phase 4, step 8), check each planned task against these ceilings:
- More than 8 files declared in "Files to Create/Modify" (Implementation Details)
- More than 6 acceptance criteria in the task's Acceptance Criteria section
If a task exceeds either ceiling:
- Do not write its task file yet
- Propose a split with ask_user_question:
Oversized Task Task "[title]" declares N files / M acceptance criteria, above the per-task ceiling (8 files, 6 acceptance criteria). Tasks this size measurably need repeated implementation attempts to land. Proposed split: - Task A: [sub-scope with its files and criteria] - Task B: [sub-scope with its files and criteria]- Options:
- "Split the task as proposed" (recommended)
- "Keep the task as it is" (not recommended - expect repeated attempts in the loop)
- Options:
- If the user splits: replace the task with the parts, re-check the parts against the ceilings, and re-check the total task count against the 15-task limit
- If the user keeps it: proceed and record a warning in the Phase 7 summary, next to any spec-level warning
Usage
# Basic usage - specify spec file or folder
/skill:specs-kit-spec-to-tasks docs/specs/001-hotel-search-aggregation/
/skill:specs-kit-spec-to-tasks docs/specs/001-hotel-search-aggregation/2026-03-07--hotel-search-aggregation.md
Arguments
| Argument | Required | Description |
|---|---|---|
--spec |
No | Path to spec folder (e.g., docs/specs/001-feature-name/) |
--kg-only |
No | Only refresh the codebase graph, skip task generation |
Examples
Basic Usage
/skill:specs-kit-spec-to-tasks docs/specs/001-feature/
KG-Only Mode
/skill:specs-kit-spec-to-tasks docs/specs/001-feature/ --kg-only
Inputs
Determine the target specification from the invocation context:
- when invoked directly, the spec folder (
--spec=) arrives as a skill argument; - otherwise infer the spec folder from the current working directory.
Resolve, in order:
spec→ the spec folder path (required); if not provided, ask the user--kg-only→ restrict to codebase graph refresh when set
If no spec folder can be determined, stop and inform the user.
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 a checklist: 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.
- Mandatory final tasks: Every spec MUST end with (1) a documentation task and (2) a code cleanup task
- Spec size limit: If > 15 implementation tasks, reject and recommend returning to brainstorm. If a single task exceeds the per-task ceiling (>8 declared files or >6 acceptance criteria), propose a split before writing its task file
Phase 1: Specification Analysis
Goal: Read and understand the functional specification
Input: the skill arguments (spec file or folder path)
Actions:
-
Create todo list with all phases
-
Parse the skill arguments to extract:
spec-path(path to spec file or folder)
-
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:
YYYY-MM-DD--feature-name.md- the only dated spec-like markdown file in the folder excluding
--tasks.md,decision-log.md,traceability-matrix.md,user-request.md, andbrainstorming-notes.md
-
Read the resolved functional specification file
-
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
- Search for these specific files that contain the original user request:
-
Extract the spec ID from folder name (e.g.,
001-hotel-search-aggregation) -
Verify the specification exists and is valid
-
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
-
Quality Pre-Check (Soft Gate):
- Check for section
## Clarificationsin the spec file (added by spec-check) - Search for vague terms: grep for "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 ask_user_question:
- Options:
- "Continue anyway" (proceed at user risk)
- "Run spec-check first" (recommended:
/skill:specs-kit-spec-check docs/specs/[id]/)
- Options:
- If Clarifications section exists OR no vague terms found: proceed without warning
- Check for section
Phase 1.5: Architecture & Ontology Definition
Goal: Ensure the project-level architecture and ontology documents exist and are consistent before generating tasks. This phase bridges the gap between WHAT (functional specification) and HOW (technical tasks).
Context: The architecture and ontology documents live at the docs/specs/ level (shared across all specifications):
docs/specs/architecture.md— Formalizes technological and infrastructural choicesdocs/specs/ontology.md— Establishes common domain language (Ubiquitous Language)
Step 1: Architecture Definition (docs/specs/architecture.md)
-
Check if
docs/specs/architecture.mdexists:-
If the file does NOT exist:
-
Inform the user: "No project architecture document found. Before generating tasks, we need to define the project architecture."
-
Use ask_user_question to gather architecture information through targeted questions:
Question 1 — Software Stack:
What is the primary technology stack for this project?- Options:
- "Java / Spring Boot"
- "TypeScript / NestJS"
- "TypeScript / React"
- "Python / Django or FastAPI"
- "PHP / Laravel or Symfony"
- Freeform: allow custom answer
Question 2 — Data Architecture:
What database and data management approach does the project use?- Options:
- "PostgreSQL (relational)"
- "MySQL (relational)"
- "MongoDB (document-based)"
- "Multiple databases (polyglot persistence)"
- Freeform: allow custom answer
Question 3 — Infrastructure:
What hosting and infrastructure approach is used?- Options:
- "AWS (EC2, ECS, Lambda, etc.)"
- "Docker / Docker Compose (local or self-hosted)"
- "Kubernetes"
- "Serverless (AWS Lambda, GCP Cloud Functions)"
- "Not yet decided"
- Freeform: allow custom answer
- Options:
-
Create
docs/specs/architecture.mdusing the gathered information:- Read the architecture template using this lookup order:
templates/architecture.md, thentemplates/architecture.mdinside the installed skill folder for non-Claude agents - Fill the gathered answers into the placeholder sections of the template
- Set
**Created**and**Last Updated**to the current date - Write the result to
docs/specs/architecture.md
The template defines these sections:
# Section Source Question 1 Logical Architecture Gather from user or leave as scaffold 2 Infrastructure Architecture Question 3 above 3 Software Architecture Questions 1 & 2 above 4 Security Constraints Default template values 5 AI Guardrails Default template values - Read the architecture template using this lookup order:
-
Log the creation and present to the user for final confirmation
-
-
If the file ALREADY exists:
- Read
docs/specs/architecture.md - Load the architecture context into memory for use in task generation (Phase 4)
- Briefly summarize what was loaded:
Loaded project architecture: - Logical Architecture: [bounded contexts summary] - Infrastructure: [hosting/scaling summary] - Stack: [detected from the codebase] - Database: [database]
- Read
-
Step 2: Ontology Definition (docs/specs/ontology.md)
-
Check if
docs/specs/ontology.mdexists:-
If the file does NOT exist:
- Extract domain terms from the specification loaded in Phase 1
- Use ask_user_question to present identified terms and gather additional ones:
I identified the following domain terms from the specification: - [Term 1]: [proposed definition] - [Term 2]: [proposed definition] - ... Should I create the project ontology with these terms? You can also add or adjust terms.- Options:
- "Yes, create with these terms" (recommended)
- "Yes, but let me adjust the terms first"
- "Skip ontology creation for now"
- Options:
- If confirmed, create
docs/specs/ontology.md:# Project Ontology — Ubiquitous Language **Created**: [current date YYYY-MM-DD] **Last Updated**: [current date YYYY-MM-DD] ## Domain Glossary | Term | Definition | Bounded Context | |------|-----------|-----------------| | [Term 1] | [Definition] | [Context where this term applies] | | [Term 2] | [Definition] | [Context where this term applies] | ## Bounded Contexts | Context | Description | Key Terms | |---------|-------------|-----------| | [Context 1] | [Description of this bounded context] | [Key terms] | ## Conceptual Mapping [Relationships between key domain entities]
-
If the file ALREADY exists:
- Read
docs/specs/ontology.md - Load the ontology context into memory for use in task generation
- Extract domain terms from the current specification
- Compare against existing glossary entries
- If NEW terms are identified:
- Append them to the Domain Glossary table
- Update the
Last Updateddate - Inform the user of the additions
- If no new terms: continue silently
- Read
-
Step 3: Context Summary
After both documents are processed, produce a brief summary:
Architecture & Ontology Context:
- Architecture: [loaded/created] — [stack summary]
- Ontology: [loaded/created/skipped] — [N terms in glossary]
- Both documents will inform task generation in Phase 4.
Phase 2: Requirement Extraction
Goal: Extract and organize requirements from the specification
Actions:
-
Analyze the specification for:
- User stories and use cases
- Business rules
- Acceptance criteria
- Integration requirements
-
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
-
Group related requirements:
- Identify naturally atomic units of work
- Note dependencies between requirements
- Prioritize based on dependencies (what can be done first)
-
CRITICAL: Verify against original user request:
- Using the
user-request.mdcontent 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 ask_user_question 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"
- "I found requirements from your original request that may not be in the specification:"
- Using the
-
Present the extracted requirements structure (including technical requirements) to user for confirmation
-
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 Codebase Graph
Goal: Load the codebase graph produced by graphify, if it exists and is fresh
Prerequisite: Requires the spec folder path
Actions:
-
Check for the codebase graph:
- Look for
graphify-out/graph.jsonin the project root - If it does not exist, run
/graphify <project-root>once to materialise it (this is the single graph the rest of the workflow reads), then proceed - If graphify is not installed, skip to Phase 3 (in-session Codebase Analysis) and note that the graph is unavailable
- Look for
-
If the graph exists:
- Read its
updated_attimestamp - 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
- Read its
-
Present summary to user:
Found codebase graph 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 graph is [fresh/getting stale/old]. -
Choose reuse strategy automatically unless the case is borderline:
- If the graph is < 7 days old: use it automatically
- If the graph is > 30 days old: re-run
/graphify <project-root> --updateautomatically - If the graph is 7-30 days old: ask user via ask_user_question whether to reuse or refresh
-
Based on the chosen strategy:
- Use cached: Load the graph into context, skip Phase 3, proceed to Phase 4
- Refresh: Re-run
/graphify <project-root> --update, then load it and proceed to Phase 4 (Phase 3 is only for the in-session exploration the graph cannot replace)
-
If using the cached graph:
- Read patterns, components and APIs directly from
graphify-out/graph.json - Store results in context for Phase 4 (Task Decomposition)
- Note: "Proceeding with the codebase graph from X days ago"
- Read patterns, components and APIs directly from
The graph is project-wide by construction (graphify indexes the whole codebase),
so there is no separate "global" graph to load — graphify-out/graph.json already
covers project-level patterns and conventions.
Phase 3: Codebase Analysis
Goal: Understand existing codebase to generate technically accurate tasks
Prerequisite: Requires the spec folder path
Actions:
- Explore the codebase yourself (there is no subagent dispatch; do it in this session). Detect the stack from the project's manifest files (
package.json,pom.xml/build.gradle,composer.json,pyproject.toml/requirements.txt,go.mod, etc.) and adapt the focus below to what you find:
Explore the codebase to understand:
1. **Project Structure**:
- Main directories and their purpose
- Configuration files and build tooling
- Entry points and main modules
2. **Existing Patterns**:
- Data models/schemas and persistence approach (ORM, raw queries, migrations)
- API patterns (REST, GraphQL, RPC) and their conventions
- Authentication/authorization patterns
- Error handling and logging conventions
3. **Technology Stack**:
- Frameworks and libraries in use (detected from manifests/lock files)
- Database systems and external service integrations
- Build, test and deployment tooling
4. **Integration Points**:
- Existing APIs the new feature must integrate with
- Shared utilities, helpers or common components
- Configuration management
5. **Code Organization & Testing**:
- Layering and module boundaries
- Dependency injection / composition patterns
- Test directory structure, framework and conventions
Provide a summary that will inform task generation with the detected stack's specific context.
- Collect and synthesize the codebase analysis
- 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: Specification Artifact Generation
Goal: Always derive stable specification artifacts before task generation
Prerequisite: Phase 2 (Requirement Extraction) must have completed. Phase 3 findings may be used only to align naming with the existing codebase.
Actions:
-
Generate
data-model.mdfrom the specification:- Create/update
docs/specs/[id]/data-model.md - Use the resolved specification,
user-request.md, andbrainstorming-notes.mdas the source of truth - Incorporate canonical terminology from
docs/specs/ontology.mdwhen available - Capture:
- Core entities, value objects, and aggregates
- Relationships and cardinality
- Lifecycle/state transitions if relevant
- Business invariants and validation rules
- Persistence or integration notes explicitly stated in the specification
- Create/update
-
Create/update the
contracts/directory:- Ensure
docs/specs/[id]/contracts/exists - Extract every explicit interface or integration boundary described by the specification
- Create one contract artifact per boundary using the most appropriate format:
- HTTP/API boundary:
[name].openapi.yaml - Async event/message boundary:
[name].event.md - Internal service/UI boundary without a formal schema:
[name].md
- HTTP/API boundary:
- Ensure
-
Populate each contract artifact with implementation-neutral details:
- Required inputs and outputs
- Validation rules and required fields
- Success responses or emitted events
- Error cases and failure modes
- Versioning or backward-compatibility notes if stated in the spec
-
Handle specs without explicit external contracts:
- Still create
docs/specs/[id]/contracts/ - Add
contracts/README.mdsummarizing why no standalone interface contract files were extracted yet - Document any implicit boundaries that tasks must preserve
- Still create
-
ARTIFACT FIDELITY GATE (prevents Over-Specification Drift):
- Before proceeding to Phase 4, verify that every entity, field, and relationship in
data-model.mdcan be traced back to the functional specification - For each element in
data-model.md, ask: "Is this explicitly required by the spec, or is it my technical interpretation?" - If an element is NOT derivable from the spec:
- Mark it with
(derived)in the data-model.md - Do NOT create acceptance criteria around it in task files
- It may appear in "Technical Context" as an implementation suggestion, never as a requirement
- Mark it with
- Example:
WorktreeStatestruct is NOT in the spec — it is a derived implementation detail. It must be marked(derived)and never appear as "WorktreeState must be defined" in any task's AC.
- Before proceeding to Phase 4, verify that every entity, field, and relationship in
-
Treat artifacts as advisory inputs for task generation:
- Phase 4 and Phase 5 may read
data-model.mdandcontracts/*for context - Tasks must use these artifacts ONLY to inform implementation choices, NEVER as source of truth for acceptance criteria
- The functional specification (with its
[IMP]/[SEF]/[EXT]taxonomy) is the ONLY source of truth for acceptance criteria - Critical distinction: If
data-model.mddefinesWorktreeManagerbut the spec does NOT mention it, the task cannot have "WorktreeManager interface must be defined" as an AC. The task AC must reflect the spec's language (e.g., "Worktree can be created via CLI command").
- Phase 4 and Phase 5 may read
-
Do NOT update agent context files in this phase:
- Do not call
/skill:specs-kit-spec-sync-context - Do not create or modify
graphify-out/graph.json(graphify owns it) - Do not rewrite task files or any other context cache as part of artifact generation
- Do not call
-
Log and report:
Specification artifacts generated: - Data model: docs/specs/[ID]/data-model.md - Contracts directory: docs/specs/[ID]/contracts/ - Contract files: [list generated files] - Fidelity Gate: [N] elements from spec, [M] elements derived (marked)
Note: This phase always runs, even when the cached codebase graph is reused in Phase 2.5.
Phase 4: Technical Task Decomposition
Goal: Break down [IMP] requirements into atomic, executable tasks. Respect bounded context boundaries and avoid over-specification.
CRITICAL: Spec Fidelity Gate — Before decomposing tasks, verify:
- The functional specification contains acceptance criteria tagged with
[IMP],[SEF], or[EXT] - If tags are MISSING: apply taxonomy retroactively based on the spec's content, then proceed
- If the spec has a "Bounded Context Impact Statement" (Section 6): load it and use it for boundary validation
- If the spec has NO
[IMP]criteria: STOP — the spec is purely descriptive. Return to brainstorming.
Actions:
- Filter requirements by taxonomy — ONLY
[IMP]criteria generate implementation tasks:- Read the functional specification's acceptance criteria
- Select ONLY criteria tagged
[IMP](Implementable) for task decomposition [SEF]criteria: Do NOT generate standalone tasks. They will be verified in the documentation task (TASK-N-1).[EXT]criteria: Do NOT generate standalone tasks. They will be listed as checkpoints in the documentation task.- Example: If AC-5 (
git worktree listshows worktree) is[SEF], it does NOT get a task. It is a natural side effect of usinggit worktree add, which is covered by AC-1's task. - Why this matters: Creating tasks for
[SEF]criteria produces "false work" — tasks that verify natural behavior rather than implement functionality. In spec 025, AC-5 (git worktree list) and AC-2 (second run reuses) are[SEF]and should not generate dedicated tasks.
1.0. Load the project learnings (if present):
- Read
docs/specs/learnings.md: it is the memory the loop writes after every run, and it includes how many attempts past tasks needed and what stopped them - Apply its lessons while decomposing: task shapes that previously needed repeated attempts (too many files, ambiguous scope, cross-context changes) must be split or sharpened now, not paid for again in the loop
1.1. If codebase graph context is available (from Phase 2.5 cached only):
- 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"
1.2. BOUNDED CONTEXT BOUNDARY CHECK (prevents Boundary Confusion Drift):
- Load
docs/specs/ontology.mdand extract the bounded context definitions - Load the spec's "Bounded Context Impact Statement" (Section 6) if present
- For each task, before assigning file targets, determine the bounded context of each file
- If a task targets files in a bounded context DIFFERENT from the feature's primary context:
- Flag the task as
CROSS-BOUNDARY - Add a warning in the task's Technical Context:
⚠️ BOUNDARY CROSSING: This task modifies [file] which belongs to [bounded context]. Primary context of this feature: [primary context]. Justification required: Why is this modification in [bounded context] necessary? Recommended: Coordinate with [bounded context] owner or consider if the change belongs there. - Example: TASK-005 modifies
cmd/specs-kit/task_run.go(Core Engine) for a Git Worktree feature. This is a HIGH RISK cross-boundary modification and must be flagged.
- Flag the task as
- If Architecture context is available (from Phase 1.5):
- Use the technology stack to inform implementation details in each task
- Ensure tasks reference the correct frameworks, libraries, and patterns from
docs/specs/architecture.md - Framework version migration notes: when the framework version detected in the codebase
is a major release (e.g. Spring Boot 4.x, React 19, Angular 18), include any known
migration impacts in the task's Technical Context under the
Framework & Versionbullet: relocated packages, renamed annotations, new required dependencies, deprecated APIs the task might reference. Draw these from the agent's own training knowledge — the goal is to save the implementation agent from a compile-error → web-search → fix cycle. - If tasks require new infrastructure components not in the architecture document, flag them
for ADR tracking using the
adr-draftingskill
1.3. EXTERNAL DEPENDENCY PRE-FLIGHT (prevents Dependency Blindness):
- Before generating a task that depends on an external interface (e.g., "ADR-038 BranchCreator", "existing API", "third-party service"):
- Verify that the interface exists in the codebase OR is documented in a contract
- If the interface does NOT exist:
- Mark the task as
EXTERNAL_DEPENDENCY_RISK - Add a warning in the task's Technical Context:
⚠️ EXTERNAL DEPENDENCY: This task depends on [interface] which was not found in the codebase. Risk: If [interface] does not exist or has a different signature, this task may fail at contract validation (T-3.6). Mitigation: Verify [interface] exists before implementing this task, or implement it first.
- Mark the task as
- Example: TASK-007 depends on
BranchCreator.EnsureBranch(specID, specName)from ADR-038. If ADR-038 is not yet implemented, this task must be flagged.
1.5. AGENT-EXECUTABILITY GATE (prevents tasks no agent can close):
- For every candidate task, each acceptance criterion and each Definition of Done item must be satisfiable by an agent working in the repository — by writing a file, running a command, or asserting a test.
- If any item requires an account, a credential, a signature, a purchase, a human decision or
access the agent does not have, the task is not emitted. There is no tag that makes such a
task runnable: a title carrying
[PROCUREMENT]or[MANUAL]is the signal that the task should not have been generated at all. - The underlying need does not disappear, it moves out of the loop's reach:
- record it in the
## Preconditions (operator)section of the tasks document, one line per action a person must have completed before the run starts; - the agent-executable residue of that work, if any, becomes an ordinary task — "author the ADR recording the chosen provider and its verification" is a good task; "put the credential in the vault" is not, and belongs in the preconditions;
- a task that consumes a precondition states its resolution in its DoR, exactly as it does for a task dependency.
- record it in the
- Why this matters: the implementation cannot satisfy such a criterion, the review is right to reject it every time, and the retries spend the task's whole spawn allowance before the run stops on it — taking every task after it with it. A task file that carries operator-only work is also refused at load, before a single agent session is spent.
1.4. If Ontology context is available (from Phase 1.5):
- Use domain terms from
docs/specs/ontology.mdconsistently in task titles, descriptions, and acceptance criteria - Ensure task descriptions use the canonical term from the glossary (avoid synonyms not defined in the ontology)
- If a task introduces NEW domain concepts not in the ontology, add them to
docs/specs/ontology.mdand update theLast Updateddate - Example: If ontology defines "Reservation" (not "Booking"), use "Reservation" in all task descriptions
-
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
-
For each task, define:
- Title: Concise, descriptive name (e.g., "User login functionality")
- Description: What the task covers functionally — must map to one or more
[IMP]acceptance criteria - AC-ID Mapping: List the acceptance criteria IDs this task implements (e.g., AC-1, AC-3)
- REQ-ID Mapping: List the requirement IDs this task covers (e.g., REQ-001)
- Acceptance Criteria: 2-4 testable conditions derived ONLY from
[IMP]spec criteria - Definition of Ready (DoR): Clear preconditions for starting (dependencies complete, technical context understood, blockers resolved)
- Definition of Done (DoD): Clear completion conditions covering implementation, tests, and task handoff
- Dependencies: List task IDs this depends on (if any)
- Cross-Boundary: YES/NO — whether this task modifies files outside the feature's primary bounded context
- External Dependency Risk: YES/NO — whether this task depends on an unverified external interface
- Agent-Executable: every AC and DoD item is satisfiable by an agent (see 1.5). A task that is
not agent-executable is not emitted: its operator half goes to
## Preconditions (operator)and its agent half, if any, becomes an ordinary task
-
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
-
FILE COLLISION DETECTION (prevents File Collision Drift):
- Before generating files, build a file-to-task mapping:
File: pkg/domain/worktree.go - TASK-001: creates WorktreeState - TASK-003: creates WorktreeManager interface → ⚠️ COLLISION: Two tasks create/modify the same file File: cmd/specs-kit/task_run.go - TASK-005: adds cleanup call - TASK-006: adds preserve-on-failure logic → ⚠️ COLLISION: Two tasks modify the same file- If collisions are detected:
- Merge the colliding tasks into a SINGLE task with combined acceptance criteria
- OR split the file responsibilities so each task targets a different file
- Add a note in the merged task explaining the collision and the merge decision
- For new files: If two tasks create the same file, merge them.
- For existing files: If two tasks modify the same file, merge them OR split by having one task create a hook/extension point and the other use it.
-
Validate dependencies before generating files:
- Present the dependency structure in a clear table format:
Task ID Title Dependencies Cross-Boundary? Ext. Dependency Risk? TASK-001 [Title] None No No TASK-002 [Title] TASK-001 No Yes — ADR-038 TASK-003 [Title] TASK-001 YES — Core Engine No ... ... ... ... ... - If there are circular dependencies, high coupling, or unclear ordering, use ask_user_question to confirm a fix
- If cross-boundary tasks exist without justification: warn and ask for confirmation
- Otherwise proceed directly and include the dependency table in the generated summary
-
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 inUserServicecallsUserRepository.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."
- Example (user registration task): "Test that the
- 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/registerendpoint 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."
- Example (user registration task): "Test that a POST request to the
- Unit Tests: Verify the behavior of a single unit in isolation.
-
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
- Java:
-
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.
5.1 TEST INSTRUCTIONS FIDELITY CHECK (prevents Self-Referential Test Drift):
- After generating test instructions, validate each test scenario against the functional specification:
- Ask: "Is this behavior explicitly mentioned in the spec's acceptance criteria or business rules?"
- If YES: Keep the test scenario
- If NO — the scenario is a 'best practice' or 'common edge case':
- Remove it from the task's test instructions
- Instead, add it to the documentation task (TASK-N-1) as a "Supplemental Verification" — a nice-to-have check, not a blocking requirement
- Banned test scenarios (unless explicitly in the spec):
- Network errors for local filesystem operations (e.g., git worktree)
- Mocking requirements for external tools unless the spec requires testability
- Performance tests unless the spec defines performance criteria
- Concurrency/race condition tests unless the spec mentions concurrent access
- Example from spec 025:
- "Network error during branch creation" → REMOVE (git worktree is local filesystem)
- "Tests use mocking for git commands" → REMOVE (not a spec requirement)
- "Git is not available on system" → KEEP only if spec explicitly mentions it (AC-3 in 025 does)
-
-
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.
-
CRITICAL: Add Mandatory Final Tasks — After generating all implementation tasks, ALWAYS add these two final tasks:
TASK-N-1: Documentation Task (where N is the next task number)
- Title: "Documentation for [Feature Name]"
- Description: Produce comprehensive documentation for the implemented feature
- Dependencies: ALL previous implementation tasks (TASK-001 through TASK-N-2)
- Purpose: Ensure the feature is properly documented for users, agents, and developers
- Documentation artifacts to produce:
- README: Feature-level README covering overview, usage examples, configuration, and troubleshooting
- AGENTS: Update or create AGENTS.md files for any agents that interact with or operate this feature
- Technical Notes: Developer-facing documentation covering architecture decisions, API contracts, integration patterns, and operational runbooks
- Files to Create/Update:
docs/specs/[id]/README.md— Feature README with usage and configurationdocs/specs/[id]/TECHNICAL-NOTES.md— Developer documentationAGENTS.md(project-level or context-specific) — Agent interaction documentation- Any additional context-specific documentation files
- Content requirements for README:
- Clear feature description and purpose
- Setup/configuration instructions
- Usage examples (CLI, API, or UI as applicable)
- Common error scenarios and resolutions
- Links to related docs or features
- Content requirements for Technical Notes:
- Architecture overview (diagram or text description)
- Key components and their responsibilities
- API contracts or integration boundaries
- Configuration options and defaults
- Operational considerations (logging, monitoring, deployment)
- Implementation Command:
/skill:specs-kit-task-implementation --task="docs/specs/[id]/tasks/TASK-N-1.md"
TASK-N: Code Cleanup & Workspace Hygiene Task (FINAL task)
- Title: "Code Cleanup & Workspace Hygiene for [Feature Name]"
- Description: Final cleanup using specs-kit-code-cleanup skill to remove dead code, debug logs, and temporary files
- Dependencies: TASK-N-1 (documentation task)
- Purpose: Ensure production-ready code quality and clean workspace
- Must perform:
- Remove all debug logs (
console.log,System.out.println,print(statements) - Remove debug comments (
// DEBUG:,/* TODO: remove */) - Remove temporary files created during development
- Remove unused imports and optimize imports
- Run code formatter (Spotless for Java, Prettier for TypeScript, Black for Python)
- Fix indentation and line length (>120 chars)
- Remove obviously safe dead code (unused private methods, unreachable code)
- Verify documentation headers are complete
- Run final linting and tests
- Remove all debug logs (
- Implementation Command:
/skill:specs-kit-code-cleanup --task="docs/specs/[id]/tasks/TASK-N.md" - CRITICAL: This task MUST use the
specs-kit-code-cleanupskill. Reference the skill documentation for exact procedures.
-
Verify task count and spec size:
- Count total implementation tasks (excluding documentation and cleanup tasks)
- If > 15 implementation tasks: Trigger rejection logic (see Task Count Limit section)
- STOP task generation
- Present warning message to user
- Offer to return to brainstorm or continue anyway
- If <= 15 tasks: Proceed with task file generation
- Per-task size: check every planned task against the Per-Task Size Limit section (more than 8 declared files or more than 6 acceptance criteria): propose a split before writing its task file, and record a "continued anyway" warning in the Phase 7 summary if the user keeps the oversized task
Phase 5: Task List Generation
Goal: Generate the task list markdown file and individual task files with technical details
Actions:
-
Generate a unique task ID for each task (e.g., TASK-001, TASK-002)
-
Extract feature name from folder (remove ID prefix, e.g.,
001-hotel-search-aggregation→hotel-search-aggregation) -
Create tasks directory:
docs/specs/[id]/tasks/ -
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").
Read the task template using this lookup order:
templates/task.mdtemplates/task.mdinside the installed skill folder for non-Claude agents. Fill in the gathered information for each task and write todocs/specs/[id]/tasks/TASK-XXX.md.
The task template defines these sections:
Section Purpose Frontmatter id, title, spec, status, dependencies, ac-mapping, imp-requirements Functional Description What this task covers, mapped to [IMP] criteria Cross-Boundary Warning (optional) Flag cross-context modifications External Dependency Risk (optional) Flag unverified dependencies Acceptance Criteria Functional criteria derived ONLY from [IMP] spec criteria Definition of Ready (DoR) Pre-flight checklist before starting Technical Context Patterns, APIs, conventions from codebase analysis Implementation Details Files to create/modify (names only, no code) Test Instructions What to test (unit, integration, edge cases) Definition of Done (DoD) Completion checklist --- id: TASK-XXX title: "[Task Title]" spec: [resolved spec file path] status: pending dependencies: [TASK-YYY if applicable] ac-mapping: [AC-1, AC-3] imp-requirements: [REQ-IDs of [IMP] criteria this task covers] --- # TASK-XXX: [Task Title] **Functional Description**: [Functional description of what this task covers — must map to one or more `[IMP]` criteria] **Maps to Specification**: [AC IDs this task implements, e.g., AC-1, AC-3] ## ⚠️ Cross-Boundary Warning (if applicable) <!-- Remove this section if not cross-boundary --> - **Primary Context**: [feature's bounded context] - **This Task Modifies**: [file] in [different bounded context] - **Risk**: HIGH / MEDIUM / LOW - **Justification**: [why this cross-boundary modification is necessary] ## ⚠️ External Dependency Risk (if applicable) <!-- Remove this section if no external dependency --> - **Depends on**: [external interface, e.g., ADR-038 BranchCreator] - **Status**: Verified / Unverified / At Risk - **Mitigation**: [what to do if the interface doesn't exist or differs] ## Acceptance Criteria - [ ] [Functional criterion 1 — derived ONLY from [IMP] spec criteria, NOT from data-model.md] - [ ] [Functional criterion 2 — must be traceable to a specific AC-ID] - [ ] [Functional criterion 3 if needed] ## Definition of Ready (DoR) Before starting this task, ensure: - [ ] Dependencies are completed or explicitly marked as not required. - [ ] Technical context, patterns, and integration points are understood. - [ ] Files to create/modify are identified and accessible. - [ ] Required tooling, commands, and local prerequisites are available. - [ ] Open questions or blockers have been resolved. ## 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] - **Architecture Reference**: [relevant entries from docs/specs/architecture.md — stack, data layer, infrastructure] - **Framework & Version**: [detected from codebase — e.g. "Spring Boot 4.1.0", "React 19.0", "Django 5.1". If the version triggers known migrations (major-version bump, relocated packages, deprecated APIs), add them as a bullet under this entry so the implementation agent does not discover them at compile time] - **Domain Terms**: [relevant terms from docs/specs/ontology.md — use canonical names consistently] ## 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%. ## Definition of Done (DoD) This task is complete when: - [ ] Functional description is implemented end-to-end. - [ ] All acceptance criteria are met with evidence in code or tests. - [ ] Tests in this task are implemented or updated and passing. - [ ] Required files are created or modified following the documented technical context. - [ ] Any handoff expectations for dependent tasks are documented. **Dependencies**: [TASK-YYY if applicable, otherwise "None"] **Implementation Command**: /skill:specs-kit-task-implementation --task="docs/specs/[id]/tasks/TASK-XXX.md" -
Create the task list index file:
docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.mdRead the task-list template at
templates/task-list.md(in this skill directory) and use it as the document structure. Fill in the task index, codebase analysis summary, operator preconditions, and task type summary.## Preconditions (operator)carries everything the agent-executability gate (Phase 4, 1.5) kept out of the task list: one line per action a person must have completed before the run starts (an account, a credential in the vault, a signed contract, console access), naming which tasks depend on it. Write "None." when there is nothing. This section is never a task and never gets a task file: the loop does not read it, the operator does.# Task List: [Feature Name] **Specification**: [resolved spec file path] **Generated**: [current date] **Stack Detected**: [detected stack summary] ## 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 | | ... | ... | ... | ... | ... | | [TASK-N-1](tasks/TASK-N-1.md) | Documentation | [doc files] | [ ] | TASK-001, TASK-002, ... | | [TASK-N](tasks/TASK-N.md) | Code Cleanup & Hygiene | [all modified files] | [ ] | TASK-N-1 | **Legend**: - [DOCS] = Documentation task (produces README, AGENTS, and technical notes) - [CLEANUP] = Code cleanup task (uses specs-kit-code-cleanup skill) ## 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 - ... - [TASK-N-1](tasks/TASK-N-1.md): End-to-End Testing (validates entire feature) - [TASK-N](tasks/TASK-N.md): Code Cleanup & Workspace Hygiene (final cleanup) ## Task Type Summary - **Implementation Tasks** (TASK-001 to TASK-N-2): Core feature implementation - **Documentation Task** (TASK-N-1): README, AGENTS, and technical notes for the feature - **Cleanup Task** (TASK-N): Final code quality and hygiene cleanup -
Save all files (including
data-model.md,contracts/*, andtraceability-matrix.md) -
Run
/skill:specs-kit-sync [spec-folder] --kg-onlyto initialize technical context
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:
-
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
-
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 ([I] Implementable / [S] Side-Effect / [E] External) - **Covered by Tasks**: N/N (100%) — Note: Only [I] criteria have implementation tasks - **With Tests**: N/N (X%) - **Implemented**: N/N (X%) ## Coverage Type Legend | Type | Meaning | Task Generated? | Verified In | |------|---------|-----------------|-------------| | `[I]` Implementable | Requires new code | YES — dedicated task(s) | Unit + Integration tests | | `[S]` Side-Effect | Natural consequence of [I] | NO — documentation verification only | Documentation task only | | `[E]` External | Verified externally | NO — documentation checkpoint only | Documentation task only | ## Matrix | REQ ID | Type | Requirement | Task(s) | Documentation Checkpoint? | Test Files | Code Files | Status | |--------|------|-------------|---------|-----------------|------------|------------|--------| | REQ-001 | [I] | User can search by destination | TASK-001, TASK-003 | — | - | - | Pending | | REQ-002 | [S] | Results appear in UI automatically | — (docs only) | YES | - | - | Pending | | REQ-003 | [E] | User receives email notification | — (manual) | YES | - | - | Pending | -
Initialize matrix columns:
- REQ ID: Identifier from Phase 2
- Type:
[I],[S], or[E]— copied from the spec's AC taxonomy - Requirement: Brief description (first 50 chars)
- Task(s):
- For
[I]: Comma-separated TASK-XXX list that cover this requirement - For
[S]/[E]: "— (docs only)" or "— (manual)"
- For
- Documentation Checkpoint?:
YESfor[S]/[E], "—" for[I] - 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
-
Calculate coverage summary:
- Total requirements count (from REQ-IDs assigned), broken down by type
- Count
[I]requirements covered by at least one task (should be 100%) - Count
[S]/[E]requirements with documentation checkpoint (should be 100%) - Report separate percentages: "[I] tasks: N/N (100%), [S] docs: N/N (100%), [E] docs: N/N (100%)"
- Why separate: A 100% overall coverage that hides 0% [S]/[E] documentation coverage is misleading. Each type must be tracked independently.
Phase 6: Review and Confirmation
Goal: Verify the task list quality
Actions:
-
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
- Task list index:
-
Ask for confirmation via ask_user_question:
- Option A: Task list looks good, proceed to summary
- Option B: Modify specific tasks (specify which)
- Option C: Regenerate with different decomposition
-
If modifications needed, return to Phase 3
Phase 7: Summary
Goal: Document what was accomplished
Actions:
-
Mark all todos complete
-
Summarize:
- Specification Used: Path to input specification
- Architecture: Loaded or created
docs/specs/architecture.md— [stack summary] - Ontology: Loaded, created, or skipped
docs/specs/ontology.md— [N terms] - Codebase Analyzed: Yes (stack: [detected])
- Key Findings: [patterns, integration points, conventions]
- Specification Artifacts:
- Data model:
docs/specs/[id]/data-model.md - Contracts:
docs/specs/[id]/contracts/*
- Data model:
- Tasks Generated: Number of tasks created (breakdown: X implementation, 1 documentation, 1 cleanup)
- [IMP] Criteria: N criteria → X implementation tasks (each [IMP] should map to at least one task)
- [SEF] Criteria: N criteria → verified in documentation task (no standalone tasks)
- [EXT] Criteria: N criteria → documentation checkpoints (no standalone tasks)
- Quality Gates Passed:
- Spec Fidelity Gate: [PASS / FAIL — retroactive taxonomy applied?]
- BC Boundary Check: [N cross-boundary tasks flagged]
- Ext Dependency Pre-Flight: [N external dependencies flagged]
- File Collision Detection: [N collisions detected and resolved]
- Test Fidelity Check: [N invented test scenarios removed]
- Dependency Structure: Brief overview of task dependencies
- Spec Size Status: [If >15 tasks were detected: "WARNING: Spec exceeds 15-task limit. User chose to continue anyway" OR "Aborted: User returned to brainstorm to split specification"] [If any task exceeded the per-task ceiling: "WARNING: Task TASK-XXX exceeds the per-task size limit (N files / M criteria). User chose to continue anyway"]
- Output Files:
- Task list:
docs/specs/[id]/YYYY-MM-DD--feature-name--tasks.md - Data model:
docs/specs/[id]/data-model.md - Contracts:
docs/specs/[id]/contracts/* - Individual tasks:
docs/specs/[id]/tasks/TASK-XXX.md(with technical context) - Documentation task:
docs/specs/[id]/tasks/TASK-N-1.md(depends on all implementation tasks) - Cleanup task:
docs/specs/[id]/tasks/TASK-N.md(depends on documentation task, uses specs-kit-code-cleanup skill)
- Task list:
- Next Step: Execute tasks using /skill:specs-kit-task-implementation command
- Task Execution Order:
- Implementation tasks (TASK-001 to TASK-N-2) — in dependency order
- Documentation task (TASK-N-1) — produces README, AGENTS, and technical notes
- Cleanup task (TASK-N) — final code quality and hygiene cleanup
-
Provide example commands for implementing tasks:
# Example: Implement a specific task
/skill:specs-kit-task-implementation --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:
- Implement tasks with no dependencies first
- After completing a task, check if dependent tasks can now proceed
- Use the task list to track progress
- 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)
↓
docs/specs/001-user-auth/tasks/TASK-005.md (depends on TASK-003, TASK-004) [Implementation]
↓
docs/specs/001-user-auth/tasks/TASK-006.md (Documentation - depends on TASK-001 to TASK-005)
↓
docs/specs/001-user-auth/tasks/TASK-007.md (Cleanup - depends on TASK-006)
Implementation Command
Each generated task file ends with a manual-invocation hint. The skill is language-agnostic, so every task carries the same command:
/skill:specs-kit-task-implementation --task="docs/specs/[id]/tasks/TASK-XXX.md"
Examples
Example 1: User Authentication (Spring Boot)
# Convert specification to tasks
/skill:specs-kit-spec-to-tasks 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
├── data-model.md
├── contracts/
│ ├── auth-api.openapi.yaml
│ └── auth-session.md
└── tasks/
├── TASK-001.md (User registration endpoint)
├── TASK-002.md (Login endpoint)
├── TASK-003.md (Password reset)
├── TASK-004.md (JWT token management)
├── TASK-005.md (Session management)
├── TASK-006.md (Documentation)
└── TASK-007.md (Code Cleanup & Workspace Hygiene)
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
status: pending
dependencies: []
ac-mapping: [AC-1, AC-4]
imp-requirements: [REQ-001, REQ-004]
---
# TASK-001: User registration endpoint
**Functional Description**: Implement user registration with email validation
**Maps to Specification**: AC-1 (User can register with email), AC-4 (Password must be encoded)
## Definition of Ready (DoR)
- [ ] No prerequisite tasks are pending.
- [ ] Existing registration patterns and security conventions are understood.
- [ ] Required files and Spring test tooling are available locally.
- [ ] Validation and duplicate-email behavior are clear from the specification.
## 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. *(AC-1)*
- [ ] Verify that `EmailAlreadyExistsException` is thrown when the email is already registered. *(AC-1)*
- [ ] Verify that the password is encoded before saving. *(AC-4)*
- `AuthController`:
- [ ] Test email validation with valid, invalid, and missing formats. *(AC-1)*
- [ ] Verify that the controller returns status 201 for successful registration. *(AC-1)*
**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. *(AC-1)*
- [ ] Verify that a request with duplicate email returns status 409 and does not modify the database. *(AC-1)*
**3. Edge Cases and Error Conditions to Test:**
- [ ] Send malformed email (e.g., without @). *(AC-1 — validation rule)*
- [ ] Send too short password (e.g., less than 8 characters). *(AC-4 — business rule)*
- [ ] Send malformed JSON payload. *(AC-1 — input validation)*
**Test Acceptance Criteria**:
- [ ] All tests described above are implemented and pass.
- [ ] Test coverage for UserService is >= 80%.
## Definition of Done (DoD)
- [ ] Registration flow is implemented end-to-end.
- [ ] All acceptance criteria are satisfied with passing tests.
- [ ] Controller, service, and security configuration changes follow existing conventions.
- [ ] The task file is updated so downstream tasks can rely on the registration endpoint.
**Implementation Command**:
/skill:specs-kit-task-implementation --task="docs/specs/001-user-auth/tasks/TASK-001.md"
Note: Each test scenario is annotated with (AC-N) to show which acceptance criterion it verifies. This prevents Self-Referential Test Drift by making it explicit when a test scenario is NOT traceable to the spec.
Example 2: E-commerce Checkout (TypeScript)
/skill:specs-kit-spec-to-tasks docs/specs/005-checkout-flow/
Example 3: API Integration (Python)
/skill:specs-kit-spec-to-tasks docs/specs/010-payment-integration/
Example 4: Full Workflow (after task generation)
# Step 1: Generate tasks from specification
/skill:specs-kit-spec-to-tasks docs/specs/003-notification-system/
# Step 2: Implement tasks in dependency order
/skill:specs-kit-task-implementation --task="docs/specs/003-notification-system/tasks/TASK-001.md"
/skill:specs-kit-task-implementation --task="docs/specs/003-notification-system/tasks/TASK-002.md"
Integration with /skill:specs-kit-task-implementation
The task list generated by this command feeds directly into /skill:specs-kit-task-implementation:
# After generating tasks, implement each one:
# Option 1: Implement all tasks (sequentially)
/skill:specs-kit-task-implementation --task="docs/specs/001-user-auth/tasks/TASK-001.md"
# (complete, then)
/skill:specs-kit-task-implementation --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
/skill:specs-kit-task-implementation --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 1.5: Architecture & Ontology Definition
[ ] Phase 2: Requirement Extraction
[ ] Phase 3: Codebase Analysis
[ ] Phase 4: Technical Task Decomposition (including documentation and cleanup tasks)
- [ ] Step 4.0: Spec Fidelity Gate (verify [IMP]/[SEF]/[EXT] taxonomy)
- [ ] Step 4.1: Filter [IMP] criteria only for task generation
- [ ] Step 4.2: Bounded Context Boundary Check
- [ ] Step 4.3: External Dependency Pre-Flight
- [ ] Step 4.4: File Collision Detection
- [ ] Step 4.5: Test Instructions Fidelity Check
- [ ] Step 4.6: Dependency validation with cross-boundary + ext-dep columns
[ ] Phase 5: Task List Generation
[ ] Phase 5.5: Traceability Matrix Generation (with [I]/[S]/[E] type classification)
[ ] Phase 5.6: Spec Size Check (reject if >15 tasks and recommend brainstorm)
[ ] Phase 6: Review and Confirmation
[ ] Phase 7: Summary
Update the status as you progress through each phase.
CRITICAL: Phase 4 MUST generate:
- Implementation tasks (based ONLY on
[IMP]requirements) - Documentation checkpoints for
[SEF]and[EXT]criteria (included in the documentation task) - One documentation task (depends on all implementation tasks, verifies all
[IMP]/[SEF]/[EXT]criteria) - One cleanup task (depends on documentation task, uses specs-kit-code-cleanup skill)
Phase 4 Quality Gates (MUST pass before generating files):
- Spec Fidelity Gate: Spec has
[IMP]/[SEF]/[EXT]taxonomy - BC Boundary Check: All cross-boundary tasks are flagged with justification
- Ext Dependency Pre-Flight: All external dependencies are flagged with risk level
- File Collision Detection: No two tasks create/modify the same file without merging
- Test Fidelity Check: No test scenario invented that isn't in the spec
Phase 5.6 (Spec Size Check): If >15 implementation tasks detected:
- STOP task generation immediately
- Present warning message explaining the spec is too large
- Recommend returning to /skill:specs-kit-brainstorm to split the idea into 2+ specifications
- Offer user option to continue anyway (at their own risk)
- If user chooses brainstorm: abort and suggest
/skill:specs-kit-brainstormcommand - If user chooses continue: log warning in summary and proceed
Task Frontmatter Standardization
All task files follow a standardized frontmatter schema defined in hooks/task_schema.py. This ensures consistent metadata across all tasks.
Standard Status Workflow
Tasks use a standardized status workflow with automatic date tracking:
pending → implemented → reviewed
└───────────→ completed (cleanup hook terminal stamp)
| Status | Description | Dates Set |
|---|---|---|
pending |
Initial state, ready to start | None |
implemented |
Coding complete, awaiting review | implemented_date |
reviewed |
Review passed (canonical terminal) | reviewed_date |
completed |
Cleanup done, fully complete | completed_date, cleanup_date |
Auto-Status Management
Task status is automatically managed by Claude Code hooks:
| User Action | Automatic Status Update |
|---|---|
| Implementation phase finishes | pending → implemented |
| Review passes | implemented → reviewed |
| Cleanup hook stamps the terminal | reviewed → completed |
How it works:
- The loop updates
statusand the date fields onTASK-*.mdfiles at each phase boundary - No manual status management needed
Manual override (if needed): Simply edit the YAML frontmatter directly:
---
status: pending # or any other valid status
---
Valid statuses: pending, implemented, reviewed, completed
These are the only values the task parser accepts (src/tasks/task-parser.ts): any other value
(e.g. in_progress, blocked, superseded, optional, done) makes the task file fail to load
and blocks run/refresh for the entire spec. To put a task aside, comment it out in the fix
plan or remove the file; do not invent a status.
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.