Context
The repository has a top-level plans/ directory with development planning artifacts organized by issue or initiative, for example plans/343/..., plans/645/..., and named workstream folders. There is not currently a top-level plans/README.md explaining what these files are or how humans and coding agents should use them.
Without that context, the folder can be mistaken for product documentation, architecture source of truth, or scratch space, and agents may add or update plans inconsistently.
Proposal
Add plans/README.md that explains:
- what the planning docs are and how they relate to GitHub issues, PRs, and implementation work
- the expected folder naming conventions, such as
plans/<issue-number>/... for issue-backed work and named workstream folders when appropriate
- what belongs in
plans/ versus product docs, architecture/, or temporary scratch notes
- guidance for agents: keep plans factual, link relevant issues and PRs, update stale plans when work changes, and avoid treating plans as user-facing documentation
- how to include supporting assets such as diagrams or images when a plan needs them
Acceptance criteria
- A top-level
plans/README.md exists.
- The README gives concise context for both human contributors and coding agents.
- It documents the current observed structure of the
plans/ directory.
- It clarifies that these are development planning artifacts, not product documentation.
- It includes enough guidance that future plans can be added consistently.
Context
The repository has a top-level
plans/directory with development planning artifacts organized by issue or initiative, for exampleplans/343/...,plans/645/..., and named workstream folders. There is not currently a top-levelplans/README.mdexplaining what these files are or how humans and coding agents should use them.Without that context, the folder can be mistaken for product documentation, architecture source of truth, or scratch space, and agents may add or update plans inconsistently.
Proposal
Add
plans/README.mdthat explains:plans/<issue-number>/...for issue-backed work and named workstream folders when appropriateplans/versus product docs,architecture/, or temporary scratch notesAcceptance criteria
plans/README.mdexists.plans/directory.