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

# Features & tasks

> The feature file and the task-block syntax the whole pipeline hangs off

A feature is one deliverable inside a PRD, and its file is where tasks live.
Created with:

```bash theme={null}
tiny-brain work add feature --prd my-initiative my-feature "My Feature"
tiny-brain work add task --feature my-feature "Add the behaviour"
```

The frontmatter (CLI-owned) carries `id`, `uuid`, `prd_id`, `number`
(positional, assigned automatically), `title`, `status`, and dates.

## Task blocks

`work add task` appends each task to the `## Tasks` section as a numbered
heading with its own UUID:

```markdown theme={null}
## Tasks

### 1. Add the behaviour
id: 019f56ae-32c7-7a1e-b715-54cc7e379d32
status: not_started
```

As the task moves through the [TDD loop](/concepts/tdd-loop), the lifecycle
fields are updated in place:

```markdown theme={null}
### 1. Add the behaviour
id: 019f56ae-32c7-7a1e-b715-54cc7e379d32
status: completed
commitSha: ec07a74
```

* One commit that closes several tasks uses the **same `commitSha`** on each.
* A task that became unnecessary is marked `status: superseded` with
  `commitSha: null` — never deleted.
* After editing, re-sync:
  `tiny-brain task sync docs/prd/my-initiative/features/my-feature.md`

<Warning>
  The sync parser treats any `### N. Title` heading as a task definition —
  only use numbered `###` headings inside `## Tasks`. Elsewhere in the
  document, use bold text or unnumbered headings.
</Warning>

## Writing good tasks

A task describes **what** to build, not how — the full TDD cycle (failing
test, implementation, review-driven refactor) happens *inside* one task.
Two shapes to reject:

* **The TDD split** — "Write failing tests for X" + "Implement X" is one
  task ("Add X"), not two. Each half is half a cycle.
* **The verification-only task** — "Run the test suite", "Verify in
  staging". These produce no commit and always end up superseded.
  Verification is part of every cycle, not a task.

The task **description is load-bearing**: it's the `Task:` value in commit
headers, matched by equality (whitespace trimmed). Write it as you want to
type it in a commit message.

## Body sections

Beyond `## Description` and `## Tasks`, features commonly carry Acceptance
Criteria (testable checkboxes), per-task file lists, Dependencies, a Testing
Strategy, and Implementation Notes. As with PRDs, prose is yours; the
frontmatter and task `id:` lines are not.