State

---
name: state
description: "STATE, the one page that says where a project stands (.bonsai/STATE.md, bonsai.state/1): its fields, their allowed values and its template. Use it to rewrite STATE, or to add one to a project that has none."
---

<!-- Generated by go generate from Bonsai's code (internal/reference/gen); never edit it by hand: a test rebuilds it and fails on any difference. -->

# STATE: where the project stands

**What it is.** `.bonsai/STATE.md` is one page, in the format `bonsai.state/1`: a short frontmatter and a free body saying where the project stands now, what is next, what is open and what was decided lately. Every project has it at that place (it is no `bonsai.yaml` setting). It is committed and not person-only.

**When to use this skill.** A new session reads STATE first. Rewrite it whole, never append, whenever where the project stands changes, and set `updated` and `updated_by` as you do. `bonsai init` writes it from the template below when the project has none (from then on it is the project's: no update writes over it, and `bonsai unlink` leaves it); a project linked before it had one writes it from the template itself. Its fields and allowed values are also printed by `bonsai check --schema bonsai.state`.

## Fields

| Field | Meaning | Allowed values | Example |
|---|---|---|---|
| `format` | The format and its version, always the first line; its comment points back to these docs | `bonsai.state/1` | `"bonsai.state/1"` |
| `updated` | The day the page was last rewritten, as text: rewrite it with the page, the UTC day from `bonsai now --day` | text matching `^[0-9]{4}-[0-9]{2}-[0-9]{2}$` | `"2026-10-08"` |
| `updated_by` | Who rewrote it: a role and its model, a person's name, or bonsai init for the first page | text | `"orchestrator (opus)"` |
| `labels` | The labels the page carries, by name (a label definition in force says which go on STATE); {} for none | a mapping | under Mappings, below |

## The template

What `bonsai init` writes, `updated` set to the day it runs:

```markdown
---
format: bonsai.state/1   # fields: bonsai check --schema bonsai.state; how to fill: skill base:state
updated: YYYY-MM-DD
updated_by: bonsai init
labels: {}
---

# Where this project stands

Rewritten whole whenever where the project stands changes; never appended to. A new session reads it first.

## Now

## Next

## Open questions

## Decided lately
```

## Mappings

The fields whose example is a mapping, written as STATE's frontmatter holds them: indented `key: value` lines, nested by the field's path. Never write a mapping with content on one line in braces (a flow mapping): Bonsai refuses the file, and in `bonsai.yaml` that stops every call until a person repairs it; `{}` alone is an empty mapping.

```yaml
labels:
  workflow.milestone: "v1"
```