Skip to content

Add README to plans/ folder #753

@johnnygreco

Description

@johnnygreco

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions