Skip to main content
tiny-brain doesn’t ask the agent (or you) to report progress. A task’s phase is derived from its commit history — git is the database, and the hooks are the only writers.

​
How a phase is derived

Each task in a plan has a stable identity (a UUID stamped into the plan markdown). As commits land with that task’s Task: header, the hooks record which commit played which role:
  • a test: commit → the task’s RED commit
  • a feat: / fix: commit → the task’s GREEN commit
  • a refactor: commit during an active review → the review-refactor commit
The current phase falls out of what’s recorded: no commits yet → red (a failing test is the next step); test commit only → still red until the implementation lands; green commit present → the review pipeline takes over. Ask the CLI directly: 
tiny-brain task phase --task 'Add the behaviour' --prd my-plan --feature my-feature

​
Starting a task

Work on a task begins by declaring it — before reading code, designing, or writing tests: 
tiny-brain task start --task 'Add the behaviour' --prd my-plan --feature my-feature
This flips the task to in_progress and starts its RED clock. Without it, the hooks can’t attribute commits to the task and the dashboard timeline can’t follow the work. For tasks with nothing to test (docs, config, templates), --phase green records that RED was deliberately skipped.

​
Who writes what

ActorWrites
You / your agentplan markdown, code, commits, task start
commit-msg hookvalidates headers and commit type against pipeline state
post-commit hookattributes the commit to its task, advances the phase, starts reviews
review agentsverdicts and findings
Everything else is projection. On current versions, progress state lives per-clone under .git/tiny-brain/ and can be rebuilt from the commit history in any clone — see the tracking model. The practical rule that keeps the model sound: never hand-edit tracking state. If the state looks wrong, the fix is finding the hook that should have written it.