repo-standard

startup

Workflow

1. Find the profile. Read

   docs/repo-standard.md

   for the

   Profile:

   line. If the file is missing, generate it (see "Generate the checklist") and pick the profile with the user: web-app, service, cli-tool, bot, or content.
2. Run the audit. From the repo root:
   bash

   bash <path-to-this-skill>/scripts/audit.sh "<repo-root>"

   It prints PASS, FAIL, NA, JUDGE, DRIFT, and INFO lines for the deterministic checks.
3. Resolve the JUDGE items yourself against STANDARD.md: C9 (is the domain non-trivial enough to need a glossary?), CI2 (is the integration mode declared in AGENTS.md and followed?), S1 (is external input handled safely?). These need reading, not a grep.
4. Reconcile drift. If the audit prints DRIFT, the repo stamp is behind the current standard version. Re-evaluate the new items, update

   docs/repo-standard.md

   , and bump its

   Standard: vN

   and

   Last reconciled

   .
5. Report. Always end with a single results table so the repo's state is readable at a glance, whether or not it passed. One row per check the audit emitted (fold each resolved JUDGE into its row with the verdict). Columns:

   Status	ID	Check	Notes
   ✅ pass	C1	AGENTS.md with Commands
   ❌ fail	C7	.env.example present	code reads env vars but no .env.example; fix: add it listing required keys
   ➖ N/A	E5	docs/adr	pure tool, no non-trivial decisions yet

   Rules for the table:
   • Status glyphs: ✅ pass, ❌ fail, ➖ N/A, 🔶 drift. Resolve every JUDGE to ✅ or ❌ first (step 3) so no row is left as "judge".
   • Every ❌ must say why it failed and the one-line fix from STANDARD.md.
   • N/A rows must carry their one-line reason.
   • Order: failures and drift first, then the rest. Above the table, give a one-line verdict (e.g. "12/12 applicable green" or "2 gaps"). Below it, offer to fix the mechanical failures now; do not edit unless asked.

Generate the checklist

docs/repo-standard.md

docs/repo-standard.md

{{REPO}}

{{PROFILE}}

{{VERSION}}

{{DATE}}

startup

Rules

• Every verdict traces to STANDARD.md, never memory.
• The audit is presence-and-config only. Never run the validation pipeline (typecheck, lint, test, build) or any heavy command to verify it is "green"; that is CI's job. Check that the repo is wired up to run it, not that it passes.
• Report gaps, do not auto-fix unless the user asks.
• Counts toward "complete" only when every applicable item is done; N/A needs a one-line reason.
• Precision over coverage: a check you cannot run reliably is JUDGE, not a wrong confident verdict.