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

# Overview

> How plans are written: slugs, UUIDs, and who owns which part of the file

Plans are markdown files in your repo. Three document kinds exist — **PRDs**
(a product initiative), **features** (a deliverable inside a PRD), and
**fixes** (a tracked bug) — and features and fixes contain **tasks**, the
unit the TDD loop runs on.

```
docs/prd/<prd-slug>/
├── prd.md
└── features/
    └── <feature-slug>.md      # contains task blocks
docs/fixes/
└── <fix-slug>.md              # contains task blocks
```

(Directory locations are configurable; repos initialised on earlier versions
may keep fixes under `.tiny-brain/fixes/`.)

## The identity model

Every PRD, feature, and task carries two names:

* a human name — the **slug** (`id:`, kebab-case) for PRDs and features, and
  the **description** for tasks. This is what commit headers use.
* a **UUIDv7** — the real, stable identity everything is tracked against.
  PRDs and features carry it as `uuid:` in their frontmatter; a task block
  carries it on its `id:` line (tasks have no slug).

You never type a UUID. Documents and tasks are created through the CLI:

```bash theme={null}
tiny-brain work add prd <slug> "Title"
tiny-brain work add feature --prd <slug> <feature-slug> "Title"
tiny-brain work add task --feature <feature-slug> "Exact task description"
tiny-brain work add fix <slug> "Title"
```

`work add` generates the UUID, stamps the frontmatter, and assigns
positional ordering. Renaming a task's description later is safe — the UUID
underneath doesn't change — but commit `Task:` headers must match the
description exactly at commit time.

## Who owns which part

| Part                                            | Owner                                                  |
| ----------------------------------------------- | ------------------------------------------------------ |
| Frontmatter (`id`, `uuid`, `number`, dates)     | the CLI — never hand-edit                              |
| Prose sections (description, criteria, notes)   | you, with your editor                                  |
| Task lifecycle fields (`status:`, `commitSha:`) | edited as work completes                               |
| Progress projections                            | derived — see [the tracking model](/concepts/tracking) |

After editing lifecycle fields, re-sync the projections from the markdown:

```bash theme={null}
tiny-brain task sync docs/prd/<prd-slug>/features/<feature-slug>.md
```

## Statuses

PRDs, features, and fixes move through `not_started` → `in_progress` →
`completed`; fixes add a fourth, `superseded`. Individual tasks use the same
values — a task that became unnecessary is marked `superseded` with
`commitSha: null` rather than deleted, so the plan keeps its history.

The per-kind pages cover each file's exact shape:
[PRDs](/markdown-format/prds) · [Features & tasks](/markdown-format/features)
· [Fixes](/markdown-format/fixes)