chore: rework planning conventions; add docs landing/comparison spec + plan

.gitignore

@@ -19,5 +19,4 @@ dist/
 .python-version
 .venv
 uv.lock
-plan.md
 /site/

CLAUDE.md

@@ -17,7 +17,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Workflow
 
-Per-feature: 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. Slugs are kebab-case descriptions, not story IDs.
+Per-feature: brainstorming → spec in `planning/active/YYYY-MM-DD-<slug>-design.md` → writing-plans → plan in `planning/active/YYYY-MM-DD-<slug>-plan.md` → executing-plans / subagent-driven-development → requesting-code-review → finishing-a-development-branch. Slugs are kebab-case descriptions, not story IDs. On merge, the pair moves to `planning/archived/` with `status: shipped`, `pr:`, and `outcome:` filled in the frontmatter. See [`planning/README.md`](planning/README.md) for the current index and [`planning/_templates/`](planning/_templates/) for copy-and-fill starting points.
+
+**Spec** captures the *thinking* — why we are doing this, what the design is, what trade-offs were considered, what is out of scope. Written before code; rarely revised after merge. **Plan** captures the *sequencing* — the ordered checklist of tasks an executor (human or agent) walks. References the spec for the "why"; never re-explains it. **`planning/architecture/`** captures the *invariants* of shipped systems by promoting the relevant parts of a spec after merge. A plan paragraph that would still read correctly with all task numbers and checkboxes removed is design content and belongs in the spec.
 
 ## Architecture
 

planning/README.md

@@ -0,0 +1,48 @@
+# Planning
+
+Specs and plans for `faststream-outbox` changes. See
+[CLAUDE.md](../CLAUDE.md#workflow) for the per-feature workflow.
+
+Each change is a paired `*-design.md` + `*-plan.md`. Both halves live
+together in `active/` while in flight; both move to `archived/` when the
+implementing PR merges. Frontmatter records `status`, `pr`, and
+`outcome`. See [`_templates/`](_templates/) for copy-and-fill starting
+points.
+
+## Active
+
+- **[docs-landing-and-comparison](active/2026-06-10-docs-landing-and-comparison-design.md)**
+  — Rewrite docs landing, reshape nav into Concepts/Guides/Reference,
+  add a Comparison page.
+- **[planning-conventions](active/2026-06-10-planning-conventions-design.md)**
+  — This restructure. Codify the spec/plan boundary, add
+  `active/`/`archived/`/`_templates/`, migrate the existing pairs.
+
+## Archived (shipped)
+
+- **[drain-test-flaky-fetch-observation](archived/2026-06-09-drain-test-flaky-fetch-observation-design.md)**
+  (#48, 2026-06-10) — Drain test waits via the `fetched` recorder
+  instead of an SQL poll, killing a 3.14 coverage flake.
+- **[mkdocs-github-pages](archived/2026-06-09-mkdocs-github-pages-design.md)**
+  (#45, 2026-06-09) — Docs hosting moves from Read the Docs to GitHub
+  Pages on `faststream-outbox.modern-python.org`.
+- **[foreign-broker-relay](archived/2026-06-04-foreign-broker-relay-design.md)**
+  (#44, 2026-06-05) — `OutboxSubscriber` officially supports the
+  FastStream-native decorator relay to Kafka/Rabbit/NATS/Redis with
+  three guardrails.
+- **[faststream-0.7.1-testbroker-typing](archived/2026-06-04-faststream-0.7.1-testbroker-typing-design.md)**
+  (#43, 2026-06-04) — Adopt FastStream 0.7.1's `TestBroker[Broker,
+  EnterType]` typing fix; drop two `# ty: ignore` directives.
+- **[faststream-0.7-migration](archived/2026-06-03-faststream-0.7-migration-design.md)**
+  (#42, 2026-06-03) — Migrate to `faststream>=0.7,<0.8`; fix mechanical
+  break points; drop per-call `middlewares=` kwarg.
+- **[all-extra-and-planning-dir](archived/2026-06-03-all-extra-and-planning-dir-design.md)**
+  (#41, 2026-06-03) — Add `faststream-outbox[all]` aggregate extra;
+  bootstrap the `planning/` directory itself.
+
+## Other
+
+- **[architecture/](architecture/)** — deep-dive reference for shipped
+  invariants (relay, timers, DLQ, drain, metrics, test broker).
+- **[lint-suppressions.md](lint-suppressions.md)** — audit of `noqa` /
+  `ty: ignore` directives and why each one stays.

planning/_templates/design.md

@@ -0,0 +1,55 @@
+---
+status: draft
+date: YYYY-MM-DD
+slug: my-change
+supersedes: null
+superseded_by: null
+pr: null
+outcome: null
+---
+
+# 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.

planning/_templates/plan.md

@@ -0,0 +1,56 @@
+---
+status: draft
+date: YYYY-MM-DD
+slug: my-change
+spec: my-change
+pr: null
+---
+
+# <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:** [`planning/active/YYYY-MM-DD-my-change-design.md`](./YYYY-MM-DD-my-change-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>
+
+  Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+  ```
+
+---
+
+### Task 2: ...