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. 
docs/prd/<prd-slug>/
├── prd.md
└── features/
    └── <feature-slug>.md      # contains task blocks
docs/fixes/
└── <fix-slug>.md              # contains task blocks
(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: 
tiny-brain work add prd <slug> "Title"
tiny-brain work add feature --prd <slug> <feature-slug> "Title"
tiny-brain work add task --feature <feature-slug> "Exact task description"
tiny-brain work add fix <slug> "Title"
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

PartOwner
Frontmatter (id, uuid, number, dates)the CLI — never hand-edit
Prose sections (description, criteria, notes)you, with your editor
Task lifecycle fields (status:, commitSha:)edited as work completes
Progress projectionsderived — see the tracking model
After editing lifecycle fields, re-sync the projections from the markdown: 
tiny-brain task sync docs/prd/<prd-slug>/features/<feature-slug>.md

​
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