> ## 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.

# The TDD loop

> RED → GREEN → REFACTOR, enforced by git hooks instead of good intentions

Every tracked task in a tiny-brain repo moves through the same three-stage
loop. The stages aren't a convention the agent is asked to follow — they're
derived from the commit history and enforced by git hooks, so the loop can't
be skipped quietly.

## RED — failing tests first

The task begins with tests that pin the behaviour and fail:

```
test(scope): pin the behaviour

PRD: my-plan
Feature: my-feature
Task: Add the behaviour
```

On a `test:` commit the hook runs typecheck and lint but **skips the test
suite** — the new tests are supposed to fail. That's the point of RED.

Work with no test surface (docs, config, templates) skips RED explicitly:
the task is started with `--phase green`, which records that the skip was a
decision, not an accident.

## GREEN — minimum code to pass

The implementation lands as a `feat:` (or `fix:`) commit with the same
tracking headers. Now the hook runs the full battery — typecheck, lint,
**and tests** — before accepting the commit. In repos with adversarial review
enabled (`enableAdversarial`), an
[adversarial review](/concepts/adversarial-review) of the work starts the
moment it lands.

## REFACTOR — review-driven, not vibes-driven

If the review verdict is **needs-refactoring**, the findings come back as
concrete suggestions and the fixes land as a `refactor:` commit. The hooks
only accept a `refactor:` commit while a review is active — refactoring is
a response to findings, not an unprompted rewrite.

## Commit types

| Type                    | Stage    | Hook behaviour                               |
| ----------------------- | -------- | -------------------------------------------- |
| `test:`                 | RED      | typecheck + lint, tests skipped              |
| `feat:` / `fix:`        | GREEN    | full battery, then adversarial review starts |
| `refactor:`             | REFACTOR | requires an active review                    |
| `spike:`                | —        | timeboxed exploration, tracked with headers  |
| `chore:` / `untracked:` | —        | untracked work, no headers needed            |

Tracked commits carry `PRD:` / `Feature:` / `Task:` headers (or `Fix:` /
`Task:` for bug work). The `Task:` value is the task's exact description —
that's how a commit attaches to the plan. A tracked commit without its
headers is **rejected**.

The result: reading the history of any task tells the whole story — what was
pinned, what was built, what the reviewer objected to, and what changed in
response. How the stages are derived from commits is covered in
[Phases](/concepts/phases).