docs: add plans/README.md documenting the plan-document convention (#753)

[chethanuk]

📋 Summary

plans/ has 16 directories and no top-level file explaining what they are, so the only written
statement of the convention is one clause in CONTRIBUTING.md ("create a plan document at
plans/<issue-number>/") — already narrower than the tree it governs, and never mentioned in
AGENTS.md, the agent entry point. Adds plans/README.md documenting the structure as it
actually exists, and points AGENTS.md at it.

🔗 Related Issue

Closes #753

🔄 Changes

• Add plans/README.md: 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 (plans/<issue-number>/ and plans/<workstream-name>/), the
  document shape as observed, where assets go, and how a plans-only PR is reviewed per
  .agents/recipes/pr-review/recipe.md.
• Add one line to AGENTS.md pointing at plans/, matching the three sentences already there.
• CONTRIBUTING.md is intentionally unchanged — GitHub renders a directory's README.md, so
  its existing relative link (and the Fern copy's absolute one) already land on the new file.

🧪 Testing

• make test — N/A, documentation-only change
• Unit tests added/updated — N/A, no executable path in this diff; plans/ has no test
  coverage and the repo has no markdown linter
• E2E tests added/updated — N/A
• uvx pre-commit run --files plans/README.md AGENTS.md passes (trailing-whitespace,
  end-of-file-fixer, mixed-line-ending)
• Every relative link in plans/README.md resolved by hand against git ls-tree origin/main plans/

✅ Checklist

• Follows commit message conventions
• Commits are signed off (DCO)
• Architecture docs updated — N/A, this change doesn't touch architecture/

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[github-actions]

Linked Issue Check

Issue #753 has not been triaged yet. A maintainer needs to review
the issue and add the triaged label for this check to pass.

You can continue working on the PR in the meantime. The check will
re-run automatically once the issue is triaged.

[greptile-apps]

Confidence Score: 5/5

The documentation-only changes appear safe to merge.

Summary

• Defines where plans belong and how new plan directories are named.
• Describes recommended document structure, asset placement, and lifecycle.
• Records the review criteria for plans-only pull requests.

_{Reviews (2) · Last reviewed commit: "docs: narrow plans/README.md to plans-sp..."}

[nabinchha]

@andreatnvidia wdyt about standardizing to plans/<issue-number>/? For existing plans following plans/<workstream-name>/ format, can we turn these into the former?

[nabinchha]

Thanks for putting this together, @chethanuk—the new index is a useful addition, and the links make the planning archive much easier to discover.

Summary

This adds a top-level guide for plans/ and links it from AGENTS.md. The broad intent matches #753, but the document-placement section expands a plans guide into an inaccurate repository-wide taxonomy; I think it should be narrowed before it becomes agent-facing guidance.

Findings

Warnings — Worth addressing

plans/README.md:13 — Keep this boundary specific to plans rather than defining a global document taxonomy

• What: “Where a document belongs” attempts to classify documentation across the repository, which is broader than this README needs and produces misleading rules. In particular, plans are described as only covering “Work not yet built” even though completed plans remain as point-in-time records, while docs/ is labeled “Not prose” even though docs/notebook_source/*.py contains authored Markdown for user-facing tutorials. At the same time, the table omits .scratch/, despite #753 explicitly asking where temporary notes belong.
• Why: Agents need to answer the narrower question “Does this belong in plans/?” A partial global taxonomy creates new repository policy, invites future drift, and can send contributors to the wrong source location.
• Suggestion: Replace the table with a short “What belongs here” section that distinguishes only the adjacent cases needed for that decision: plans/ for the design and shipped outcome of a specific body of work, architecture/ for the maintained description of the current system, fern/ for user-facing product documentation, and .scratch/ for temporary uncommitted notes. There is no need for this README to classify docs/, root policy files, or every other document type.

plans/README.md:27 — Standardize the plan-directory naming convention

• What: CONTRIBUTING.md currently directs every non-trivial change to plans/<issue-number>/, while this README declares plans/<workstream-name>/ “equally current” based on three existing directories. That turns historical exceptions into a second supported convention without defining an objective boundary between the two.
• Why: Agents can choose different paths for equivalent work, making plans harder to locate and leaving the repository with two conventions that will be increasingly costly to reconcile. It also makes the new guidance disagree with the existing contributor workflow.
• Suggestion: Could we standardize on plans/<issue-number>/ for new plans and map the existing workstream directories to their tracking issues? Before renaming those directories, audit inbound repository links so references can be updated in the same change. If named workstreams must remain supported, update CONTRIBUTING.md too and define a concrete exception rather than calling both forms equally current.

plans/README.md:70 — Clarify that plans record what a change shipped, not how the system works today

• What: The introduction frames a plan as what its author intended before work started, while this section says to update or supersede it when implementation changes. Neither statement captures the full lifecycle: a plan should evolve with its implementation and accurately record what that body of work ultimately shipped, then remain as the historical record of that change.
• Why: Without that distinction, an agent may leave a plan describing an abandoned design, freeze it before the implementation is reconciled, or later treat an accurate shipped plan as the current source of truth. A subsequent plan can legitimately alter the same behavior, so even a finalized plan cannot tell readers how the system works now.
• Suggestion: Define the lifecycle explicitly: draft and review the plan before implementation; keep it aligned as the work is built; reconcile it with the delivered behavior before the implementing work is considered complete; then preserve it as a historical record tied to that issue or pull request. Later changes should get their own plans. Current behavior remains authoritative in the code and its maintained architecture/ and fern/ documentation, not in any individual plan.

Suggestions — Take it or leave it

plans/README.md:60 — A directory-local asset rule is presented as repository-wide policy

• What: The README says the PlantUML source rule from plans/645/ “applies generally,” but that source only establishes the rule for its own diagrams. No existing repository-level guidance makes it a general convention.
• Why: This PR is meant to document observed practice, so silently promoting one plan's local instruction into a global requirement blurs the line between describing conventions and creating new policy.
• Suggestion: Either state plainly that this README is establishing a new convention for generated assets, or limit the claim to plans/645/ and give general advice without citing that local rule as authority.

plans/README.md:18 — Avoid a census that will become stale

• What: The README records transient inventory facts such as “nine subsystem documents,” “two directories,” and “the one snake_case holdout,” along with relative chronology claims about named workstreams.
• Why: None of these counts is needed to explain the convention, and each becomes incorrect as soon as another document or plan is added. This is especially fragile in a README that says automated documentation maintenance excludes plans/.
• Suggestion: State the convention and keep one or two examples, but remove exact counts, exhaustive exception lists, and chronology claims unless they materially affect where a new plan belongs.

What Looks Good

• Linking plans/ from AGENTS.md gives both humans and agents a clear discovery path.
• The warning that plans are not product documentation or a reliable description of current code is important and worth preserving.
• The concrete examples and relative links are useful; all added relative-link targets resolve in the PR checkout.

Verdict

Needs changes — Replace the broad document taxonomy with focused guidance about what belongs in plans/, choose a plan-directory naming convention that agrees with CONTRIBUTING.md, and clarify that plans are reconciled with what their work shipped but never become the source of truth for current behavior. The asset-policy and inventory points are optional cleanup.

---

This review was generated by an AI assistant.