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

# Your first PRD

> What actually happens when your agent plans and ships a tracked task

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:

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