plans/spec
Anatomy of a plan file, every frontmatter field, the lifecycle from idea to shipped, and the two commands that let your AI assistant read along. Implementation details — full reference is on GitHub.
01 · ANATOMY
Every plan file has machine-readable YAML frontmatter and a
human-readable Status banner. If they conflict, frontmatter wins.
The dashboard reads frontmatter; /plans sync watches
for drift between the two.
--- status: active priority: P1 owner: alex type: feature depends_on: [] blocks: [THEME_PICKER] last_updated: 2026-05-06 in_flight: true start_date: 2026-04-28 ---
in_flight flips to true the moment work actively starts.
## Status - Overall: In progress, Phase 2 of 3 - Phase 0 (Color tokens): Done · 2026-04-29 - Phase 1 (Component pass): Done · 2026-05-02 - Phase 2 (Settings UI): In progress · ETA 2026-05-12 Next action: Wire up the theme toggle to the settings panel.
New ideas live as backlog bullets in STATUS.md. No plan file gets created until work is committed. No idea lives in two places.
02 · FRONTMATTER
Nine fields, all flat YAML. Strings, dates, and string lists. No
nested objects, no custom types. plans.json is
regenerated from these fields — never hand-edited.
| Field | Type | Valid values | Required |
|---|---|---|---|
| status | string | active · shipped · superseded |
yes |
| priority | enum | P0 (drop everything) · P1 · P2 · P3 (someday) |
yes |
| owner | string | a name or handle. you is fine for solo projects. |
yes |
| type | enum | feature · refactor · bug · infra · docs |
yes |
| depends_on | string[] | filenames (without .md) of plans this one waits on |
yes |
| blocks | string[] | filenames of plans waiting on this one | yes |
| last_updated | YYYY-MM-DD | date of the most recent edit. Bumped whenever a phase changes. | yes |
| in_flight | boolean | true when work has actively started — drives the Gantt timeline |
when active |
| start_date | YYYY-MM-DD | when work began (or projected start, for queued plans) | optional |
03 · LIFECYCLE
An idea moves through five stages, exactly. There is one canonical location for it at each stage — never two. This is what stops the stale-file pile-up.
1Idea
Add a one-line bullet to STATUS.md backlog. No plan file yet.
2Committed
Run /plans new. Frontmatter is filled, banner is templated, row added to STATUS.md "Up next".
3Started
Flip the flag. Row moves to "In flight". The Gantt picks it up automatically on next sync.
4Shipped
mv plans/active/X.md plans/shipped/X.md. Row moves to "Recently shipped".
5Replaced
Different approach won. status: superseded. Kept for archaeology, not noise.
04 · /plans SKILL
A Claude Code skill (and Antigravity / Cursor port) with two modes. Both run inside your assistant — no separate process, no daemon, no API key.
/plans sync
Reads every plan's frontmatter, runs git log, cross-references the two,
and shows you a diff before writing anything.
depends_on / blocks edgesplans.json and STATUS.md auto-sections/plans new
Walks you through the eight required fields. Picks a filename
from the title. Inserts the templated ## Status banner. Adds the
row to STATUS.md.
depends_on to existing filesFull reference (every edge case, every CLI flag, the JSON schema) lives in the repo.