chore: adopt canonical planning convention (#16)

lesnik512 · web-flow · commit cd41771b348f · 2026-06-25T21:52:31.000+03:00
* chore: adopt canonical planning convention

Fresh-adopt the portable two-axis planning convention from
lesnik512/planning-convention (v1.0.0):

- Vendor planning/index.py (validator + index generator) and
  planning/_templates/ (change, design, plan, decision, release).
- Add planning/README.md with the Quick path + Conventions prose and
  planning/.convention-version (1.0.0); scaffold changes/, decisions/,
  releases/ directories.
- Add architecture/README.md as the per-capability truth home with the
  promotion rule (no capability files yet — repo authors its own).
- Wire `uv run python planning/index.py --check` into `lint-ci`; add
  `index` and `check-planning` recipes to the Justfile.
- Point CLAUDE.md § Workflow at planning/README.md's Quick path and add
  the architecture promotion reminder.

just lint-ci green (ruff + ty + planning validator); check-planning: OK.

* index.py: tolerate a missing changes/ dir (sync canonical fix)
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,10 +1,14 @@
 ## Workflow
 
-Per-feature workflow: brainstorming → spec in
-`planning/specs/YYYY-MM-DD-<slug>-design.md` → writing-plans →
-plan in `planning/plans/YYYY-MM-DD-<slug>-plan.md` →
-executing-plans / subagent-driven-development →
-requesting-code-review → finishing-a-development-branch.
+Planning uses a portable convention — `architecture/` (repo root) is the living
+**truth home** and promotion target; `planning/changes/` holds the per-change
+bundles. Start at the
+[Quick path](planning/README.md#quick-path-start-here) in `planning/README.md`
+(the authoritative spec) to pick a lane — **Full** (`design.md` + `plan.md`),
+**Lightweight** (single `change.md`), or **Tiny** (just a commit) — and ship.
+`just check-planning` validates bundles; `just index` prints the change +
+decision listing; `planning/_templates/` are copy-and-fill starting points.
 
-Topic slugs are kebab-case descriptions (e.g. `faststream-0.7-migration`),
-not story IDs.
+**When a change alters a capability's behavior, update the matching
+`architecture/<capability>.md` in the same PR** — that promotion is what keeps
+`architecture/` true.
diff --git a/Justfile b/Justfile
@@ -15,6 +15,15 @@ lint-ci:
     uv run ruff format --check
     uv run ruff check --no-fix
     uv run ty check
+    uv run python planning/index.py --check
+
+# Print the planning change index (flat, newest-first) to stdout.
+index:
+    uv run python planning/index.py
+
+# Validate planning bundles + decisions; CI runs this.
+check-planning:
+    uv run python planning/index.py --check
 
 test *args:
     uv run --no-sync pytest {{ args }}
diff --git a/architecture/README.md b/architecture/README.md
@@ -0,0 +1,23 @@
+# Architecture
+
+The living truth about what `modern-di-faststream` does **now** — one file per
+capability, updated by hand whenever a change ships. The *why* and *how it got
+here* live in [`../planning/changes/`](../planning/changes/), and decisions
+deliberately taken (including options rejected) in
+[`../planning/decisions/`](../planning/decisions/); this directory is the present.
+
+Each capability file is an **implementation-detail** page. Its terse
+**invariant summary** ("what Claude must not break") lives in
+[`../CLAUDE.md`](../CLAUDE.md) § Architecture.
+
+These files carry **no frontmatter** — they are prose, dated by git.
+
+## Capabilities
+
+_None yet — the repo authors its own capability files as changes ship._
+
+## Promotion rule
+
+Shipping a change hand-edits the affected capability file(s) here to match the
+new reality, in the same PR as the code. The change bundle stays in place under
+[`../planning/changes/`](../planning/changes/) — no folder move.
diff --git a/planning/.convention-version b/planning/.convention-version
@@ -0,0 +1 @@
+1.0.0
diff --git a/planning/README.md b/planning/README.md
@@ -0,0 +1,128 @@
+# Planning
+
+Specs, plans, and change history for `modern-di-faststream`. The living truth
+about *what the system does now* lives in [`architecture/`](../architecture/)
+at the repo root; this directory records *how it got there*.
+
+## Quick path (start here)
+
+> The fast lane for making a change. The full reference is in
+> [Conventions](#conventions) below — read it only when this isn't enough.
+
+**1. Choose a lane — first matching rule wins:**
+
+1. Any of: needs design judgment · new file/module · public-API change ·
+   cross-cutting or multi-file · non-trivial test design → **Full**
+   (`design.md` + `plan.md`)
+2. Purely mechanical: typo · dep bump · linter/formatter/CI tweak ·
+   mechanical rename · single-line config → **Tiny** (no bundle, conventional
+   commit)
+3. Small-but-real, none of the above: ≲30 LOC net · ≤2 files · no new file ·
+   no public-API change · one straightforward test → **Lightweight**
+   (`change.md`)
+
+Ambiguous between two? Take the heavier. A `change.md` that outgrows its lane
+splits into `design.md` + `plan.md`.
+
+**2. Create the bundle** (Full / Lightweight only):
+`planning/changes/YYYY-MM-DD.NN-<slug>/`, where `.NN` is a zero-padded
+intra-day counter. Copy the matching template from
+[`_templates/`](_templates/).
+
+**3. Ship in the implementing PR:** hand-edit the affected
+`architecture/<capability>.md`, finalize the bundle's `summary:` to the
+realized result, and run `just check-planning` before pushing.
+
+## Conventions
+
+> This is the portable convention, sourced from the canonical repo
+> [`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention)
+> (applied version in [`.convention-version`](.convention-version)). To update
+> it, run that repo's `APPLY.md` flow. The generated change index (`just index`)
+> and the `## Other` pointers below are repo-local.
+
+### Two axes, never mixed
+
+- **`architecture/` (repo root) — the present.** One file per capability,
+  living prose, updated in the same PR that ships the change. The truth home.
+- **`planning/changes/` — the past-and-pending.** One folder per change,
+  kept in place after ship.
+
+A change **promotes** its conclusions into the affected
+`architecture/<capability>.md` by hand **in the implementing PR, alongside the
+code** — the edit rides in the same diff and is reviewed with it, never applied
+as a separate post-merge step. That hand-edit is what keeps `architecture/`
+true; the bundle stays in `changes/` as the *why*.
+
+### Change bundles
+
+A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
+
+- `YYYY-MM-DD` — proposal date; `.NN` — zero-padded intra-day counter
+  (`.01`, `.02`, …) that breaks same-date ties so the timeline sorts stably.
+- `<slug>` — kebab-case description, not a story ID.
+
+`summary` is written when the change is created (the intent one-liner) and
+**finalized at ship** to state the realized result — set in the implementing
+PR, alongside the code and the `architecture/` promotion. No post-merge
+bookkeeping, no folder move. `date` and `slug` are never written — they are
+read from the bundle's directory name.
+
+### Three lanes
+
+| Lane | Artifacts | Use when |
+|------|-----------|----------|
+| **Full** | `design.md` + `plan.md` | design judgment; new file/module; public-API change; cross-cutting/multi-file; non-trivial test design |
+| **Lightweight** | `change.md` | small-but-real: ≲30 LOC net, ≤2 files, no new file, no public-API change, single straightforward test |
+| **Tiny** | none — conventional commit | typo, dep bump, linter/formatter/CI tweak, mechanical rename, single-line config |
+
+Heavier lane wins on ambiguity. A `change.md` that outgrows its lane splits
+into `design.md` + `plan.md`.
+
+### Artifacts at a glance
+
+- **`design.md`** — the spec: the *thinking* (why, design, trade-offs, scope).
+- **`plan.md`** — the plan: the *sequencing* (the executor's task checklist).
+- **`change.md`** — both, condensed, for the lightweight lane.
+- **`releases/<semver>.md`** — per-release user-facing notes.
+- **`audits/<date>-<slug>.md`** — findings from a code/docs/bug-hunt sweep;
+  spawns fix changes.
+- **`retros/<date>-<slug>.md`** — what we learned after a body of work.
+- **`deferred.md`** — real-but-unscheduled items, each with a revisit trigger.
+- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
+  (especially options *rejected*), each with a revisit trigger; listed by
+  `just index`.
+
+Templates live in [`_templates/`](_templates/).
+
+### Frontmatter
+
+`date` and `slug` are **derived from the directory / file name** — never
+repeated in frontmatter. So:
+
+- `design.md` / `change.md`: `summary` (single line) only.
+- `plan.md`: **no frontmatter** — its identity is the bundle directory.
+- `decisions/*.md`: `status` (accepted|superseded), `summary`, and optional
+  `supersedes` / `superseded_by`.
+- Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
+
+**`summary`** is one line: written at creation as the intent, then **finalized
+at ship** to state the realized result — what shipped and its effect. It is the
+only field the index renders.
+
+## Index
+
+The listing is **generated**, not maintained — run `just index` to print it: a
+flat, newest-first list of changes, then decisions newest-first. The frontmatter
+in each bundle / decision file is the single source of truth; there is no
+committed copy to drift.
+
+## Other
+
+- **[`architecture/`](../architecture/)** at the repo root — the living
+  capability truth. This is the promotion target on every ship.
+- **[decisions/](decisions/)** — design decisions taken (and alternatives
+  rejected), each with a revisit trigger, so reviews don't re-litigate them;
+  indexed by `just index`.
+- **[specs/](specs/)** — pre-convention design docs retained for history (e.g.
+  the FastStream 0.7 migration design).
diff --git a/planning/_templates/change.md b/planning/_templates/change.md
@@ -0,0 +1,32 @@
+---
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
+---
+
+# Change: One-line capitalized title
+
+**Lane:** lightweight — ≲30 LOC net, ≤2 files, no new file, no public-API
+change, a single straightforward test. If it outgrows this, split into
+`design.md` + `plan.md`.
+
+## Goal
+
+One or two sentences: what changes and why.
+
+## Approach
+
+The shape of the change in brief — enough that a reviewer sees the design
+without a full spec. Link the truth home (`architecture/<capability>.md`) if a
+capability contract moves.
+
+## Files
+
+- `path/to/file.py` — what changes
+- `tests/test_x.py` — test added / updated
+
+## Verification
+
+- [ ] Failing test first — command + expected error.
+- [ ] Apply the change.
+- [ ] Test passes — command.
+- [ ] `just test` — full suite green.
+- [ ] `just lint` — clean.
diff --git a/planning/_templates/decision.md b/planning/_templates/decision.md
@@ -0,0 +1,23 @@
+---
+status: accepted        # accepted | superseded
+summary: One line — shown in `just index`.
+supersedes: null
+superseded_by: null
+---
+
+# One-line capitalized title
+
+**Decision:** What was decided, in a sentence.
+
+## Context
+
+Why this came up; the options that were on the table.
+
+## Decision & rationale
+
+The call and why — including why the alternatives were rejected. Enough that a
+future explorer doesn't re-litigate it.
+
+## Revisit trigger
+
+The concrete signal that should reopen this decision.
diff --git a/planning/_templates/design.md b/planning/_templates/design.md
@@ -0,0 +1,49 @@
+---
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
+---
+
+# Design: One-line capitalized title
+
+## Summary
+
+One paragraph. What changes, at the level a reader needs to decide if this
+spec is worth reading in full.
+
+## Motivation
+
+Why now. What is broken or missing. Concrete observations / numbers, not
+abstract complaints. Link to memory entries or earlier specs when relevant.
+
+## Non-goals
+
+What is deliberately out of scope and (when nontrivial) why. Each item is
+a sentence; one line each.
+
+## Design
+
+### 1. <First piece>
+
+What changes, in enough detail that a reader who has not seen the codebase
+can follow. Code samples / diagrams welcome.
+
+### 2. <Second piece>
+
+...
+
+## Operations
+
+Out-of-repo steps (DNS, infra, external account changes). Omit if none.
+
+## Out of scope
+
+Already covered above under Non-goals if appropriate. Repeat-list of
+explicitly-excluded follow-ups belongs here when the list is long.
+
+## Testing
+
+How we know it landed correctly. New pytest? Smoke check on live URL?
+Lint pass? Be specific.
+
+## Risk
+
+What could go wrong, ranked by likelihood × impact. Mitigations.
diff --git a/planning/_templates/plan.md b/planning/_templates/plan.md
@@ -0,0 +1,46 @@
+# <slug> — implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use
+> superpowers:subagent-driven-development (recommended) or
+> superpowers:executing-plans to implement this plan task-by-task. Steps
+> use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** One sentence — what shipping this plan achieves. No design
+rationale; link to the spec for that.
+
+**Spec:** [`design.md`](./design.md)
+
+**Branch:** `feat/my-change` (or `fix/`, `chore/`, etc.)
+
+**Commit strategy:** Per-task commits / single commit / squash on merge.
+Whichever fits.
+
+---
+
+### Task 1: <imperative description>
+
+**Files:**
+- Modify: `path/to/file.py`
+- Create: `path/to/new.py`
+
+One sentence on what this task accomplishes. No deeper reasoning — that's
+in the spec.
+
+- [ ] **Step 1: <action>**
+
+  Run / edit / verify command. Expected output.
+
+- [ ] **Step 2: <action>**
+
+  ...
+
+- [ ] **Step 3: Commit**
+
+  ```bash
+  git add path/to/file.py
+  git commit -m "<type>: <subject>"
+  ```
+
+---
+
+### Task 2: ...
diff --git a/planning/_templates/release.md b/planning/_templates/release.md
@@ -0,0 +1,38 @@
+# <project> <version> — <one-line headline>
+
+<One or two sentences: what this release is and its headline change. Say up
+front if there are no behavior/API changes.>
+
+<!-- Keep only the sections that apply; reorder/rename freely. A tiny release
+     may be just the title + one section. Versioning is tag-driven — the
+     release tag sets the version (`just publish` runs `uv version`), so there
+     is no pyproject bump. -->
+
+## Feature
+
+- **<name>.** What it adds and how to use it.
+
+## Fix
+
+- **<name>.** What was broken, now fixed (reference the issue/regression).
+
+## Internal refactors
+
+- **<name>.** What changed under the hood, stated as no behavior change.
+
+## Packaging
+
+- Metadata / build / dependency changes visible to installers.
+
+## Why
+
+Context a reader needs for the headline change. Omit for small releases.
+
+## Downstream
+
+What dependents must do — e.g. bump their version floor — or "No action
+needed" when there is no API change. Omit if the project has no downstreams.
+
+## Internals
+
+- Coverage / tooling notes.
diff --git a/planning/index.py b/planning/index.py
