Skip to main content
The sdd-tasks sub-agent creates a concrete, actionable task breakdown organized by implementation phase. It takes the proposal, specs, and design, then produces a tasks.md file with hierarchical, verifiable tasks.

​
Metadata

​
name
string
sdd-tasks
​
version
string
2.0
​
author
string
gentleman-programming
​
license
string
MIT

​
When It’s Triggered

The orchestrator launches sdd-tasks when:
  • User runs /sdd-new <change-name> (after design)
  • User wants to create or update the task breakdown
  • Design is complete and ready for implementation planning

​
What It Does

​
Step 1: Analyze the Design

From the design document, identifies:
  • All files that need to be created/modified/deleted
  • The dependency order (what must come first)
  • Testing requirements per component

​
Step 2: Write tasks.md

Creates the task file: 
openspec/changes/{change-name}/
├── proposal.md
├── specs/
├── design.md
└── tasks.md               ← Created here

​
Task File Format

# Tasks: {Change Title}

## Phase 1: {Phase Name} (e.g., Infrastructure / Foundation)

- [ ] 1.1 {Concrete action — what file, what change}
- [ ] 1.2 {Concrete action}
- [ ] 1.3 {Concrete action}

## Phase 2: {Phase Name} (e.g., Core Implementation)

- [ ] 2.1 {Concrete action}
- [ ] 2.2 {Concrete action}
- [ ] 2.3 {Concrete action}
- [ ] 2.4 {Concrete action}

## Phase 3: {Phase Name} (e.g., Testing / Verification)

- [ ] 3.1 {Write tests for ...}
- [ ] 3.2 {Write tests for ...}
- [ ] 3.3 {Verify integration between ...}

## Phase 4: {Phase Name} (e.g., Cleanup / Documentation)

- [ ] 4.1 {Update docs/comments}
- [ ] 4.2 {Remove temporary code}

​
Task Writing Rules

Each task MUST be:
CriteriaExample ✅Anti-example ❌
Specific”Create internal/auth/middleware.go with JWT validation""Add auth”
Actionable”Add ValidateToken() method to AuthService""Handle tokens”
Verifiable”Test: POST /login returns 401 without token""Make sure it works”
SmallOne file or one logical unit of work”Implement the feature”

​
Phase Organization Guidelines

Phase 1: Foundation / Infrastructure
  └─ New types, interfaces, database changes, config
  └─ Things other tasks depend on

Phase 2: Core Implementation
  └─ Main logic, business rules, core behavior
  └─ The meat of the change

Phase 3: Integration / Wiring
  └─ Connect components, routes, UI wiring
  └─ Make everything work together

Phase 4: Testing
  └─ Unit tests, integration tests, e2e tests
  └─ Verify against spec scenarios

Phase 5: Cleanup (if needed)
  └─ Documentation, remove dead code, polish

​
Example: Dark Mode Tasks

# Tasks: Add Dark Mode

## Phase 1: Foundation

- [ ] 1.1 Convert all color values in `src/styles/theme.css` to CSS variables
- [ ] 1.2 Define dark theme color palette in `src/styles/theme.css` under `:root[data-theme="dark"]`
- [ ] 1.3 Create `src/contexts/ThemeContext.tsx` with theme state and toggle logic
- [ ] 1.4 Create `src/hooks/useTheme.ts` hook to consume ThemeContext

## Phase 2: Core Implementation

- [ ] 2.1 Update `src/components/App.tsx` to wrap app with `<ThemeProvider>`
- [ ] 2.2 Create theme toggle button component in `src/components/Header.tsx`
- [ ] 2.3 Implement localStorage read on mount in `ThemeContext`
- [ ] 2.4 Implement localStorage write on theme change in `ThemeContext`
- [ ] 2.5 Add `data-theme` attribute setter to `<html>` element in `ThemeContext`

## Phase 3: SSR Flash Fix

- [ ] 3.1 Add inline script to `src/main.tsx` to read localStorage and apply theme before React hydration
- [ ] 3.2 Test: Verify no theme flash on page load with dark mode selected

## Phase 4: Testing

- [ ] 4.1 Test: ThemeContext toggles between light and dark (unit)
- [ ] 4.2 Test: Theme persists to localStorage when changed (unit)
- [ ] 4.3 Test: Theme loads from localStorage on mount (unit)
- [ ] 4.4 Test: useTheme hook throws error when used outside ThemeProvider (unit)
- [ ] 4.5 Test: Theme toggle button changes UI colors (integration)
- [ ] 4.6 Test: Theme persists across page reload (E2E with Cypress)

## Phase 5: Cleanup

- [ ] 5.1 Add JSDoc comments to ThemeContext and useTheme
- [ ] 5.2 Update README with dark mode feature description

​
Result Envelope Example

## Tasks Created

**Change**: add-dark-mode
**Location**: openspec/changes/add-dark-mode/tasks.md

### Breakdown
| Phase | Tasks | Focus |
|-------|-------|-------|
| Phase 1 | 4 | Foundation (CSS vars, Context, Hook) |
| Phase 2 | 5 | Core Implementation (UI wiring, storage) |
| Phase 3 | 2 | SSR Flash Fix |
| Phase 4 | 6 | Testing (unit, integration, E2E) |
| Phase 5 | 2 | Cleanup (docs) |
| Total | 19 | |

### Implementation Order
Phase 1 establishes infrastructure (CSS variables and Context), Phase 2 wires up the UI and persistence, Phase 3 fixes SSR flash, Phase 4 validates against spec scenarios, and Phase 5 polishes documentation.

### Next Step
Ready for implementation (sdd-apply).

​
Rules

  • ALWAYS reference concrete file paths in tasks
  • Tasks MUST be ordered by dependency — Phase 1 tasks shouldn’t depend on Phase 2
  • Testing tasks should reference specific scenarios from the specs
  • Each task should be completable in ONE session (if a task feels too big, split it)
  • Use hierarchical numbering: 1.1, 1.2, 2.1, 2.2, etc.
  • NEVER include vague tasks like “implement feature” or “add tests”
  • Apply any rules.tasks from openspec/config.yaml
  • If the project uses TDD, integrate test-first tasks: RED task (write failing test) → GREEN task (make it pass) → REFACTOR task (clean up)
  • Return a structured envelope with: status, executive_summary, detailed_report, artifacts, next_recommended, and risks

​
TDD Task Structure

If the project uses Test-Driven Development, tasks should follow the RED-GREEN-REFACTOR cycle: 
## Phase 2: Core Implementation

- [ ] 2.1 RED: Write failing test for ThemeContext toggle
- [ ] 2.2 GREEN: Implement toggleTheme to make test pass
- [ ] 2.3 REFACTOR: Extract theme logic to separate helper
- [ ] 2.4 RED: Write failing test for localStorage persistence
- [ ] 2.5 GREEN: Implement localStorage read/write
- [ ] 2.6 REFACTOR: Simplify localStorage abstraction
Each triplet of tasks (RED → GREEN → REFACTOR) implements one requirement.

Build docs developers (and LLMs) love

Get started for freeTalk to us