Skip to main content
A feature is one deliverable inside a PRD, and its file is where tasks live. Created with: 
tiny-brain work add feature --prd my-initiative my-feature "My Feature"
tiny-brain work add task --feature my-feature "Add the behaviour"
The frontmatter (CLI-owned) carries id, uuid, prd_id, number (positional, assigned automatically), title, status, and dates.

​
Task blocks

work add task appends each task to the ## Tasks section as a numbered heading with its own UUID: 
## Tasks

### 1. Add the behaviour
id: 019f56ae-32c7-7a1e-b715-54cc7e379d32
status: not_started
As the task moves through the TDD loop, the lifecycle fields are updated in place: 
### 1. Add the behaviour
id: 019f56ae-32c7-7a1e-b715-54cc7e379d32
status: completed
commitSha: ec07a74
  • One commit that closes several tasks uses the same commitSha on each.
  • A task that became unnecessary is marked status: superseded with commitSha: null — never deleted.
  • After editing, re-sync: tiny-brain task sync docs/prd/my-initiative/features/my-feature.md
The sync parser treats any ### N. Title heading as a task definition — only use numbered ### headings inside ## Tasks. Elsewhere in the document, use bold text or unnumbered headings.

​
Writing good tasks

A task describes what to build, not how — the full TDD cycle (failing test, implementation, review-driven refactor) happens inside one task. Two shapes to reject:
  • The TDD split — “Write failing tests for X” + “Implement X” is one task (“Add X”), not two. Each half is half a cycle.
  • The verification-only task — “Run the test suite”, “Verify in staging”. These produce no commit and always end up superseded. Verification is part of every cycle, not a task.
The task description is load-bearing: it’s the Task: value in commit headers, matched by equality (whitespace trimmed). Write it as you want to type it in a commit message.

​
Body sections

Beyond ## Description and ## Tasks, features commonly carry Acceptance Criteria (testable checkboxes), per-task file lists, Dependencies, a Testing Strategy, and Implementation Notes. As with PRDs, prose is yours; the frontmatter and task id: lines are not.