Skip to main content
This walkthrough follows one small feature through the whole tiny-brain loop, so you can recognise each stage when you see it in your terminal and on the dashboard. You type the first line; your agent does the rest.

​
1. Plan

/plan "add email validation to signup"
The agent works with you to pin down purpose, features, and tasks, then creates the plan as markdown in your repo: 
docs/prd/signup-email-validation/
├── prd.md
└── features/
    └── email-validation.md
Each feature file lists its tasks. The markdown is the source of truth — progress state is projected from it automatically, and the dashboard renders it live.

​
2. Task start

Before touching any code for a task, the agent registers that work has begun: 
tiny-brain task start --task 'Add email validation' \
  --prd signup-email-validation --feature email-validation
The task flips to in_progress and its RED phase starts. You’ll see it move on the dashboard.

​
3. RED — failing tests first

The agent writes tests that pin the behaviour, watches them fail, and commits: 
test(signup): pin email validation rules

PRD: signup-email-validation
Feature: email-validation
Task: Add email validation
The gate hooks check the headers and run typecheck and lint — but skip the test suite on a test: commit, since the new tests are supposed to fail. Once accepted, the post-commit hook records the commit against the task.

​
4. GREEN — minimum code to pass

The implementation lands as a feat: commit with the same headers. This time the hook runs the full battery — typecheck, lint, and tests — before the commit is accepted.

​
5. Adversarial review

The moment a feat: commit lands, an isolated review agent challenges the work: does the implementation cheat the tests, overstate what it does, hide complexity? It returns one of two verdicts:
  • clean — the cycle closes.
  • needs-refactoring — concrete findings come back, and the agent addresses them in a refactor: commit (same headers) before the cycle can close.

​
6. Repeat

The agent moves to the next task and the loop continues — every task leaves behind a test commit, an implementation commit, a review verdict, and (sometimes) a refactor commit, all traceable from the markdown plan. A commit that skips the pipeline — wrong type, missing headers, a refactor: with no active review — is rejected by the hooks. That’s the guarantee: if it’s in the history, it went through the loop.