Three layers
Plan markdown (committed, canonical)
PRDs, features, and fixes live under
docs/ (and fix documents under
.tiny-brain/fixes/) as reviewable markdown. Task descriptions,
statuses, and commit SHAs are recorded here. Each item carries a stable
UUID in its frontmatter — that UUID, not the wording, is the task’s real
identity.Repo context (committed, generated)
.tiny-brain/ holds what tiny-brain has learned and configured for the
repo: analysis.json (detected stack, package manager, scripts, test
patterns), config.json (preferences — enabled gates, directories,
default persona), and technology context under tech/. Committed so the
whole team — and every agent session — works from the same picture.Per-clone state (not committed, rebuildable)
On current tiny-brain versions, live progress projections, review
records, and session telemetry sit under
.git/tiny-brain/ in each
clone — deliberately outside the committed tree, because they’re derived
from commit history: a fresh clone reconstructs them with
tiny-brain progress rebuild instead of merging them. Repos initialised
on earlier versions may still carry committed projections
(.tiny-brain/progress/, .tiny-brain/reviews/) alongside; teams
choose whether to keep tracking those in git.Why commits are the joins
A tracked commit’s headers (PRD: / Feature: / Task:, or Fix:) are
resolved to task UUIDs by the commit-msg hook at commit time. That makes the
git history the join table between plans and code: any clone, dashboard, or
future tool can re-derive who did what for which task from history alone.
It’s also why the headers are enforced rather than suggested — an
unattributed commit is a hole in the record.
Hooks own the state
The tracking layers are written by hooks and agents, not by hand. Hand-editing a projection creates a state that history doesn’t support, and the next hook run will disagree with it. If tracking looks wrong, the fix is the hook (or a re-sync from the markdown) — not the JSON. What is yours to edit is the canonical layer: the plan markdown. Update a task’s status there and re-sync (tiny-brain task sync <file>), and the
projections follow.