Forward-looking specs for lingo. One numbered markdown per topic. Plans are
living specs: when implementation forces a change, update the plan in the
same change. Plans hold specs only — grammar, alias tables, ambiguity policy,
API shapes. History belongs in git and packages/lingo/CHANGELOG.md; durable
"how it works now" prose belongs in wiki/. A plan whose work is fully shipped
and whose content is covered by wiki/code gets deleted, and its number retired
(numbers are stable once assigned, never reused).
- Filename:
NNN-kebab-title.md— three digits, stable once assigned. Next free number: 035. - Frontmatter:
id,title,status,created,updated. New plans (since 2026-07-04) also carry:goal:— one-sentence done state.success_criteria:— 1–4 terse pass/fail outcomes, each written as"<measurable outcome> -> <proof artifact>"(test name, script, report path, terminal output). When a criterion is settled, annotate it in place:[MET: …]/[SKIPPED: … + why].
- Status lifecycle:
draft→approved→in-progress→done, plusdeferred(intentionally on hold — reason in the body) andsuperseded(link the successor). A short free-text note after an em dash is welcome and normal:done — shipped 2026-07-04 (D20). If you need a status not on this list, add it here in the same change; otherwise the table is unfilterable. - Progress lives in body checklists, not frontmatter percentages — a single percentage tends to be both inaccurate and unmaintained.
- Tangential ideas surfaced mid-task go to
backlog.md— append, don't act. - Big design decisions inside a plan get a
(locked-in YYYY-MM-DD)marker on their heading; API sketches are real TypeScript signatures in fenced blocks, not prose.
---
id: NNN
title: <Human title>
status: draft
created: YYYY-MM-DD
updated: YYYY-MM-DD
goal: "<one-sentence done state>"
success_criteria:
- "<measurable outcome> -> <proof artifact>"
---
# <Title>
Driver: <the user need, review finding, or decision that motivates this — link it>
## Design principle
<!-- the one idea that settles arguments during implementation -->
## Design (locked-in YYYY-MM-DD)
<!-- real TS signatures for anything public; alias tables; grammar rules -->
## Changes
<!-- numbered, by module -->
## Non-goals
<!-- what this plan deliberately does not do -->
## Open questions
<!-- decisions still owed, and by whom -->
## Acceptance
<!-- which gates prove it done: bun run check, corpus class, eval gates, budgets -->Retired numbers (plans deleted after shipping; content lives in wiki/code): 015–017, 022–023.
Parking lot: backlog.md — ideas with no number yet.