Task List

Structure work as executable task files that define what to do, how to verify completion, and track progress across sessions.

Quick Reference

• Task Format — Structure of a task file
• Working a Task — Process for executing tasks
• Execution Notes — Recording progress across sessions

Task Format

A task file captures intent, ordered steps, and verification checks in a single document. The structure below keeps every task self-contained so an agent or human can pick it up cold and know exactly what to do.

# Task: <name>

## Intent

One paragraph explaining the purpose of this task.

## Steps

1. First imperative action
2. Second imperative action
3. Continue with clear, ordered steps

## Checks

### Preconditions

Commands to confirm environment readiness before starting.

### Tests

Automated commands where exit 0 = pass:
- `npm test`
- `./scripts/verify.sh`

### Manual

Human or agent inspection items:
- [ ] Feature works as expected
- [ ] No regressions introduced

### Human Approval

Named sign-offs required:
- [ ] @username approved

## Execution Notes

(Added during work — see below)

Section Purpose

Section	Purpose
Intent	Why this task exists
Steps	What to do, in order
Preconditions	Environment requirements
Tests	Automated verification
Manual	Human judgment checks
Human Approval	Required sign-offs
Execution Notes	Progress tracking

Working a Task

Starting Work

1. Read the full task file
2. Run precondition checks
3. Work through steps in order
4. Add execution notes as you go

During Execution

• Check off completed items
• Record commands run and their output
• Note any blockers or surprises
• Update the task file with progress

Definition of Done

A task is complete when:

1. All Preconditions pass
2. All Tests pass (exit 0)
3. All Manual checks satisfied
4. All Human Approval recorded
5. File renamed from .task.md to .done.md

Execution Notes

Each session appends a dated section with progress, blockers, and next steps so the next session can resume without re-reading the entire task.

## Execution Notes

### Session: YYYY-MM-DD HH:MM

- **Progress**: What was accomplished
- **Partial work**: What's in progress but incomplete
- **Next steps**: Where to continue next session
- **Blockers**: Any issues encountered
- **Commands run**: Key commands executed
- **Files modified**: Important files changed
- **Test results**: What passed/failed

Multiple sessions each add their own dated section.

File Naming

Tasks follow a naming convention to indicate status:

Pattern	Status
XYZ-task-name.task.md	Active (pending or in progress)
XYZ-task-name.done.md	Completed

The prefix (XYZ) can be an issue number, date, or sequence identifier.

Multiple Tasks

When a project has many tasks, a dedicated tasks/ directory with numbered files makes status visible at a glance — completed files end in .done.md and pending ones end in .task.md.

tasks/
  README.md           # Overview and conventions
  001-setup.done.md   # Completed
  002-feature.task.md # In progress
  003-cleanup.task.md # Pending

Notes

Keep steps imperative and actionable. Each step should be something you can do, not something to think about.

Write checks that can actually be verified. Prefer automated tests over manual checks when possible.

Execution notes are for future you (or another agent). Include enough context to pick up work without re-reading everything.