[codex] Add devkit manifest and selection report guidance

.cursor/rules/repo-conventions.mdc

@@ -3,4 +3,7 @@ description: Repository conventions for agent edits
 alwaysApply: true
 ---
 
-Read `AGENTS.md` before changing files. Prefer repo scripts over ad hoc commands. Keep edits small, update `.env.example` when adding config, and update `.context/` only for durable operational knowledge.
+Read `AGENTS.md` before changing files. Prefer repo scripts over ad hoc
+commands. Keep edits small, update `.env.example` when adding config, and keep
+`.context/` as gitignored workspace-local scratch. Promote durable knowledge
+into tracked docs instead of committing `.context/`.

AGENTS.md

@@ -24,9 +24,14 @@
 
 ## Repository Shape
 
-- `stacks/typescript`: framework-neutral Bun/TypeScript conventions.
-- `scripts`: stable project entrypoints.
+- `AGENTS.md`: canonical agent operating instructions.
+- `MANIFEST.md`: file inventory and template-selection checklist.
+- `DECISIONS.md`: decision authority for devkit topology and policy.
 - `docs`: contributor-facing documentation.
+- `extras`: optional workflows, deployment examples, and support add-ons.
+- `scripts`: stable project entrypoints.
+- `skills`: optional project-local agent skills.
+- `stacks/typescript`: framework-neutral Bun/TypeScript conventions.
 - `stacks/python`: optional Python API/shared-package workspace.
 - `stacks/ruby`: optional Ruby/Rails/Rack workspace conventions.
 - `.context`: gitignored workspace-local scratch for Conductor and agents.
@@ -46,6 +51,10 @@
 ## Editing Rules
 
 - Read target files, callers, exports, tests, and obvious shared utilities before editing.
+- When applying this devkit or cleaning up a GitHub-template-generated repo,
+  read `MANIFEST.md` and produce a selection report before editing. Cover every
+  top-level path in this devkit and the target repo with an adopt, adapt, skip,
+  delete, or defer decision and a one-line reason.
 - Keep edits surgical.
 - Do not reformat unrelated files.
 - Add or update tests when behavior changes.

MANIFEST.md

@@ -0,0 +1,103 @@
+# 508 Devkit Manifest
+
+This manifest is the agent-facing inventory for template selection. Use it to
+walk the repo before copying or deleting files.
+
+Disposition tags:
+
+- `keep-by-default`: broad repo hygiene that usually survives, with project
+  edits.
+- `select-per-stack`: keep only when the target language/runtime or package
+  manager calls for it.
+- `opt-in`: keep only after confirming the workflow, owner, permission,
+  infrastructure, or deployment need.
+- `devkit-only-delete-in-generated-repos`: design history or devkit interface
+  content that should not remain in a generated product repo unless explicitly
+  repurposed.
+
+## Top-Level Inventory
+
+| Path | Disposition | Purpose |
+| --- | --- | --- |
+| `.cursor/rules/` | `keep-by-default` | Cursor agent rule pointing to canonical repo instructions. |
+| `.dockerignore` | `keep-by-default` | Keeps Docker build contexts small and secret-safe. |
+| `.editorconfig` | `keep-by-default` | Cross-editor formatting baseline. |
+| `.env.example` | `keep-by-default` | Environment contract template; rewrite for the target app. |
+| `.github/` | `keep-by-default` | Small issue, PR, and CI defaults when the repo uses GitHub. |
+| `.gitignore` | `keep-by-default` | Ignore rules for local state, dependencies, caches, and `.context/`. |
+| `.pre-commit-config.yaml` | `opt-in` | Optional local hook runner for repos that want pre-commit. |
+| `.sops.yaml.example` | `opt-in` | Optional SOPS starter for repos with encrypted tracked files. |
+| `.worktreeinclude` | `keep-by-default` | Allowlist of ignored local config copied into sibling worktrees. |
+| `AGENTS.md` | `keep-by-default` | Canonical agent operating instructions. |
+| `CLAUDE.md` | `keep-by-default` | Claude Code pointer to canonical instructions. |
+| `CONTRIBUTING.md` | `keep-by-default` | Contributor workflow baseline. |
+| `DECISIONS.md` | `keep-by-default` | Devkit constitution; rewrite into project decisions after generation. |
+| `LICENSE` | `keep-by-default` | Repository license; replace if the target project uses another license. |
+| `MANIFEST.md` | `keep-by-default` | This inventory and template-selection checklist. |
+| `README.md` | `keep-by-default` | Project overview and quickstart; rewrite for the target project. |
+| `SECURITY.md` | `keep-by-default` | Vulnerability reporting and security expectations. |
+| `biome.json` | `select-per-stack` | Biome formatter/linter config for JavaScript or TypeScript projects. |
+| `bun.lock` | `select-per-stack` | Bun lockfile for the root TypeScript workspace example. |
+| `bunfig.toml` | `select-per-stack` | Bun install policy, including dependency cooldowns. |
+| `compose.yml` | `opt-in` | Local infrastructure examples such as Postgres and Redis. |
+| `docker-compose.yml` | `opt-in` | Compatibility wrapper for `compose.yml`. |
+| `docs/` | mixed | Durable documentation; see the docs inventory below. |
+| `extras/` | `opt-in` | Optional workflows, Dockerfiles, dev containers, storage, and GitHub add-ons. |
+| `llms.txt` | `keep-by-default` | Short index for agents and LLM-based tooling. |
+| `package.json` | `select-per-stack` | Root Bun/TypeScript scripts and dependency metadata. |
+| `pnpm-workspace.example.yaml` | `select-per-stack` | pnpm alternative root workspace policy. |
+| `renovate.json` | `keep-by-default` | Dependency update policy with cooldown-aware scheduling. |
+| `scripts/` | `keep-by-default` | Stable human/agent entrypoints for dev, test, lint, ports, and Compose. |
+| `skills/` | `opt-in` | Project-local agent skills; usually remove from product repos unless maintained. |
+| `stacks/` | `select-per-stack` | Language/runtime convention packs. |
+
+## Docs Inventory
+
+| Path | Disposition | Purpose |
+| --- | --- | --- |
+| `docs/agent-walkthrough.md` | `devkit-only-delete-in-generated-repos` | Expected agent behavior when applying this devkit. |
+| `docs/deployment.md` | `keep-by-default` | Deployment documentation placeholder and decision prompts. |
+| `docs/development.md` | `keep-by-default` | Local development runbook and script conventions. |
+| `docs/frontend.md` | `keep-by-default` | Framework-neutral frontend policy. |
+| `docs/github-template.md` | `devkit-only-delete-in-generated-repos` | Cleanup checklist for GitHub-template-generated repos. |
+| `docs/github-workflows.md` | `keep-by-default` | GitHub workflow and template guidance. |
+| `docs/interfaces.md` | `keep-by-default` | Runtime and boundary contract guidance. |
+| `docs/observability.md` | `keep-by-default` | Logging, metrics, traces, and incident context guidance. |
+| `docs/pattern-report.md` | `devkit-only-delete-in-generated-repos` | Design-history synthesis from source repos. |
+| `docs/secrets.md` | `keep-by-default` | Secret handling and environment boundary guidance. |
+| `docs/supply-chain.md` | `keep-by-default` | Canonical dependency cooldown and locked-install policy. |
+| `docs/template-proposal.md` | `devkit-only-delete-in-generated-repos` | Design rationale for this template source. |
+| `docs/tooling.md` | `keep-by-default` | Tooling policy and command conventions. |
+
+## Stack Inventory
+
+| Path | Disposition | Purpose |
+| --- | --- | --- |
+| `stacks/typescript/` | `select-per-stack` | Framework-neutral Bun/TypeScript conventions, Biome, Vitest, and Drizzle examples. |
+| `stacks/typescript/pnpm/` | `select-per-stack` | pnpm root files and CI fragment for pnpm workspaces. |
+| `stacks/python/` | `select-per-stack` | Optional uv Python API/shared-package workspace with Ruff, MyPy, Pytest, Pydantic, and Alembic examples. |
+| `stacks/ruby/` | `select-per-stack` | Optional Ruby/Rails/Rack conventions with Bundler cooldown guidance. |
+
+## Extras Inventory
+
+| Path | Disposition | Purpose |
+| --- | --- | --- |
+| `extras/dev-scripts/` | `opt-in` | JS-first variants of root dev and worktree-port scripts. |
+| `extras/devcontainer/` | `opt-in` | Dev container starter for teams that want containerized development. |
+| `extras/dockerfiles/` | `opt-in` | Example deployment Dockerfiles for API, worker, and web services. |
+| `extras/github/` | `opt-in` | CODEOWNERS, discussion template, Gitleaks, and Dependency Review examples. |
+| `extras/object-storage/` | `opt-in` | MinIO Compose example for local S3-compatible storage. |
+| `extras/todo-to-issue/` | `opt-in` | GitHub workflow for turning TODO comments into issues. |
+
+## Selection Report
+
+Before editing a generated repo or normalizing a target repo, produce a
+selection report with one row for every top-level path in this devkit and every
+top-level path in the target repo:
+
+| Path | Source | Decision | Reason |
+| --- | --- | --- | --- |
+| `example/path` | devkit or target | adopt, adapt, skip, delete, or defer | One concrete reason. |
+
+The report is intentionally mechanical. It makes skipped files explicit and
+keeps the first PR focused on selection before product feature work.

README.md

@@ -1,6 +1,6 @@
 # 508 Devkit
 
-Last reviewed: 2026-06-03
+Last reviewed: 2026-07-05
 
 Opinionated sane defaults and conventions for software projects.
 
@@ -51,9 +51,11 @@ Recommended first prompt in the generated repo:
 
 ```text
 This repository was generated from 508 Devkit. Do a template selection pass:
-inspect the product goal and existing files, keep only the root hygiene, stacks,
-extras, docs, and workflows that fit this project, delete the rest, rename all
-devkit/example identifiers, and run the narrowest relevant checks.
+use MANIFEST.md to produce a selection report before editing, covering every
+top-level path in the devkit and this repo with adopt/adapt/skip/delete/defer
+and a one-line reason. Then keep only the root hygiene, stacks, extras, docs,
+and workflows that fit this project, delete the rest, rename all devkit/example
+identifiers, and run the narrowest relevant checks.
 ```
 
 See `docs/github-template.md` for the cleanup checklist.
@@ -79,6 +81,9 @@ Run it as /508-devkit, /bootstrap-project, or whatever command name your agent c
 Expected agent behavior:
 
 - Inspect the target repo before editing.
+- Use `MANIFEST.md` to produce a selection report before editing. Cover every
+  top-level path in the devkit and the target repo with an adopt, adapt, skip,
+  delete, or defer decision and a one-line reason.
 - Ask about product shape, deployment target, data stores, and language/runtime choices when those are unclear.
 - Automatically pick up existing conventions when the repo already has them.
 - Prefer the devkit defaults for new projects unless there is a clear reason to choose a stack or extra.
@@ -95,20 +100,25 @@ bun install --frozen-lockfile
 ## Layout
 
 ```text
-stacks          Language/runtime conventions such as TypeScript and Python
-scripts         Stable human/agent entrypoints
-docs            Durable project documentation
-extras          Optional workflow, deployment, and support add-ons
+AGENTS.md      Canonical agent operating instructions
+MANIFEST.md    File inventory and template-selection checklist
+DECISIONS.md   Decision authority for devkit topology and policy
+docs           Durable project documentation
+extras         Optional workflow, deployment, and support add-ons
+scripts        Stable human/agent entrypoints
+skills         Optional project-local agent skills
+stacks         Language/runtime convention packs
 ```
 
 ## Read Next
 
 1. Read `DECISIONS.md`.
-2. Read `docs/pattern-report.md`.
-3. Read `docs/tooling.md`.
-4. Read `docs/template-proposal.md`.
-5. Read `docs/github-template.md` when starting from GitHub's template button.
-6. Read `docs/frontend.md`.
+2. Read `MANIFEST.md`.
+3. Read `docs/github-template.md` when starting from GitHub's template button.
+4. Read `docs/tooling.md`.
+5. Read `docs/frontend.md`.
+6. Read `docs/pattern-report.md` and `docs/template-proposal.md` when you need
+   devkit design history.
 7. Copy `.env.example` to `.env`.
 8. Run `./scripts/worktree-ports.sh env`.
 9. Run `./scripts/docker-compose.sh up -d postgres redis`.
@@ -172,10 +182,10 @@ is a template source, not an installable preset or final generated app.
 
 Keep root defaults for most new projects: shell wrappers, shell worktree ports,
 and example Compose-managed infra. Select language/runtime stacks such as
-`stacks/typescript/`, `stacks/python/`, future `stacks/go/`, or future
-`stacks/rust/` based on the target project. Treat stack files as conventions to
-adapt, not product code to copy blindly. If this repo was used through
-GitHub's template button, do the same selection and pruning before feature work.
+`stacks/typescript/`, `stacks/python/`, or `stacks/ruby/` based on the target
+project. Treat stack files as conventions to adapt, not product code to copy
+blindly. If this repo was used through GitHub's template button, do the same
+selection and pruning before feature work.
 
 ## Agent Notes
 

docs/agent-walkthrough.md

@@ -13,23 +13,29 @@ For a repository generated from GitHub's `Use this template` button:
 
 ```text
 This repository was generated from 508 Devkit. Do a template selection pass:
-inspect the product goal and existing files, keep only the root hygiene, stacks,
-extras, docs, and workflows that fit this project, delete the rest, rename all
-devkit/example identifiers, and run the narrowest relevant checks.
+use MANIFEST.md to produce a selection report before editing, covering every
+top-level path in the devkit and this repo with adopt/adapt/skip/delete/defer
+and a one-line reason. Then keep only the root hygiene, stacks, extras, docs,
+and workflows that fit this project, delete the rest, rename all devkit/example
+identifiers, and run the narrowest relevant checks.
 ```
 
 ## Expected Agent Flow
 
 1. Inspect the target repo before editing.
-2. Read existing `AGENTS.md`, package manifests, lockfiles, workflows, Compose files, scripts, and docs.
-3. Decide which devkit conventions already exist.
-4. Ask questions only when the product shape or stack cannot be inferred safely.
-5. Apply the smallest useful set of files.
-6. If the repo was generated from the GitHub template, delete unselected stacks,
+2. Read `DECISIONS.md`, `MANIFEST.md`, and existing `AGENTS.md`, package
+   manifests, lockfiles, workflows, Compose files, scripts, and docs.
+3. Produce a selection report before editing. Cover every top-level path in the
+   devkit and target repo with an adopt, adapt, skip, delete, or defer decision
+   and a one-line reason.
+4. Decide which devkit conventions already exist.
+5. Ask questions only when the product shape or stack cannot be inferred safely.
+6. Apply the smallest useful set of files.
+7. If the repo was generated from the GitHub template, delete unselected stacks,
    extras, workflows, example app names, and docs that do not describe the
    target project.
-7. Run focused validation.
-8. Summarize what was adopted, skipped, and why.
+8. Run focused validation.
+9. Summarize what was adopted, skipped, and why.
 
 ## Example Questions
 

docs/github-template.md

@@ -9,13 +9,16 @@ bootstrap workspace, not as the final project shape.
 
 1. Create a new repository from the GitHub `Use this template` button.
 2. Make the first project PR a template selection pass.
-3. Keep the root hygiene files that apply to most software repos.
-4. Select only the language stacks and extras that match the project.
-5. Delete unselected examples, placeholder workflows, and docs that no longer
+3. Use `MANIFEST.md` to produce a selection report before editing. Cover every
+   top-level path in the devkit and generated repo with an adopt, adapt, skip,
+   delete, or defer decision and a one-line reason.
+4. Keep the root hygiene files that apply to most software repos.
+5. Select only the language stacks and extras that match the project.
+6. Delete unselected examples, placeholder workflows, and docs that no longer
    describe the project.
-6. Rename package names, env defaults, service names, and documentation from
+7. Rename package names, env defaults, service names, and documentation from
    devkit examples to the real product.
-7. Run the narrowest relevant checks before building product features.
+8. Run the narrowest relevant checks before building product features.
 
 The selection pass is part of using the template. Do not start feature work
 while the repository still contains irrelevant stacks or optional extras.
@@ -66,7 +69,9 @@ Use this prompt immediately after creating a repository from the template:
 
 ```text
 This repository was generated from 508 Devkit. Do a template selection pass:
-inspect the product goal and existing files, keep only the root hygiene, stacks,
-extras, docs, and workflows that fit this project, delete the rest, rename all
-devkit/example identifiers, and run the narrowest relevant checks.
+use MANIFEST.md to produce a selection report before editing, covering every
+top-level path in the devkit and this repo with adopt/adapt/skip/delete/defer
+and a one-line reason. Then keep only the root hygiene, stacks, extras, docs,
+and workflows that fit this project, delete the rest, rename all devkit/example
+identifiers, and run the narrowest relevant checks.
 ```

docs/template-proposal.md

@@ -30,9 +30,8 @@ It is optimized for:
 ├── .github/workflows/
 ├── stacks/
 │   ├── python/
-│   ├── typescript/
-│   ├── go/
-│   └── rust/
+│   ├── ruby/
+│   └── typescript/
 ├── extras/
 ├── docs/
 └── scripts/

llms.txt

@@ -6,10 +6,13 @@
 
 - `README.md`: overview and quickstart.
 - `AGENTS.md`: agent operating instructions.
+- `DECISIONS.md`: decision authority for devkit topology and policy.
+- `MANIFEST.md`: file inventory and template-selection checklist.
 - `docs/pattern-report.md`: source patterns behind the scaffold.
 - `docs/template-proposal.md`: design rationale for included files.
 - `docs/frontend.md`: framework-neutral frontend policy.
 - `docs/github-workflows.md`: GitHub templates and workflow guidance.
+- `docs/github-template.md`: generated-repo cleanup checklist.
 - `docs/supply-chain.md`: dependency safety policy.
 
 ## Key Conventions
@@ -24,6 +27,8 @@
 - Use deterministic worktree ports from `scripts/worktree-ports.sh`.
 - Keep `.context/` gitignored and workspace-local; durable knowledge belongs in tracked docs.
 - Put language/runtime conventions in `stacks/` and opt-in add-ons in `extras/`.
+- Before applying the devkit, use `MANIFEST.md` to produce a selection report
+  covering every top-level path in the devkit and target repo.
 
 ## Validation