# The .andon/ directory format

`.andon/` at a repository's root is what the repository remembers: conventions, decisions, traps and how-tos, longer
notes, and the plans of its projects. It is committed beside the code, so every clone, tool and Andon instance reads the
same files. This page is the file format. The schemas are in `packages/shared/src/andon-directory.ts`.

## Layout

```
.andon/
  README.md                                      what this directory is (a fixed text)
  settings.json                                  the team's automation settings (repo-settings.md)
  memory/<kind>/<ULID>-<slug>.md                 one memory entry a file
  knowledge/<topic>.md                           a longer note on one topic, edited in place
  knowledge/<area>/<topic>.md                    the same, grouped by area
  plans/<project-slug>/plan.md                   a project's goal, approach and decisions
  plans/<project-slug>/groups/<ULID>-<slug>.md   a PR group's plan, written when the group starts building
```

Nothing else. No index files, counters or generated files: Andon builds its index from the files. A file that isn't one
of these isn't Andon's, and Andon ignores it. `settings.json` has [its own page](https://andon-docs.pages.dev/reference/repo-settings.md).

### Names

- `<ULID>`: 26 Crockford base32 characters, the first `0` to `7` (`01JBQ3Y4Z5A6B7C8D9E0F1G2H3`). It sorts by time, and
  two branches never pick the same one. It is the entry's identity.
- `<slug>`: lowercase letters and digits joined by `-`, at most 40 characters, made from the title. It is for people;
  any slug works.
- `<kind>`: `conventions`, `decisions`, `gotchas`, `how-to`, `glossary` or `people`.
- `<topic>`, `<area>`, `<project-slug>`: one segment each, with the slug's grammar.

### The README

Andon writes `.andon/README.md` the first time it writes anything else there, and never rewrites it. It says what the
directory is, that entries are never edited in place, and where plans go.

### The pointer in CLAUDE.md and AGENTS.md

When it imports memory or writes a plan, Andon adds three lines between `<!-- andon:start -->` and
`<!-- andon:end -->` to a repository's `CLAUDE.md` or `AGENTS.md`: what `.andon/` is, that its entries are the repository's memory, and that `andon memory show` prints them.
It replaces only the text between the markers.

## Front matter

Every file is Markdown that starts with front matter between `---` lines. The front matter is **flat** YAML:

- `key: value`, `key: "quoted value"`, `key: [a, b]`, or a `- item` list under a bare `key:`
- `#` after a space starts a comment, so quote a value that holds one
- no nesting, anchors or multi-line values: prose goes in the body

Dates are `YYYY-MM-DD` or an ISO date-time. An unknown key makes the file invalid.

### A memory entry

`memory/<kind>/<ULID>-<slug>.md`

| Field | Value |
|---|---|
| `id` | The ULID, the same as in the file name. |
| `kind` | The same as the folder. |
| `status` | `proposed`, `accepted` or `retired`. |
| `title` | One line, up to 120 characters. |
| `tags` | Up to 12: lowercase letters and digits, with `-` or `.` inside (`db`, `board.cards`). |
| `paths` | Up to 20 globs relative to the repository, `.gitignore` style (`apps/board/**`, `*.test.ts`). |
| `source` | Where it came from: `run`, `review`, `reply`, `comment`, `person` or `import`, then what it points at (`review PR 212`, `run WEB-12`). |
| `confidence` | 0 to 1. A person's own entry is 1; a run's proposal starts lower. |
| `supersedes` | The id of the entry this one replaces, or `none`. |
| `created` | When it was written. |
| `history` | Only on a compacted entry: the ids folded into it. |
| `sources` | Only on a merged entry: the other entries' sources. |

The body is one paragraph a run can act on: the convention, why, and what to do. Keep it under about 300 tokens (1,200
characters); longer belongs in a knowledge note that the entry points at. A `people` entry names a person by their
Andon handle; an email address is refused in any entry.

### A knowledge note

`knowledge/<topic>.md` or `knowledge/<area>/<topic>.md`

| Field | Value |
|---|---|
| `title` | One line, up to 120 characters. |
| `tags` | As for an entry. |
| `paths` | As for an entry. |
| `updated` | When it last changed. |

The body is up to about 1,500 tokens. Split a bigger note into two topics, or an area.

### A project plan

`plans/<project-slug>/plan.md`

| Field | Value |
|---|---|
| `title` | One line, up to 120 characters. |
| `status` | `active` (the default), `done` or `canceled`. |
| `updated` | When it last changed. |

The body is the project's goal, approach and the decisions taken on the way, up to about 1,500 tokens.

### A group plan

`plans/<project-slug>/groups/<ULID>-<slug>.md`

| Field | Value |
|---|---|
| `id` | The ULID, the same as in the file name. |
| `title` | One line, up to 120 characters. |
| `branch` | The group's branch, or `none` until it has one. |
| `cards` | The cards it builds, by key or id (up to 50). |
| `updated` | When it last changed. |

The body is why the cards ship together, up to about 800 tokens.

## Changing what's there

- **A memory entry is never edited in place.** To change one, add a new file whose `supersedes` names the old id. To
  remove one, add a file with `status: retired` and `supersedes`. Andon reads each chain through its newest file.
- **Only an accepted or retired entry replaces what it names.** A proposed one is listed beside the entry it would
  replace until a review accepts it.
- **Two branches that supersede the same entry** leave two heads: both are read, newest first, until a third entry
  supersedes both.
- **A `supersedes` that names a missing id** is reported, and the entry still counts.
- **Knowledge notes and plans are edited in place.** A group plan isn't edited after its group merges.

Runs propose entries with the `remember` and `knowledge` [MCP tools](https://andon-docs.pages.dev/reference/mcp-tools.md); a proposal rides the run's pull
request.

## An example entry

`.andon/memory/gotchas/01JBQ3Y4Z5A6B7C8D9E0F1G2H3-a-schema-change-is-two-files.md`:

```markdown
---
id: 01JBQ3Y4Z5A6B7C8D9E0F1G2H3
kind: gotchas
status: accepted
title: A schema change is one file
tags: [db, migrations]
paths: [db/migrations/**]
source: review PR 212
confidence: 0.9
supersedes: none
created: 2026-11-02
---

Every schema change is one new file under `db/migrations/`, named by the UTC time, then `pnpm db:check`. Editing an
applied file fails `db:check` and is sent back.
```

## Check and read it

- `andon memory show [path]` prints the live set from a checkout's files: accepted entries with their chains resolved.
  No board needed. See [the `andon` command](https://andon-docs.pages.dev/reference/cli.md#andon-memory).
- In Andon's own repository, `pnpm check:andon-dir` checks every file under `.andon/` for secrets, and every entry and
  note against this format.
