Adopt planning-convention v1.1.1 and migrate docs/superpowers (#19) · modern-python/.github@10c32a2 · GitHub
Skip to content

Commit 10c32a2

Browse files
lesnik512claude
lesnik512
and
claude
authored
Adopt planning-convention v1.1.1 and migrate docs/superpowers (#19)
* docs: spec for adopting the planning convention Brainstorming output: adopt lesnik512/planning-convention v1.1.1 at the repo root and migrate docs/superpowers/ into planning/ change bundles plus a lazy architecture/ truth home. Spec is bootstrapped into the new tree it describes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: implementation plan for adopting the planning convention Eight bite-sized tasks: scaffold the convention skeleton, merge the README prose, migrate the four docs/superpowers bundles, move the launch playbook and retire docs/superpowers, wire just + CI, and verify + PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: scaffold planning convention skeleton (v1.1.1) * docs: add planning/README with merged convention prose * docs: migrate promotion-strategy and community-channels into bundles * docs: migrate org-favicon-social-card into a Full bundle * docs: migrate community-health defaults into a bundle * docs: move launch playbook to planning/, retire docs/superpowers Repair stale cross-links to the migrated promotion-strategy spec. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: wire just + CI check-planning, point CLAUDE.md at the convention --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent e0596ac commit 10c32a2

26 files changed

Lines changed: 1509 additions & 11 deletions

File tree

‎.github/workflows/planning.yml‎

Lines changed: 18 additions & 0 deletions

‎CLAUDE.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,20 @@ GitHub occasionally type-checks a **stale `refs/pull/<n>/merge`** after a push,
5353
PR can show an old lint/test failure that no longer matches the branch. Confirm by
5454
running the failing check locally at the branch HEAD (with the pinned tool version);
5555
if it's clean, push a fresh commit to force GitHub to recompute the merge ref.
56+
57+
## Workflow
58+
59+
Planning follows the convention in [`planning/README.md`](planning/README.md) —
60+
its **Quick path** is authoritative. Pick a lane (Full = `design.md` + `plan.md`,
61+
Lightweight = `change.md`, Tiny = conventional commit), create a bundle under
62+
`planning/changes/YYYY-MM-DD.NN-<slug>/` from `planning/_templates/`, and run
63+
`just check-planning` before pushing. The applied convention version is in
64+
`planning/.convention-version`; update it via the canonical repo's `APPLY.md`.
65+
66+
## Architecture
67+
68+
`architecture/` (repo root) is the living truth about what this repo does now —
69+
one file per capability plus `glossary.md`, no frontmatter, authored lazily.
70+
**When a change alters a capability's behavior, update the matching
71+
`architecture/<capability>.md` in the same PR.** The change bundle in
72+
`planning/changes/` stays as the *why*.

‎Justfile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
default: check-planning test
2+
3+
index:
4+
uv run python planning/index.py
5+
6+
check-planning:
7+
uv run python planning/index.py --check
8+
9+
lint-ci: check-planning
10+
11+
test:
12+
uv run pytest

‎architecture/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Architecture — the truth home
2+
3+
This directory holds the **living truth** about what `modern-python/.github` does
4+
*now*: one file per capability, plus a single `glossary.md` (the ubiquitous
5+
language). These files carry **no frontmatter** and are dated by git.
6+
7+
**Promotion rule:** when a change alters a capability's behavior, hand-edit the
8+
matching `architecture/<capability>.md` in the **same PR** as the code — the edit
9+
rides in the same diff and is reviewed with it. The change bundle in
10+
`planning/changes/` stays as the *why*; this directory stays *true*.
11+
12+
Capability files and `glossary.md` are authored **lazily** — each appears when the
13+
first capability or term is worth pinning down.

‎mkdocs.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ repo_name: modern-python
77
# Repo-internal docs that must not be published to the public site.
88
exclude_docs: |
99
DEPLOYMENT.md
10-
superpowers/
1110
1211
theme:
1312
name: material

‎planning/.convention-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.1.1

‎planning/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Planning — modern-python/.github
2+
3+
This repo's planning home, following the portable two-axis convention from
4+
[`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention)
5+
(applied version in [`.convention-version`](.convention-version)). `architecture/`
6+
(repo root) holds the living truth about what the system does now; the bundles in
7+
[`changes/`](changes/) record how it got there. To update the convention itself,
8+
re-run that repo's `APPLY.md` flow.
9+
10+
## Quick path (start here)
11+
12+
> The fast lane for making a change. The full reference is in
13+
> [Conventions](#conventions) below — read it only when this isn't enough.
14+
15+
**1. Choose a lane — first matching rule wins:**
16+
17+
1. Any of: needs design judgment · new file/module · public-API change ·
18+
cross-cutting or multi-file · non-trivial test design → **Full**
19+
(`design.md` + `plan.md`)
20+
2. Purely mechanical: typo · dep bump · linter/formatter/CI tweak ·
21+
mechanical rename · single-line config → **Tiny** (no bundle, conventional
22+
commit)
23+
3. Small-but-real, none of the above: ≲30 LOC net · ≤2 files · no new file ·
24+
no public-API change · one straightforward test → **Lightweight**
25+
(`change.md`)
26+
27+
Ambiguous between two? Take the heavier. A `change.md` that outgrows its lane
28+
splits into `design.md` + `plan.md`.
29+
30+
**2. Create the bundle** (Full / Lightweight only):
31+
`planning/changes/YYYY-MM-DD.NN-<slug>/`, where `.NN` is a zero-padded
32+
intra-day counter. Copy the matching template from
33+
[`_templates/`](_templates/).
34+
35+
**3. Ship in the implementing PR:** hand-edit the affected
36+
`architecture/<capability>.md`, finalize the bundle's `summary:` to the
37+
realized result, and run `just check-planning` before pushing.
38+
39+
## Conventions
40+
41+
> This is the portable convention, sourced from the canonical repo
42+
> [`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention)
43+
> (applied version in [`.convention-version`](.convention-version)). To update
44+
> it, run that repo's `APPLY.md` flow. The generated change index (`just index`)
45+
> and the `## Other` pointers below are repo-local.
46+
47+
### Two axes, never mixed
48+
49+
- **`architecture/` (repo root) — the present.** One file per capability, plus
50+
a single `glossary.md` (the ubiquitous language); living prose, updated in the
51+
same PR that ships the change. The truth home.
52+
- **`planning/changes/` — the past-and-pending.** One folder per change,
53+
kept in place after ship.
54+
55+
A change **promotes** its conclusions into the affected
56+
`architecture/<capability>.md` by hand **in the implementing PR, alongside the
57+
code** — the edit rides in the same diff and is reviewed with it, never applied
58+
as a separate post-merge step. That hand-edit is what keeps `architecture/`
59+
true; the bundle stays in `changes/` as the *why*.
60+
61+
### Glossary
62+
63+
`architecture/glossary.md` is the project's **ubiquitous language** — one page
64+
defining the domain terms that code, specs, and capability pages all share. Like
65+
the capability files beside it, it is living prose with **no frontmatter**, dated
66+
by git, and authored lazily: it appears when the first term is worth pinning down.
67+
68+
Each entry is a term, a one-or-two-sentence definition of what it *is* (not what
69+
it does), and an optional `_Avoid_:` line naming the synonyms to reject:
70+
71+
```md
72+
**Timer**:
73+
A scheduled future delivery, identified by a timer id.
74+
_Avoid_: job, task, alarm
75+
```
76+
77+
Keep it a glossary, not a spec — no implementation detail. A change that
78+
introduces or sharpens a term updates `glossary.md` in the same PR, the same way
79+
a behavior change promotes into a capability file.
80+
81+
### Change bundles
82+
83+
A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
84+
85+
- `YYYY-MM-DD` — proposal date; `.NN` — zero-padded intra-day counter
86+
(`.01`, `.02`, …) that breaks same-date ties so the timeline sorts stably.
87+
- `<slug>` — kebab-case description, not a story ID.
88+
89+
`summary` is written when the change is created (the intent one-liner) and
90+
**finalized at ship** to state the realized result — set in the implementing
91+
PR, alongside the code and the `architecture/` promotion. No post-merge
92+
bookkeeping, no folder move. `date` and `slug` are never written — they are
93+
read from the bundle's directory name.
94+
95+
### Three lanes
96+
97+
| Lane | Artifacts | Use when |
98+
|------|-----------|----------|
99+
| **Full** | `design.md` + `plan.md` | design judgment; new file/module; public-API change; cross-cutting/multi-file; non-trivial test design |
100+
| **Lightweight** | `change.md` | small-but-real: ≲30 LOC net, ≤2 files, no new file, no public-API change, single straightforward test |
101+
| **Tiny** | none — conventional commit | typo, dep bump, linter/formatter/CI tweak, mechanical rename, single-line config |
102+
103+
Heavier lane wins on ambiguity. A `change.md` that outgrows its lane splits
104+
into `design.md` + `plan.md`.
105+
106+
### Artifacts at a glance
107+
108+
- **`design.md`** — the spec: the *thinking* (why, design, trade-offs, scope).
109+
- **`plan.md`** — the plan: the *sequencing* (the executor's task checklist).
110+
- **`change.md`** — both, condensed, for the lightweight lane.
111+
- **`releases/<semver>.md`** — per-release user-facing notes.
112+
- **`audits/<date>-<slug>.md`** — findings from a code/docs/bug-hunt sweep;
113+
spawns fix changes.
114+
- **`retros/<date>-<slug>.md`** — what we learned after a body of work.
115+
- **`deferred.md`** — real-but-unscheduled items, each with a revisit trigger.
116+
- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
117+
(especially options *rejected*), each with a revisit trigger; listed by
118+
`just index`.
119+
120+
Templates live in [`_templates/`](_templates/).
121+
122+
### Frontmatter
123+
124+
`date` and `slug` are **derived from the directory / file name** — never
125+
repeated in frontmatter. So:
126+
127+
- `design.md` / `change.md`: `summary` (single line) only.
128+
- `plan.md`: **no frontmatter** — its identity is the bundle directory.
129+
- `decisions/*.md`: `status` (accepted|superseded), `summary`, and optional
130+
`supersedes` / `superseded_by`.
131+
- Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
132+
133+
**`summary`** is one line: written at creation as the intent, then **finalized
134+
at ship** to state the realized result — what shipped and its effect. It is the
135+
only field the index renders.
136+
137+
## Index
138+
139+
Run `just index` to print the change/decision listing — a query over the files,
140+
never a committed artifact.
141+
142+
## Other
143+
144+
- [`launch-playbook.md`](launch-playbook.md) — internal Phase 4 launch asset (not published).
145+
- [`deferred.md`](deferred.md) — real-but-unscheduled items, each with a revisit trigger.

‎planning/_templates/change.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
3+
---
4+
5+
# Change: One-line capitalized title
6+
7+
**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`.
10+
11+
## Goal
12+
13+
One or two sentences: what changes and why.
14+
15+
## Approach
16+
17+
The shape of the change in brief — enough that a reviewer sees the design
18+
without a full spec. Link the truth home (`architecture/<capability>.md`) if a
19+
capability contract moves.
20+
21+
## Files
22+
23+
- `path/to/file.py` — what changes
24+
- `tests/test_x.py` — test added / updated
25+
26+
## Verification
27+
28+
- [ ] Failing test first — command + expected error.
29+
- [ ] Apply the change.
30+
- [ ] Test passes — command.
31+
- [ ] `just test` — full suite green.
32+
- [ ] `just lint` — clean.

‎planning/_templates/decision.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
status: accepted # accepted | superseded
3+
summary: One line — shown in `just index`.
4+
supersedes: null
5+
superseded_by: null
6+
---
7+
8+
# One-line capitalized title
9+
10+
**Decision:** What was decided, in a sentence.
11+
12+
## Context
13+
14+
Why this came up; the options that were on the table.
15+
16+
## Decision & rationale
17+
18+
The call and why — including why the alternatives were rejected. Enough that a
19+
future explorer doesn't re-litigate it.
20+
21+
## Revisit trigger
22+
23+
The concrete signal that should reopen this decision.

‎planning/_templates/design.md‎

Lines changed: 49 additions & 0 deletions

0 commit comments

Comments
 (0)