Skip to content

Commit cbf2039

Browse files
lesnik512claude
andauthored
Bump planning convention 1.x -> 2.0.0 (#150)
* chore(planning): bump convention to 2.0.0 Apply the lesnik512/planning-convention APPLY.md 1.x->2.0.0 update: swap index.py + templates (drop plan.md, add glossary.md), flatten the 11 change folders to flat files and drop committed plan.md, merge the 2.0.0 convention prose into planning/README.md, retire "bundle" wording in CLAUDE.md/Justfile, and record .convention-version=2.0.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: retire "change bundle" wording in living-truth prose Promotion-rule prose now says "change file" (2.0.0 flat-file model). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 1674c30 commit cbf2039

31 files changed

Lines changed: 197 additions & 12235 deletions

File tree

‎CLAUDE.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -68,29 +68,29 @@ Capability index (all of `architecture/`):
6868

6969
Recent design context, bugs, and rationale: bug-audit findings in
7070
`planning/audits/`, post-work reflections in `planning/retros/`, and the audit
71-
arcs bundled under `planning/changes/`. The full extras matrix is
72-
`[project.optional-dependencies]` in `pyproject.toml`.
71+
arcs recorded as change files under `planning/changes/`. The full extras
72+
matrix is `[project.optional-dependencies]` in `pyproject.toml`.
7373

7474
## Workflow
7575

7676
Planning uses the portable two-axis convention: `architecture/` (repo root) is
7777
the living truth home and promotion target; `planning/changes/` holds the
78-
per-change bundles. **Start at the
78+
per-change files. **Start at the
7979
[Quick path](planning/README.md#quick-path-start-here)** in
8080
[`planning/README.md`](planning/README.md) to choose a lane (Full / Lightweight /
81-
Tiny), create a bundle, and ship — that file is the authoritative spec, with
81+
Tiny), create a change file, and ship — that file is the authoritative spec, with
8282
copy-and-fill starters in [`planning/_templates/`](planning/_templates/). Run
83-
`just check-planning` to validate bundles and `just index` to print the listing.
83+
`just check-planning` to validate changes and `just index` to print the listing.
8484

8585
Repo-local notes:
8686

8787
- Design docs and plans live under `planning/`, **not** under `docs/`, so the
8888
mkdocs site excludes them automatically. When superpowers skills default to
89-
`docs/superpowers/specs/` or `docs/superpowers/plans/`, use the change bundle
89+
`docs/superpowers/specs/` or `docs/superpowers/plans/`, use a change file
9090
under `planning/changes/` instead.
9191
- `summary` is finalized at ship to state the realized result, in the
9292
implementing PR alongside the code and the `architecture/` promotion — no
93-
post-merge bookkeeping, no folder move.
93+
post-merge bookkeeping, no file move.
9494

9595
## Code style
9696

‎Justfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ lint-ci:
2121
index:
2222
uv run python planning/index.py
2323

24-
# Validate planning bundles + decisions; CI runs this.
24+
# Validate planning changes + decisions; CI runs this.
2525
check-planning:
2626
uv run python planning/index.py --check
2727

‎planning/.convention-version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.0.0
1+
2.0.0

‎planning/README.md‎

Lines changed: 88 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,77 @@ Specs, plans, and change history for `lite-bootstrap`. The living truth
44
about *what the system does now* lives in [`architecture/`](../architecture/)
55
at the repo root; this directory records *how it got there*.
66

7+
## Quick path (start here)
8+
9+
> The fast lane for making a change. The full reference is in
10+
> [Conventions](#conventions) below — read it only when this isn't enough.
11+
12+
**1. Choose a lane — first matching rule wins:**
13+
14+
1. Any of: needs design judgment · new file/module · public-API change ·
15+
cross-cutting or multi-file · non-trivial test design → **Full** (design template)
16+
2. Purely mechanical: typo · dep bump · linter/formatter/CI tweak ·
17+
mechanical rename · single-line config → **Tiny** (no change file, conventional
18+
commit)
19+
3. Small-but-real, none of the above: ≲30 LOC net · ≤2 files · no new file ·
20+
no public-API change · one straightforward test → **Lightweight** (change template)
21+
22+
Ambiguous between two? Take the heavier. A lightweight change file that outgrows its lane is rewritten from the design template.
23+
24+
**2. Create the change file** (Full / Lightweight only):
25+
`planning/changes/YYYY-MM-DD.NN-<slug>.md`, where `.NN` is a zero-padded
26+
intra-day counter — copied from the matching template (design or change) in
27+
[`_templates/`](_templates/).
28+
29+
**3. Ship in the implementing PR:** hand-edit the affected
30+
`architecture/<capability>.md`, finalize the change file's `summary:` to the
31+
realized result, and run `just check-planning` before pushing.
32+
733
## Conventions
834

9-
> This section is the portable convention, sourced from the canonical repo
35+
> This is the portable convention, sourced from the canonical repo
1036
> [`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention)
1137
> (applied version in [`.convention-version`](.convention-version)). To update
1238
> it, run that repo's `APPLY.md` flow. The generated change index (`just index`)
1339
> and the `## Other` pointers below are repo-local.
1440
1541
### Two axes, never mixed
1642

17-
- **`architecture/` (repo root) — the present.** One file per capability,
18-
living prose, updated in the same PR that ships the change. The truth home.
19-
- **`planning/changes/` — the past-and-pending.** One folder per change,
43+
- **`architecture/` (repo root) — the present.** One file per capability, plus
44+
a single `glossary.md` (the ubiquitous language); living prose, updated in the
45+
same PR that ships the change. The truth home.
46+
- **`planning/changes/` — the past-and-pending.** One file per change,
2047
kept in place after ship.
2148

2249
A change **promotes** its conclusions into the affected
2350
`architecture/<capability>.md` by hand **in the implementing PR, alongside the
2451
code** — the edit rides in the same diff and is reviewed with it, never applied
2552
as a separate post-merge step. That hand-edit is what keeps `architecture/`
26-
true; the bundle stays in `changes/` as the *why*.
53+
true; the change file stays in `changes/` as the *why*.
54+
55+
### Glossary
56+
57+
`architecture/glossary.md` is the project's **ubiquitous language** — one page
58+
defining the domain terms that code, specs, and capability pages all share. Like
59+
the capability files beside it, it is living prose with **no frontmatter**, dated
60+
by git, and authored lazily: it appears when the first term is worth pinning down.
61+
62+
Each entry is a term, a one-or-two-sentence definition of what it *is* (not what
63+
it does), and an optional `_Avoid_:` line naming the synonyms to reject:
2764

28-
### Change bundles
65+
```md
66+
**Timer**:
67+
A scheduled future delivery, identified by a timer id.
68+
_Avoid_: job, task, alarm
69+
```
2970

30-
A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
71+
Keep it a glossary, not a spec — no implementation detail. A change that
72+
introduces or sharpens a term updates `glossary.md` in the same PR, the same way
73+
a behavior change promotes into a capability file.
74+
75+
### Change files
76+
77+
A change is a file `changes/YYYY-MM-DD.NN-<slug>.md`:
3178

3279
- `YYYY-MM-DD` — proposal date; `.NN` — zero-padded intra-day counter
3380
(`.01`, `.02`, …) that breaks same-date ties so the timeline sorts stably.
@@ -36,43 +83,61 @@ A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
3683
`summary` is written when the change is created (the intent one-liner) and
3784
**finalized at ship** to state the realized result — set in the implementing
3885
PR, alongside the code and the `architecture/` promotion. No post-merge
39-
bookkeeping, no folder move. `date` and `slug` are never written — they are
40-
read from the bundle's directory name.
86+
bookkeeping, no file move. `date` and `slug` are never written — they are
87+
read from the file name.
4188

4289
### Three lanes
4390

4491
| Lane | Artifacts | Use when |
4592
|------|-----------|----------|
46-
| **Full** | `design.md` + `plan.md` | design judgment; new file/module; public-API change; cross-cutting/multi-file; non-trivial test design |
47-
| **Lightweight** | `change.md` | small-but-real: ≲30 LOC net, ≤2 files, no new file, no public-API change, single straightforward test |
93+
| **Full** | one change file from the design template | design judgment; new file/module; public-API change; cross-cutting/multi-file; non-trivial test design |
94+
| **Lightweight** | one change file from the change template | small-but-real: ≲30 LOC net, ≤2 files, no new file, no public-API change, single straightforward test |
4895
| **Tiny** | none — conventional commit | typo, dep bump, linter/formatter/CI tweak, mechanical rename, single-line config |
4996

50-
Heavier lane wins on ambiguity. A `change.md` that outgrows its lane splits
51-
into `design.md` + `plan.md`.
97+
Heavier lane wins on ambiguity. A lightweight change file that outgrows its lane is rewritten from the design template.
98+
99+
### Plans are ephemeral
100+
101+
The executable plan — task checklists, embedded code, commit sequences,
102+
whatever the executor needs — is a working artifact, not history. Keep it out
103+
of `changes/` and out of version control (git-ignored scratch, e.g.
104+
`.superpowers/`). Once the change ships, the diff and the PR are the record
105+
of execution; a committed plan duplicates them. `check-planning` rejects
106+
anything in `changes/` that is not a flat change file.
107+
108+
### Lean specs
109+
110+
The change file is the single home of a change's rationale:
111+
112+
- The PR body summarizes and links to the change file — it never restates it.
113+
- Rejected alternatives live in `decisions/` and are referenced, not retold.
114+
- Show a sketch when the design needs code; never the full diff-to-be.
115+
- Delete template sections that don't apply — an empty section is ceremony.
116+
- Most designs fit well under ~700 words; length must buy information.
52117

53118
### Artifacts at a glance
54119

55-
- **`design.md`** — the spec: the *thinking* (why, design, trade-offs, scope).
56-
- **`plan.md`** — the plan: the *sequencing* (the executor's task checklist).
57-
- **`change.md`** — both, condensed, for the lightweight lane.
58-
- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
59-
(especially options *rejected*), each with a revisit trigger, so reviews don't
60-
re-litigate them; listed by `just index`.
120+
- **design template** — the spec: the *thinking* (why, design, trade-offs,
121+
scope); the change file it produces is the single home of rationale (see
122+
[Lean specs](#lean-specs)).
123+
- **change template** — the condensed spec for the lightweight lane.
61124
- **`releases/<semver>.md`** — per-release user-facing notes.
62125
- **`audits/<date>-<slug>.md`** — findings from a code/docs/bug-hunt sweep;
63126
spawns fix changes.
64127
- **`retros/<date>-<slug>.md`** — what we learned after a body of work.
65128
- **`deferred.md`** — real-but-unscheduled items, each with a revisit trigger.
129+
- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
130+
(especially options *rejected*), each with a revisit trigger; listed by
131+
`just index`.
66132

67133
Templates live in [`_templates/`](_templates/).
68134

69135
### Frontmatter
70136

71-
`date` and `slug` are **derived from the directory / file name** — never
137+
`date` and `slug` are **derived from the file name** — never
72138
repeated in frontmatter. So:
73139

74-
- `design.md` / `change.md`: `summary` (single line) only.
75-
- `plan.md`: **no frontmatter** — its identity is the bundle directory.
140+
- `changes/*.md`: `summary` (single line) only.
76141
- `decisions/*.md`: `status` (accepted|superseded), `summary`, and optional
77142
`supersedes` / `superseded_by`.
78143
- Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
@@ -85,7 +150,7 @@ only field the index renders.
85150

86151
The listing is **generated**, not maintained — run `just index` to print it:
87152
changes flat, newest-first, then decisions newest-first. The frontmatter in
88-
each bundle / decision file is the single source of truth; there is no
153+
each change / decision file is the single source of truth; there is no
89154
committed copy to drift.
90155

91156
## Other

‎planning/_templates/change.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ summary: One line — shown in the generated index. Written at creation; finaliz
55
# Change: One-line capitalized title
66

77
**Lane:** lightweight — ≲30 LOC net, ≤2 files, no new file, no public-API
8-
change, a single straightforward test. If it outgrows this, split into
9-
`design.md` + `plan.md`.
8+
change, a single straightforward test. If it outgrows this, rewrite it from
9+
the design template.
1010

1111
## Goal
1212

‎planning/_templates/design.md‎

Lines changed: 12 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ summary: One line — shown in the generated index. Written at creation; finaliz
44

55
# Design: One-line capitalized title
66

7+
<!-- The single home of this change's rationale: the PR body summarizes and
8+
links here, never restates. Delete any section that doesn't apply — an empty
9+
section is ceremony. Most designs fit well under ~700 words. -->
10+
711
## Summary
812

913
One paragraph. What changes, at the level a reader needs to decide if this
@@ -12,37 +16,23 @@ spec is worth reading in full.
1216
## Motivation
1317

1418
Why now. What is broken or missing. Concrete observations / numbers, not
15-
abstract complaints. Link to memory entries or earlier specs when relevant.
16-
17-
## Non-goals
18-
19-
What is deliberately out of scope and (when nontrivial) why. Each item is
20-
a sentence; one line each.
19+
abstract complaints.
2120

2221
## Design
2322

24-
### 1. <First piece>
25-
2623
What changes, in enough detail that a reader who has not seen the codebase
27-
can follow. Code samples / diagrams welcome.
24+
can follow. Sketches and interface fragments welcome; never the full
25+
diff-to-be. Reference rejected alternatives in `decisions/` instead of
26+
retelling them.
2827

29-
### 2. <Second piece>
30-
31-
...
32-
33-
## Operations
34-
35-
Out-of-repo steps (DNS, infra, external account changes). Omit if none.
36-
37-
## Out of scope
28+
## Non-goals
3829

39-
Already covered above under Non-goals if appropriate. Repeat-list of
40-
explicitly-excluded follow-ups belongs here when the list is long.
30+
What is deliberately out of scope and (when nontrivial) why. One line each.
4131

4232
## Testing
4333

44-
How we know it landed correctly. New pytest? Smoke check on live URL?
45-
Lint pass? Be specific.
34+
How we know it landed correctly. Be specific: the command and the expected
35+
signal.
4636

4737
## Risk
4838

‎planning/_templates/glossary.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Glossary
2+
3+
The project's ubiquitous language — the domain terms that code, specs, and
4+
capability pages share. Living prose, no frontmatter, dated by git. Each entry is
5+
a term, what it *is* (not what it does), and the synonyms to avoid. No
6+
implementation detail; this is a glossary, not a spec.
7+
8+
**Term**:
9+
A one-or-two-sentence definition of what it is.
10+
_Avoid_: rejected-synonym, another-one
11+
12+
**Another term**:
13+
Define what it is, tightly. Group related terms under `##` subheadings when
14+
natural clusters emerge; a flat list is fine when they don't.
15+
_Avoid_: …

‎planning/_templates/plan.md‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

planning/changes/2026-05-31.01-audit-implementation/design.md renamed to planning/changes/2026-05-31.01-audit-implementation.md

File renamed without changes.

0 commit comments

Comments
 (0)