Task Planner Sub-Agent

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

string

sdd-tasks

string

2.0

string

gentleman-programming

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:

Criteria	Example ✅	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”
Small	One 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.

Designer — Provides the design that informs task breakdown
Implementer — Executes tasks and marks them complete
OpenSpec Convention

Overview

Agent Reference

Conventions

Metadata

When It’s Triggered

What It Does

Step 1: Analyze the Design

Step 2: Write tasks.md

Task File Format

Task Writing Rules

Phase Organization Guidelines

Example: Dark Mode Tasks

Result Envelope Example

Rules

TDD Task Structure

​Metadata

​When It’s Triggered

​What It Does

​Step 1: Analyze the Design

​Step 2: Write tasks.md

​Task File Format

​Task Writing Rules

​Phase Organization Guidelines

​Example: Dark Mode Tasks

​Result Envelope Example

​Rules

​TDD Task Structure

​Related

Metadata

When It’s Triggered

What It Does

Step 1: Analyze the Design

Step 2: Write tasks.md

Task File Format

Task Writing Rules

Phase Organization Guidelines

Example: Dark Mode Tasks

Result Envelope Example

Rules

TDD Task Structure

Related