[codex] Add devkit manifest and selection report guidance

[michaelmwu]

Summary

• Add MANIFEST.md as an agent-facing inventory for template selection, with disposition tags for top-level paths, docs, stacks, and extras.
• Require a manifest-backed selection report before edits in the README, AGENTS instructions, bundled devkit skill, generated-repo checklist, and agent walkthrough.
• Fix concrete doc inconsistencies: Cursor .context/ guidance now matches repo policy, the layout maps include extras/ and skills/, DECISIONS.md is surfaced in llms.txt, and nonexistent Go/Rust stack entries are removed from the default tree.

Why

The repo already has strong policy, but agents can skim past repeated guidance. This change gives them one inventory to walk and a concrete pre-edit artifact that makes skipped files explicit during GitHub-template cleanup or target-repo normalization.

Validation

• bun install --frozen-lockfile
• ./scripts/lint.sh
• git diff --check

---

Note

Low Risk
Documentation and agent-instruction changes only; no runtime, security, or dependency behavior changes.

Overview
Introduces MANIFEST.md as the single agent-facing inventory for template selection, with disposition tags and tables for top-level paths, docs/, stacks/, and extras/, plus a selection report format (path, source, adopt/adapt/skip/delete/defer, reason).

Bootstrap workflow now requires that report before any edits when applying the devkit or cleaning a GitHub-template repo. That requirement is wired through AGENTS.md, README, docs/github-template.md, docs/agent-walkthrough.md, llms.txt, and skills/508-devkit/SKILL.md (updated prompts and reordered agent flow).

Doc alignment fixes: Cursor rules now match .context/ policy (gitignored scratch; durable knowledge in tracked docs). Layout/read-next guidance surfaces MANIFEST.md / DECISIONS.md, includes extras/ and skills/, and docs/template-proposal.md drops nonexistent Go/Rust stack entries in favor of ruby.

^{Reviewed by Cursor Bugbot for commit b7dbff4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Clarified repository setup and editing guidance across the project docs.
  • Added a consistent step for reviewing and selecting which top-level items to keep, adapt, or remove during new repo setup or normalization.
  • Updated layout and template guidance to better reflect the recommended project structure and stack choices.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1398e845-3900-4203-a044-ef133df9948e

📥 Commits

Reviewing files that changed from the base of the PR and between 2fa0585 and b7dbff4.

📒 Files selected for processing (9)

• .cursor/rules/repo-conventions.mdc
• AGENTS.md
• MANIFEST.md
• README.md
• docs/agent-walkthrough.md
• docs/github-template.md
• docs/template-proposal.md
• llms.txt
• skills/508-devkit/SKILL.md

---

📝 Walkthrough

Walkthrough

This PR adds a populated MANIFEST.md inventory file and updates AGENTS.md, README.md, docs/agent-walkthrough.md, docs/github-template.md, docs/template-proposal.md, llms.txt, and skills/508-devkit/SKILL.md to require agents to generate a MANIFEST.md-based selection report (adopt/adapt/skip/delete/defer) covering every top-level path before editing. Also clarifies .context/ scratch conventions and narrows default stack listings to typescript/python/ruby.

Changes

Selection report workflow

Layer / File(s)	Summary
MANIFEST.md inventory and selection report contract MANIFEST.md	Adds disposition tags, top-level/docs/stacks/extras inventories, and a Selection Report section defining the required report structure.
AGENTS.md repository shape and editing rules AGENTS.md	Expands the Repository Shape inventory and adds a pre-edit requirement to generate a MANIFEST.md-based selection report.
README.md quickstart and normalization guidance README.md	Updates reviewed date, quickstart/normalize prompts to require a MANIFEST.md selection report, revises Layout/Read Next, and narrows stack guidance to typescript/python/ruby.
Agent walkthrough flow updates docs/agent-walkthrough.md	Adds selection-report requirement and rewrites Expected Agent Flow steps referencing DECISIONS.md/MANIFEST.md and pruning behavior.
GitHub template flow and prompt updates docs/github-template.md, docs/template-proposal.md	Updates Intended Flow and Agent Prompt text for the selection-report workflow; removes go/rust from default stacks tree.
llms.txt and SKILL.md workflow updates llms.txt, skills/508-devkit/SKILL.md	Adds MANIFEST.md/DECISIONS.md references and pre-application instruction; reorders SKILL.md workflow to inspect devkit inventory first and add a selection-report step.
Repo conventions scratch directory clarification .cursor/rules/repo-conventions.mdc	Clarifies .context/ as gitignored scratch, directing durable knowledge into tracked docs.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• 508-dev/508-devkit#6: Overlapping updates to the same GitHub-template/agent workflow documentation files (README.md, docs/agent-walkthrough.md, docs/github-template.md, docs/template-proposal.md, SKILL.md).

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a devkit manifest and selection report guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch michaelmwu/devkit-review-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}