> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiny-brain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phases

> Task status is derived from git, not declared by anyone

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:

```bash theme={null}
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:

```bash theme={null}
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

| Actor                | Writes                                                                |
| -------------------- | --------------------------------------------------------------------- |
| **You / your agent** | plan markdown, code, commits, `task start`                            |
| **commit-msg hook**  | validates headers and commit type against pipeline state              |
| **post-commit hook** | attributes the commit to its task, advances the phase, starts reviews |
| **review agents**    | verdicts 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](/concepts/tracking). 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.