Skip to content
AndonDocs
GitHub
Look something up

The .andon/ directory format

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

.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

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

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; 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.
  • In Andon’s own repository, pnpm check:andon-dir checks every file under .andon/ for secrets, and every entry and note against this format.