Skip to main content
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 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

TypeStageHook behaviour
test:REDtypecheck + lint, tests skipped
feat: / fix:GREENfull battery, then adversarial review starts
refactor:REFACTORrequires 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.