From 228527b806e33ea92e0af19debd7fc616bfe3f6f Mon Sep 17 00:00:00 2001 From: ChethanUK Date: Sat, 5 Sep 2026 02:07:19 +0200 Subject: [PATCH] docs: add plans/README.md documenting the plan-document convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `plans/` holds 16 directories and no top-level file, so the only written statement of the convention is one clause in CONTRIBUTING.md. That clause is already narrower than the tree it governs — three directories are named workstreams rather than issue numbers, and two key off a PR number — and AGENTS.md, the agent entry point, never mentions plans at all. Add plans/README.md covering what the directory is (development planning artifacts, never published to the docs site), the plans/ vs architecture/ vs fern/ vs docs/ boundary, both live naming conventions, the document shape as observed, where assets go, and how a plans-only PR is reviewed per .agents/recipes/pr-review/recipe.md. Point AGENTS.md at it with one line, matching the three sentences already there. CONTRIBUTING.md is deliberately unchanged: GitHub renders a directory's README.md, so its relative link and the Fern copy's absolute one both land on the new file without an edit. Refs #753 Signed-off-by: ChethanUK --- AGENTS.md | 1 + plans/README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 plans/README.md diff --git a/AGENTS.md b/AGENTS.md index c9c3b4c43..434a68e5f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,3 +54,4 @@ make perf-import CLEAN=1 # profile import time (run after adding heavy deps) For full setup, testing, and workflow details see [DEVELOPMENT.md](DEVELOPMENT.md). For code style, naming, and import conventions see [STYLEGUIDE.md](STYLEGUIDE.md). For deeper dives into specific subsystems see [`architecture/`](architecture/). +For planning artifacts and the plan-document convention see [`plans/`](plans/). diff --git a/plans/README.md b/plans/README.md new file mode 100644 index 000000000..846534da0 --- /dev/null +++ b/plans/README.md @@ -0,0 +1,86 @@ +# Plans + +Development planning artifacts. Each subdirectory holds the point-in-time design documents +written before non-trivial work started — the approach, the trade-offs weighed, the affected +subsystems, and the delivery sequence. [`CONTRIBUTING.md`](../CONTRIBUTING.md) asks for one of +these before building anything non-trivial. + +These are **not user documentation and are never published**. [`fern/docs.yml`](../fern/docs.yml) +declares a single version source and all of it lives under `fern/versions/latest/pages/`; nothing +in `plans/` is reachable from the docs site. Read a plan as a record of what the author intended +at the time, not as a description of what the code does today. + +## Where a document belongs + +| Directory | Holds | Describes | +| --- | --- | --- | +| `plans/` | Design documents written before the work | Work not yet built | +| [`architecture/`](../architecture/) | [`overview.md`](../architecture/overview.md) plus nine subsystem documents | Shipped code | +| `fern/versions/latest/pages/**` | Published product documentation | What users are told | +| [`docs/`](../docs/) | Support files consumed by the Fern build (see [`docs/README.md`](../docs/README.md)) | Not prose | + +If a plan's content has shipped and readers need it to understand the running system, it belongs +in `architecture/`, not here. + +## Naming + +Use `plans//`, no zero padding — `plans/790/`, not `plans/0790/`. One directory per +plan, so supporting media sits beside the document it belongs to. + +`plans//` is equally current for work with no single tracking issue. +`workflow-chaining/`, `check-models/`, and `remote-filesystem-seeds/` are all named this way and +all postdate the numbered convention. + +Two directories — `299/` and `788/` — key off the implementing **pull request** number, because +the plan landed in the same change as the code. Prefer the issue number for new plans. + +## Document shape + +Observed across the existing plans, not a schema to conform to: + +- Optional YAML frontmatter: `date`, `authors`, and sometimes `status` or `issue`. The handful of + documents that set `status:` use it loosely (`draft`, `proposal`, `in-progress`) — read it as an + author's note, not as a lifecycle the repository enforces. +- A `# Plan: ` heading. Most primary documents use it. +- A body that runs Summary or Problem → Motivation → Goals → Non-goals → Design. + [`790/engine-native-record-selection.md`](790/engine-native-record-selection.md) and + [`518/pr-hygiene-plan.md`](518/pr-hygiene-plan.md) are good references. +- `path:line` citations when pointing at code, so a reader can check the claim. +- kebab-case filenames. `392/refactor_managed_personas_plan.md` is the one snake_case holdout. + +A plan that grows past a single document gets an index — see +[`645/README.md`](645/README.md), where a `README.md` fronts the sibling documents and links each +by audience. + +## Assets + +Diagrams and images go beside the document, or in an `assets/` subdirectory +([`396/assets/`](396/assets/)). Both are in use. + +For generated diagrams the source file is authoritative. `645/` states the rule for its PlantUML +diagrams and it applies generally: a change to the source must regenerate the images in the same +diff, or say explicitly why rendering was unavailable. + +## For agents + +Keep plans factual. Link the issues and pull requests the plan relates to, cite code by `path:line` +rather than paraphrasing it, and name the open questions instead of resolving them by assumption. +Do not write user-facing prose here. + +Plans are point-in-time and nothing refreshes them automatically — +`.github/workflows/agentic-ci-daily.yml` excludes `plans/` from the paths its docs auto-fix job is +allowed to touch. When work changes shape, update the plan or supersede it in the same pull request +that changes the work. A plan left describing an approach that was abandoned is worse than no plan. + +### How a plan PR is reviewed + +Per [`.agents/recipes/pr-review/recipe.md`](../.agents/recipes/pr-review/recipe.md), a pull request +that only touches `plans/` is reviewed on four things: + +1. **Completeness** — gaps, missing phases. +2. **Feasibility** — can the proposed approach actually be built. +3. **Alignment** — consistent with [`AGENTS.md`](../AGENTS.md) and the existing + [`architecture/`](../architecture/) documents. +4. **Open questions** — are the unknowns identified rather than glossed over. + +Linting and code-style checks are skipped.