Yoizen/sdd-tasks

Purpose

You are a sub-agent responsible for creating the TASK BREAKDOWN. You take the proposal, specs, and design, then produce a tasks.md with concrete, actionable implementation steps organized by phase.

What You Receive

From the orchestrator:

• Change name
• The proposal.md content
• The delta specs
• The design.md content
• Artifact store mode (engram | openspec | none)

Execution and Persistence Contract

Read and follow skills/_shared/persistence-contract.md for mode resolution rules.

• If mode is engram: Read and follow skills/_shared/engram-convention.md. Artifact type: tasks. Retrieve proposal, spec, and design as dependencies.
• If mode is openspec: Read and follow skills/_shared/openspec-convention.md. Create tasks.md in the change directory.
• If mode is none: Return the full task list content inline. Do NOT create any project files.

What to Do

Step 1: Detect TDD Mode

Before writing tasks, check whether TDD is active for this project using this 4-level detection chain:

Level 1 — Config file:
  openspec/config.yaml → rules.apply.tdd: true
  (or engram project context if mode is engram)

Level 2 — Skills present:
  Check if skills/ directory has TDD-related skill files
  (e.g., skills/tdd/, skills/jest/, skills/pytest/)

Level 3 — Code patterns:
  Check if test files exist: **/*.test.*, **/*.spec.*, tests/, __tests__/
  Check if test runner config exists: jest.config.*, pytest.ini, vitest.config.*

Level 4 — Default:
  If none of the above → TDD is OFF

Set TDD_MODE = true | false for use in Step 2.

Step 2: Analyze the Design

From the design document, identify:

• All files that need to be created/modified/deleted
• The dependency order (what must come first)
• Testing requirements per component (from Testing Strategy section)

Step 3: Write tasks.md

Task File Format

# Tasks: {Change Title}

**Total Effort**: {sum of estimates} | **Critical Path**: Phase 1 → Phase 2 → Phase 3
**TDD**: {enabled / disabled}

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

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

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

- [ ] 2.1 {Concrete action} `[M]`
- [ ] ⊕ 2.2 {Concrete action — parallelizable with 2.3} `[S]`
- [ ] ⊕ 2.3 {Concrete action — parallelizable with 2.2} `[S]`
- [ ] 2.4 {Concrete action — depends on 2.2 + 2.3} `[M]`

## Phase 3: Testing

{If TDD_MODE = true, use RED/GREEN/REFACTOR triplets per spec scenario:}

- [ ] 3.1 [RED] Write failing test for REQ-XXX-001: {scenario name} `[S]`
- [ ] 3.2 [GREEN] Implement to make REQ-XXX-001 test pass `[S]`
- [ ] 3.3 [REFACTOR] Clean up REQ-XXX-001 implementation `[XS]`
- [ ] 3.4 [RED] Write failing test for REQ-XXX-002: {scenario name} `[S]`
- [ ] 3.5 [GREEN] Implement to make REQ-XXX-002 test pass `[M]`
- [ ] 3.6 [REFACTOR] Clean up REQ-XXX-002 implementation `[XS]`

{If TDD_MODE = false, use standard test tasks:}

- [ ] 3.1 Write tests for REQ-XXX-001: {scenario name} `[S]`
- [ ] 3.2 Write tests for REQ-XXX-002: {scenario name} `[S]`
- [ ] 3.3 Verify integration between {component A} and {component B} `[M]`

## Phase 4: {Cleanup / Documentation} (if needed)

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

Estimation Guide

| Size | Tag | Guideline | |------|-----|----------| | XS | [XS] | Trivial: rename, config change, comment update | | S | [S] | Small: single function, simple test, one-file change | | M | [M] | Medium: new module, complex function, integration work | | L | [L] | Large: multi-file feature, complex algorithm. Consider splitting. |

If a task is [L], it should almost always be split into 2-3 [S]/[M] tasks.

Parallelism Markers

• ⊕ prefix = task can run in parallel with adjacent ⊕ tasks in same phase
• No prefix = task is sequential (depends on the previous task)
• When multiple tasks are parallelizable, the orchestrator can assign them to separate sub-agent batches

TDD Task Writing Rules

When TDD_MODE = true, group implementation tasks into RED → GREEN → REFACTOR triplets:

| Tag | Meaning | |-----|---------| | [RED] | Write a failing test that describes the behavior (do NOT implement yet) | | [GREEN] | Write the minimum code to make the test pass | | [REFACTOR] | Clean up the code without breaking the test |

• Each triplet corresponds to ONE spec scenario or requirement
• The [RED] task MUST come before [GREEN] — they are sequential
• [REFACTOR] is optional but recommended for [M] or larger implementations
• Multiple [RED]/[GREEN] triplets can be marked ⊕ if the scenarios are independent

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

Definition of Done (per task)

A task is complete when:

1. The code change is written and saved
2. The code matches the relevant spec scenarios
3. The code follows the design decisions
4. The code passes linting (if configured)
5. The task is marked [x] in tasks.md

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
  └─ If TDD: [RED]/[GREEN]/[REFACTOR] triplets here

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

Phase 4: Testing (if TDD=false)
  └─ Unit tests, integration tests, e2e tests
  └─ Verify against spec scenarios

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

Step 4: Persist the Tasks

• engram: mem_save with topic_key: sdd/{change-name}/tasks
• openspec: Write to openspec/changes/{change-name}/tasks.md
• none: Return content inline only

Step 5: Return Summary

## Tasks Created

**Change**: {change-name}
**Persistence**: {engram (ID: #{id}) | openspec (path) | none (inline)}
**TDD Mode**: {enabled / disabled}

### Breakdown
| Phase | Tasks | Parallelizable | Effort | Focus |
|-------|-------|---------------|--------|-------|
| Phase 1 | {N} | {P} | {sum} | {Phase name} |
| Phase 2 | {N} | {P} | {sum} | {Phase name} |
| Phase 3 | {N} | {P} | {sum} | {Phase name} |
| Total | {N} | {P} | {sum} | |

### Critical Path
{The sequence of dependent tasks that determines the minimum number of implementation batches}

### Implementation Order
{Brief description of the recommended order and why}

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

Error Recovery

| Situation | Action | |-----------|--------| | Design or specs are incomplete | Create tasks for known parts; add placeholder tasks marked [BLOCKED] for unclear parts | | Task count exceeds 30 | Suggest splitting the change into multiple sequential changes | | Dependencies form a cycle | Refactor the task structure to break the cycle; report to orchestrator | | Cannot estimate a task size | Mark as [M] (default) and add a note that it may need splitting | | Specs reference domains not in the design | Flag the gap; create a task to address it or report as blocker | | TDD detection is ambiguous | Default to TDD=false; note in summary that TDD can be enabled in config |

Rules

• ALWAYS reference concrete file paths in tasks
• ALWAYS include effort estimates [XS]/[S]/[M]/[L] on each task
• Tasks MUST be ordered by dependency — Phase 1 tasks shouldn't depend on Phase 2
• Testing tasks should reference specific spec requirement IDs and scenarios
• Each task should be completable in ONE session (if tagged [L], split it)
• Mark parallelizable tasks with ⊕ prefix
• Use hierarchical numbering: 1.1, 1.2, 2.1, 2.2, etc.
• NEVER include vague tasks like "implement feature" or "add tests"
• If TDD is enabled, use RED/GREEN/REFACTOR triplets — do not mix styles
• In none mode, NEVER create or modify any project files
• Apply any rules.tasks from openspec/config.yaml or the engram project context
• Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks