Admin runbooks
Multi-file procedures. Each lists the files to touch and the order to touch them — never the values inside them. Read the file to get the value.
These are procedures for a human to carry out. State them; do not execute them.
Add a new language
The single most-missed thing in this repo, because the language list is duplicated across config, tooling and docs. Touch all of these or the language is half-supported in ways CI will not tell you about.
.github/schemas/manifest-schema.json— add the value to thelanguageenum. Until this lands, every manifest declaring the language fails schema validation, so do it first..github/policy.yml— add sections underrequired_files.by_language,required_dirs.by_language, andexcluded_paths(build output, dependency caches, lockfiles). Placeholders already exist for some languages; an empty list is a valid answer, a missing key is not..github/CODEOWNERS— add/core/<lang>/**and/contrib/<lang>/**lines. Remember last-match-wins: place them where the intended rule ends up last..github/dependabot.yml— add apackage-ecosystementry. Counter-intuitive but required: the entry exists to suppress updates, not request them. Read that file's header before writing it, and check.github/scripts/tests/test_dependabot_config.py, which asserts the suppression shape..github/workflows/— a<lang>-format.ymland a<lang>-tests.yml, modelled on an existing pair..github/workflows/validate-recipe-structure.yml— add the new root to the workflow's path filters, including the retired<lang>/agents/**path if one exists.tools/validate_manifest.py—LANGUAGE_NAMESPACE_DIRSis a hardcoded set. A language missing here is accepted by the schema and rejected by the validator..github/policy.yml,frozen_paths— only if the language has a retired<lang>/agentsroot to close.- Docs —
docs/recipe-handbook/languages/<lang>.md, plus the language mentions indocs/recipe-checklist.mdanddocs/recipe-handbook/anatomy.md.
Verify: uv run validate all from the repo root, and confirm the new
<lang>-format / <lang>-tests workflows appear on a PR touching that root.
Gotcha: searching for an existing language name to find every touchpoint misses
.github/CODEOWNERS, which has no file extension. Do not filter the search by
extension.
Change who reviews a path
.github/CODEOWNERS— edit or add the line. Rules are last-match-wins, so a new line at the bottom overrides everything above it for the paths it matches.
The file's own header documents how to change the catch-all reviewer and how to add a language folder. Read it rather than reasoning about it.
Gotcha: the change itself needs approval from the current owner of that path, so whoever is being replaced approves their own replacement.
Change a limit or threshold
.github/policy.yml— edit the value. That is the whole procedure.
The file is the single source of truth by design: workflows read it through
.github/scripts/load_policy.py, and docs link to it rather than restating the numbers.
Before promising it is a one-line change, confirm nothing hardcodes the value
independently. That is the consumer trace in drift-checks.md. Known offenders exist —
tools/validate_manifest.py keeps its own language set — so the claim is a strong
default, not a guarantee.
Gotcha, staleness values specifically: the numbers are absolute days since last
activity, and stale-sweep.yml passes actions/stale the difference between the
nudge and the close value. Change one and you change the gap. The workflow asserts the
difference is positive.
Add a required file or directory
.github/policy.yml— add torequired_filesorrequired_dirs, underalways,by_root[<root>], orby_language[<lang>]depending on how wide the rule should be. No code change is needed;tools/validate_structure.pyreads the policy.
Before adding a directory, read the required_dirs header. An empty directory
passes, so the bar is "the recipe is broken without it", not "the recipe is unusual
without it" — several directories were deliberately removed under that bar.
Case sensitivity: entries are matched exactly, so a contributor on a
case-insensitive filesystem can pass locally and fail on CI. case_insensitive_files
relaxes that per-entry, and its header lists which files must never be added to it.
Existing recipes are not grandfathered. Adding to always or a populated
by_root breaks every recipe that lacks the file, at once.
Retire, move, or rename a recipe
- Move the files. Recipes belong at
<root>/<language>/<recipe>, except underplugins/, where the middle folder is a<vertical>. .github/policy.yml,frozen_paths— if closing a whole root. A PR that adds or modifies files under a frozen path fails; deletions and renames are exempt, so migrating out is never blocked.- Dependabot PRs against the old path are closed automatically by
dependabot-housekeeping.yml; nothing to do. - Check inbound references — other recipes' READMEs, docs pages, and
docs-links.ymlwill fail a PR that leaves a dangling internal link.
Verify: uv run validate placement, which exists precisely because the per-recipe
checkers only see recipes the collector already found, and a misplaced recipe is
invisible to that collector.
Gotcha: an escape hatch exists for legacy paths via a PR label, and only users with write access can apply labels.
Exempt something from a sweep
- A pull request or issue — apply the keep-open label named in
stale_policy.keep_open_label. Issues additionally haveexempt_labels, and are exempt when assigned or milestoned. Only users with write access can apply labels, so this is a maintainer override rather than a contributor escape hatch. - A branch — add it to
stale_policy.branches.protected. Shell globs work. The default branch and any branch with a protection rule are skipped automatically. - Never remove the canary label from
exempt_labels. The recipe canary stores its escalation ladder in the issue's labels and finds its issue by title among open issues. Closing one does not pause the ladder, it erases it, and the two workflows then fight monthly forever.
Add a repo skill
.agents/skills/<name>/SKILL.md— frontmatter needsnameanddescription. The description is what makes the skill trigger; write it around what the user will say, not around what the skill does internally.scripts/andtests/— only if the skill needs code. The code goes inscripts/, its tests intests/..github/workflows/tools-tests.ymlruns them, so code without tests is code CI does not cover.docs/recipe-handbook/skills-catalog.md— add an entry if the skill helps contributors prepare a recipe.docs-links.ymlvalidates the links.
Gotcha: AGENTS.md forbids mixing .agents/skills/ changes with recipe or
vertical-skill changes in the same PR.
Add a validator
tools/validate_<name>.py— exposemain(scope: str | None) -> int. The scope convention is documented intools/README.md.tools/validate.py— register it inSUBCOMMANDS.tools/tests/— covered bytools-tests.yml.- A workflow — registering the subcommand makes it runnable locally; it does not make CI run it.
Set up CI cloud auth
Read .github/terraform/README.md. It covers Workload Identity Federation between
GitHub Actions and Google Cloud, and outputs the provider value the workflows consume.