Skip to content

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

Open
chethanuk wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
chethanuk:fix/issue-753-add-readme-to-plans-folder
Open

docs: add plans/README.md documenting the plan-document convention (#753)#918
chethanuk wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
chethanuk:fix/issue-753-add-readme-to-plans-folder

Conversation

@chethanuk

Copy link
Copy Markdown

📋 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/

`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 NVIDIA-NeMo#753

Signed-off-by: ChethanUK <chethanuk@outlook.com>
@chethanuk
chethanuk requested a review from a team as a code owner September 5, 2026 04:51
@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:


I have read the DCO document and I hereby sign the DCO.


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

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

greptile-apps Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This documentation-only PR establishes a top-level guide for development plans and makes it discoverable from the agent entry point.

  • Documents the boundaries between planning artifacts, architecture references, published Fern content, and documentation support files.
  • Describes existing naming, document, asset, and lifecycle conventions.
  • Accurately summarizes the repository’s plans-only review process.

Confidence Score: 5/5

The PR appears safe to merge with no actionable correctness, documentation, or repository-rule issues identified.

The documented conventions agree with the cited repository files and workflows, and all added links resolve.

Important Files Changed

Filename Overview
AGENTS.md Adds a valid link directing development agents to the new planning convention.
plans/README.md Documents repository planning conventions with accurate paths, examples, workflow behavior, and review guidance.

Reviews (1): Last reviewed commit: "docs: add plans/README.md documenting th..." | Re-trigger Greptile

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add README to plans/ folder

1 participant