tasks.md

Why tasks are sized for an agent's attention span

A coding agent is excellent at one bounded change with a clear "done" and poor at "implement the billing module". tasks.md converts the solution into bounded changes: each task cites the modules and data models the solution named, lists the requirement IDs it satisfies, and carries its own testable acceptance criteria - so an agent can pick up task 7 cold, do it, verify it, and stop.

Three workflows, three shapes

In MySpec the greenfield tasks stage has a collect substage that asks about your team structure, which feeds the delivery plan (section 04). The brownfield tasks stage is optional: after the requirements delta is approved the workflow asks whether you want a plan or would rather hand the delta straight to your coding agent.

The MySpec task format

# Implementation Tasks: [Project Name]

## Overview
Approach, total task count, total man-days, elapsed duration.

## Milestone 1: <the outcome this milestone ships>

- [ ] 1\. Create Postgres migration for usage_ledger
  - Add uq_tenant_idempotency (tenant_id, idempotency_key) unique constraint
  - Acceptance Criteria:
    - Migration applies and rolls back cleanly on an empty database
    - Duplicate (tenant_id, idempotency_key) insert is rejected
  - _Dependencies: none_
  - _Requirements: FR-001, NFR-002_
  - _Complexity: Small_
  - _Estimate: 0.5 man-days_

- [ ] 2\. Implement idempotency middleware
  - ...
  - _Dependencies: 1_
  - _Requirements: FR-001_
  - _Complexity: Medium_
  - _Estimate: 1.5 man-days_

## Milestone 2: ...

## Milestone N: QA Verification
- [ ] 14\. Verify FR-001 - Idempotent usage ingestion (actor: Tenant admin)
  - Scenario per acceptance criterion, negative IF…THEN paths included
  - _Requirements: FR-001_

## Delivery Timeline            (Mermaid gantt: milestones × team)

## Dependency Graph
Critical path and parallelization opportunities, in prose, consistent with the chart.

• Task line - - [ ] N\. Title; the escaped period keeps the number literal instead of starting a Markdown ordered list.
• Sizing bands - Small ≤ 4 hours, Medium 1–2 days, Large > 2 days; anything that would exceed 5 days is split first, so every task lands in exactly one band.
• Milestone order - Infrastructure → Core Features → Supporting Features → Integration → Testing → Documentation → Deployment, but each milestone is named after the deliverable it ships, not the activity.
• Every requirement covered - each FR has at least one task; NFRs are addressed by the tasks that touch them.

Delivery plan and QA verification

Two additions turn a checklist into a plan a team can commit to:

• Project-Manager delivery plan. Every task gets an _Estimate: N man-days_ line consistent with its complexity band (Small 0.5, Medium 1–2, Large 2–5), the Overview states total man-days and elapsed duration, and a Mermaid Gantt timeline sits just before the Dependency Graph, laid out against the team you described in the collect substage.
• QA-Engineer verification milestone. A final milestone with one verification task per functional requirement: the actor comes from the requirement's User Role, the scenarios from its EARS+ acceptance criteria, and every IF … THEN unwanted-behaviour criterion must have its negative path covered. NFRs fold into the FR they constrain rather than getting a task of their own.

The Spec Kit task format

The Spec Kit workflow mirrors GitHub Spec Kit's tasks-template.md: sequential T001 numbering across the whole file, [P] for tasks that touch different files and can run in parallel, [US1] tags on user-story tasks, a concrete (file: path) on every task, and a checkpoint at the end of each phase.

# Tasks: [FEATURE NAME]

**Input**: Design documents from `specs/<FEAT_DIR>/`
**Prerequisites**: spec.md, plan.md

## Format: `[ID] [P?] [Story] Description`
- **[P]**: can run in parallel (different files, no dependencies)
- **[Story]**: which user story the task belongs to (US1, US2, …)

## Phase 1: Setup (Shared Infrastructure)
- [ ] T001 Create project structure per plan.md (file: repo root)
- [ ] T003 [P] Configure linting and formatting tools (file: .eslintrc.json)

## Phase 2: Foundational (Blocking Prerequisites)
- [ ] T004 Set up database schema + migrations (file: drizzle/schema.ts)
**Checkpoint**: Foundation ready - user-story phases can begin.

## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
**Goal**: …   **Independent Test**: …
- [ ] T007 [P] [US1] Create [Entity1] model (file: src/models/entity1.ts)
- [ ] T009 [US1] Implement [Service] (file: src/services/foo.ts)
**Checkpoint**: User Story 1 fully functional and testable independently.

## Phase N: Polish & Cross-Cutting Concerns
- [ ] T0XX Run the validation steps from plan.md's Testing Strategy

## Dependencies & Execution Order

The OpenSpec task format

The OpenSpec workflow keeps tasks at planning level and groups them by the capabilities the proposal named - one ## N. <capability> group with - [ ] N.M checkboxes each, all unchecked, so the OpenSpec CLI can track them.

## 1. webapp
- [ ] 1.1 Add the session-rename action to the session list menu
- [ ] 1.2 Wire the rename dialog to PATCH /sessions/:id

## 2. platform
- [ ] 2.1 Add rename endpoint with 500-char summary validation
- [ ] 2.2 Emit session.renamed realtime event

Authoring and review rules

How coding agents use it

1. One task per prompt. "Implement task 3 from .specs/billing/tasks.md strictly according to solution.md and constitution.md" beats any free-form request.
2. Tick the box, cite the IDs. The agent marks - [x] and the PR description lists the requirement IDs from the task's _Requirements:_ line.
3. Keep the file live. With the MCP server the agent can update_spec_file the checklist as a new revision (passing expected_version so a teammate's edit is never overwritten).
4. Run the QA milestone last. The verification tasks are the acceptance test of the whole bundle.