> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/agent-teams-lite/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Planner Sub-Agent

> Break down a change into an implementation task checklist

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

<ResponseField name="name" type="string">
  `sdd-tasks`
</ResponseField>

<ResponseField name="version" type="string">
  `2.0`
</ResponseField>

<ResponseField name="author" type="string">
  `gentleman-programming`
</ResponseField>

<ResponseField name="license" type="string">
  `MIT`
</ResponseField>

## 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

```markdown theme={null}
# 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

```markdown theme={null}
# 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

```markdown theme={null}
## 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:

```markdown theme={null}
## 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.

## Related

* [Designer](/sub-agents/designer) — Provides the design that informs task breakdown
* [Implementer](/sub-agents/implementer) — Executes tasks and marks them complete
* [OpenSpec Convention](/sub-agents/openspec-convention)