Command: `/tasks`
Relevant source files
The following files were used as context for generating this wiki page:
The /tasks command is the third step in the Spec-Driven Development (SDD) lifecycle, following the /specify and /plan commands. Its purpose is to break down a high-level technical implementation plan (plan.md) into a granular, ordered, and executable list of development tasks. This command analyzes the plan.md and other design documents to generate a tasks.md file within the feature's specification directory.
This generated task list is designed to be specific enough for an AI agent or a developer to execute each item with minimal additional context. The command automates the conversion of a technical plan into an actionable work breakdown, enforcing principles like Test-Driven Development (TDD) and identifying opportunities for parallel execution.
Sources: templates/commands/tasks.md:1-5, spec-driven.md:143-151, README.md:43-45
Execution Flow
The /tasks command follows a structured process to generate the task list. It begins by verifying prerequisites, analyzes various design documents, applies generation rules, and finally outputs the tasks.md file.
Sources: templates/commands/tasks.md:7-46, templates/tasks-template.md:6-28
The following diagram illustrates the high-level execution flow of the /tasks command.
Inputs and Prerequisites
The command relies on a set of design documents generated by the preceding /plan command. The presence and content of these files determine the completeness and accuracy of the generated task list.
Sources: templates/commands/tasks.md:9-19, scripts/check-task-prerequisites.sh:2-5
Prerequisite Check
Before task generation, the command executes scripts/check-task-prerequisites.sh to verify that the necessary input files are available. This script checks for the existence of plan.md and identifies other optional design documents.
The script can be run in JSON mode to provide a structured output of the available documents.
#!/usr/bin/env bash
# Check that implementation plan exists and find optional design documents
# Usage: ./check-task-prerequisites.sh [--json]
set -e
JSON_MODE=false
for arg in "$@"; do
case "$arg" in
--json) JSON_MODE=true ;;
--help|-h) echo "Usage: $0 [--json]"; exit 0 ;;
esac
done
# ... (script continues)
Sources: scripts/check-task-prerequisites.sh:1-51
Input Documents
The command analyzes the following documents to generate tasks:
| Document | Required / Optional | Purpose |
|---|---|---|
plan.md | Required | Provides the core tech stack, libraries, and project structure. |
data-model.md | Optional | Defines entities, which are used to create model-related tasks. |
contracts/ | Optional | Contains API endpoint definitions, used for creating contract tests and endpoint implementation tasks. |
research.md | Optional | Contains technical decisions that inform setup tasks. |
quickstart.md | Optional | Provides user scenarios that are translated into integration and validation tests. |
Sources: templates/commands/tasks.md:9-19, templates/tasks-template.md:2-3, templates/plan-template.md:104-109
Task Generation Logic
Tasks are generated by mapping artifacts from the design documents to specific task categories defined in /templates/tasks-template.md.
The diagram below shows how different input documents contribute to various task categories.
Generation Rules
The system uses a set of rules to derive tasks from the input artifacts:
| Input Artifact | Generated Task(s) | Parallel [P]? |
|---|---|---|
Each file in contracts/ | A contract test task. | Yes |
Each endpoint in contracts/ | An endpoint implementation task. | No (if they share files) |
Each entity in data-model.md | A model creation task. | Yes |
| Each user story | An integration test task. | Yes |
- Tasks that modify different files can be marked as parallel
[P]. - Tasks that modify the same file must be sequential (no
[P]).
Sources: templates/commands/tasks.md:28-35, templates/tasks-template.md:73-86
Task Ordering and Dependencies
A crucial function of the /tasks command is to order the generated tasks according to their dependencies, ensuring a logical build sequence. This enforces principles like Test-Driven Development (TDD).
The general order of execution is:
- Setup: Project initialization, dependencies, linting.
- Tests: Contract and integration tests are created first (and are expected to fail).
- Core Implementation: Models, services, and endpoints are created to make the tests pass.
- Integration: Database connections, middleware, and logging.
- Polish: Final unit tests, performance tuning, and documentation.
Sources: templates/commands/tasks.md:37-43, templates/tasks-template.md:41-68, 88-91
The following graph visualizes the dependency flow between task phases.
Sources: templates/tasks-template.md:41-68
Output: tasks.md
The final output of the /tasks command is a tasks.md file located in the feature directory (e.g., specs/[###-feature-name]/tasks.md). This file contains a numbered list of tasks ready for execution.
Task Format
Each task follows a standard format: [ID] [P?] Description.
- [ID]: A unique, sequential identifier (e.g.,
T001). - [P?]: An optional marker indicating the task can be run in parallel with other
[P]tasks. - Description: A clear, specific action, including the exact file paths to be modified.
Sources: templates/tasks-template.md:30-32, templates/commands/tasks.md:45-46
Example Structure
The tasks.md file is structured into phases, as shown in this snippet from the template:
## Phase 3.1: Setup
- [ ] T001 Create project structure per implementation plan
- [ ] T002 Initialize [language] project with [framework] dependencies
- [ ] T003 [P] Configure linting and formatting tools
## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py
## Phase 3.3: Core Implementation (ONLY after tests are failing)
- [ ] T008 [P] User model in src/models/user.py
- [ ] T011 POST /api/users endpoint
Sources: templates/tasks-template.md:41-60
The file also includes sections for dependencies and examples of how to execute parallel tasks. This ensures the output is immediately actionable.
Sources: templates/tasks-template.md:93-103