Skip to main content
Plans are markdown files in your repo. Three document kinds exist — PRDs (a product initiative), features (a deliverable inside a PRD), and fixes (a tracked bug) — and features and fixes contain tasks, the unit the TDD loop runs on.
(Directory locations are configurable; repos initialised on earlier versions may keep fixes under .tiny-brain/fixes/.)

​
The identity model

Every PRD, feature, and task carries two names:
  • a human name — the slug (id:, kebab-case) for PRDs and features, and the description for tasks. This is what commit headers use.
  • a UUIDv7 — the real, stable identity everything is tracked against. PRDs and features carry it as uuid: in their frontmatter; a task block carries it on its id: line (tasks have no slug).
You never type a UUID. Documents and tasks are created through the CLI:
work add generates the UUID, stamps the frontmatter, and assigns positional ordering. Renaming a task’s description later is safe — the UUID underneath doesn’t change — but commit Task: headers must match the description exactly at commit time.

​
Who owns which part

After editing lifecycle fields, re-sync the projections from the markdown:

​
Statuses

PRDs, features, and fixes move through not_started → in_progress → completed; fixes add a fourth, superseded. Individual tasks use the same values — a task that became unnecessary is marked superseded with commitSha: null rather than deleted, so the plan keeps its history. The per-kind pages cover each file’s exact shape: PRDs · Features & tasks · Fixes