From b7dbff4a34e38d4308b60cbae260ce029e56dc60 Mon Sep 17 00:00:00 2001 From: Michael Wu Date: Sun, 5 Jul 2026 23:06:27 -1000 Subject: [PATCH] Add devkit manifest and selection report guidance --- .cursor/rules/repo-conventions.mdc | 5 +- AGENTS.md | 13 +++- MANIFEST.md | 103 +++++++++++++++++++++++++++++ README.md | 44 +++++++----- docs/agent-walkthrough.md | 26 +++++--- docs/github-template.md | 21 +++--- docs/template-proposal.md | 5 +- llms.txt | 5 ++ skills/508-devkit/SKILL.md | 24 +++++-- 9 files changed, 198 insertions(+), 48 deletions(-) create mode 100644 MANIFEST.md diff --git a/.cursor/rules/repo-conventions.mdc b/.cursor/rules/repo-conventions.mdc index c8bfb08..cd2961c 100644 --- a/.cursor/rules/repo-conventions.mdc +++ b/.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/`. diff --git a/AGENTS.md b/AGENTS.md index e874053..492739f 100644 --- a/AGENTS.md +++ b/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. diff --git a/MANIFEST.md b/MANIFEST.md new file mode 100644 index 0000000..a2d9c0d --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 644e79e..4648d28 100644 --- a/README.md +++ b/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 diff --git a/docs/agent-walkthrough.md b/docs/agent-walkthrough.md index 98b09a8..11b769d 100644 --- a/docs/agent-walkthrough.md +++ b/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 diff --git a/docs/github-template.md b/docs/github-template.md index 0eae356..e3f4e8f 100644 --- a/docs/github-template.md +++ b/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. ``` diff --git a/docs/template-proposal.md b/docs/template-proposal.md index 5fbd1e3..112b506 100644 --- a/docs/template-proposal.md +++ b/docs/template-proposal.md @@ -30,9 +30,8 @@ It is optimized for: ├── .github/workflows/ ├── stacks/ │ ├── python/ -│ ├── typescript/ -│ ├── go/ -│ └── rust/ +│ ├── ruby/ +│ └── typescript/ ├── extras/ ├── docs/ └── scripts/ diff --git a/llms.txt b/llms.txt index a2190a9..97f0676 100644 --- a/llms.txt +++ b/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 diff --git a/skills/508-devkit/SKILL.md b/skills/508-devkit/SKILL.md index be7e6eb..a80149e 100644 --- a/skills/508-devkit/SKILL.md +++ b/skills/508-devkit/SKILL.md @@ -3,7 +3,7 @@ Use this skill when creating or normalizing a software project with 508 Devkit conventions. -Last reviewed: 2026-06-03 +Last reviewed: 2026-07-05 Preserve the devkit's topology and policy, but verify current versions, action SHAs, and API documentation before applying them to a target repo. @@ -28,7 +28,13 @@ example app, or design-history document. ## Workflow -1. Inspect the target repo first: +1. Inspect the devkit decision authority and inventory: + - `DECISIONS.md`. + - `MANIFEST.md`. + - `docs/supply-chain.md` when dependency policy is relevant. + - `docs/github-template.md` when the target repo was generated from the + GitHub template. +2. Inspect the target repo before editing: - `DECISIONS.md` when present. - `AGENTS.md`, `CLAUDE.md`, Cursor rules. - `pyproject.toml`, `uv.lock` when Python is present. @@ -39,7 +45,11 @@ example app, or design-history document. - `.github/workflows`. - `.env.example`. - `scripts/`. -2. Decide which devkit pieces apply. Do not infer a language, framework, +3. Produce a selection report before editing. It must include every top-level + path in the devkit and every top-level path in the target repo, with columns + for path, source, decision, and reason. Use decisions such as `adopt`, + `adapt`, `skip`, `delete`, and `defer`. +4. Decide which devkit pieces apply. Do not infer a language, framework, database, ORM, migration tool, object store, or package manager from the devkit alone. - Start with broadly useful repo hygiene: agent instructions, stable scripts, @@ -74,11 +84,11 @@ example app, or design-history document. graph-based vulnerability, license, or dependency-change reporting and has enabled the dependency graph. - Use SOPS only when encrypted tracked files are needed. -3. Copy or adapt files from the `508-devkit` repository. -4. Update names, package scopes, ports, and docs to fit the target project. -5. In GitHub-template-generated repos, delete unselected stacks, extras, +5. Copy or adapt files from the `508-devkit` repository. +6. Update names, package scopes, ports, and docs to fit the target project. +7. In GitHub-template-generated repos, delete unselected stacks, extras, workflows, example names, and docs before starting product feature work. -6. Run the narrowest relevant checks. +8. Run the narrowest relevant checks. ## Worktree And Docker Files