AGENTS.md

This file provides guidance to AI coding agents (Claude Code, OpenAI Codex, and GitHub Copilot) when working with code in this repository. It is the single source: CLAUDE.md only imports it, so every agent reads the same text. Edit this file, never a copy (see ADR 0010).

What this repository is

This is not an application — it's a versioned package of GitHub workflow skills (skills/github-*/SKILL.md) consumed by three AI coding platforms: OpenAI Codex, Claude Code, and GitHub Copilot CLI (GitHub's Agent Skills format is an explicit open standard shared with Anthropic's, so no content translation is needed for Copilot). ChatGPT is not a supported platform: the Custom GPT export was retired (ADR 0016). The repo's product is policy text plus a validated manifest and an installer that copies that policy into a consumer's home directory (~/.codex, ~/.claude, and/or ~/.copilot).

Priorities. The primary product is the set of GitHub skills: best-in-class workflow policy that the maintainer uses across most of their repositories and shares so others get a first-class GitHub experience. The secondary product is the educational material in education/, training for colleagues that also reaches beyond GitHub (the LLM and tooling track). When the two compete for effort, the skills come first: skill correctness, evidence that each platform finds and follows them, and a trustworthy release take precedence over new lessons. Education is not paused by this: it keeps growing, sequenced after the skill milestones.

Because the "code" here is largely prescriptive documentation that other AI agents will read and act on, precision and internal consistency across files matter more than usual — a wording change in one skill can contradict another. The education/ folder is the one exception: it holds human-facing colleague training material, not agent-facing policy. As of ADR 0007 it covers two parallel tracks — GitHub workflow (the original content) and LLM/VS Code tooling (how a colleague uses Copilot/Claude Code day to day). The LLM track is about colleague usage of AI tooling; it does not change what skills/*/SKILL.md covers, which stays GitHub-workflow-only policy for the agent itself. Per ADR 0009, folders are numbered for reading order (0_prerequisites/ → 1_beginners/ → 2_intermediate/ → 3_advanced/, with a 4_next-level/ tier reserved but not yet populated), and the LLM track's Pre-requisite page is required reading, not optional — its later tiers (Basics, Intermediate, Advanced, Extra) stay optional as written.

Commands

npm ci                 # install devDependencies (markdownlint-cli2, yaml)
npm run validate       # scripts/validate-skills.mjs — manifest/skill checks
npm test               # node --test (runs tests/*.test.mjs)
npm run test:unit      # all but the installer suite (CI: once per Node version)
npm run test:installer # only the installer suite (CI: once per OS)
npm run lint:markdown  # lint:markdown:docs + lint:markdown:skills + lint:markdown:education
npm run check          # validate + test + lint:markdown, run before every PR

Run a single test file directly with the Node test runner:

node --test tests/validate-skills.test.mjs
node --test tests/workflow-policy.test.mjs
node --test tests/install-skills.test.mjs

Installer dry runs (always preview before a real install):

pwsh -NoProfile -File .\scripts\install-skills.ps1 -Target Both -DryRun
pwsh -NoProfile -File .\scripts\install-skills.ps1 -Target Claude -DryRun
pwsh -NoProfile -File .\scripts\install-skills.ps1 -Target Codex -DryRun
pwsh -NoProfile -File .\scripts\install-skills.ps1 -Target Copilot -DryRun

-Target Both means Codex + Claude only, for backward compatibility; installing all three needs two invocations. The installer is PowerShell-only. Windows is the primary verified environment (required CI check); Ubuntu and macOS pwsh also run it in CI as advisory checks. macOS was dropped once for a reparse-point false-positive (/var is a symlink on macOS; see issue #23) and restored once the underlying guard was fixed to stop walking past paths the installer itself doesn't own (see issue #45). .github/workflows/validate.yml runs npm run check plus the installer suite in CI; .github/workflows/release.yml handles releases.

Architecture

Canonical source vs. deployment output

skills/<name>/ is the single canonical source. The installer (scripts/install-skills.ps1) copies these directories into a consumer's .codex/skills, .claude/skills, and/or .copilot/skills. Installed copies are deployment outputs — never edit them; always edit the canonical skills/ tree and let the installer redeploy. All three platforms consume the same SKILL.md content verbatim; only Codex also reads the agents/openai.yaml sidecar (Claude and Copilot both ignore it).

The twelve canonical skills and their handoffs

Each skill has a narrow trigger and a boundary/handoff to the next skill. This chain is the core domain model of the repo (see docs/GUIDE.md for full detail):

• github-issue-first — file an issue before acting on any finding. Hands security-sensitive findings to github-security-response; hands implementation to github-hygiene.
• github-hygiene — owns branches, PR traceability, closure evidence, cleanup. Individual PR review belongs to github-pr-review; releasing and tagging hand off to github-releases; merge still requires explicit human approval.
• github-releases — owns milestones, branch protection/rulesets, release notes, and the release recipe. PR merge and the closure gate stay with github-hygiene; a release containing a security fix goes through github-security-response first.
• github-pr-review — reviews someone else's PR/fork PR against linked acceptance criteria. Approval is not merge approval.
• github-repo-review — full-repository, evidence-based audit; findings labeled CONFIRMED (safely reproduced) or PLAUSIBLE. Exploitable findings go to github-security-response, not a public issue.
• github-repo-bootstrap — the only skill allowed to create repo content before an issue exists (the initial shell); everything after that shell goes through the normal issue-first flow.
• github-repo-configure — elicits org-optional settings (Wiki, Discussions, Project attachment, label scheme) for an already-existing repo, and ships generic issue/PR templates. Distinct from github-repo-bootstrap: this skill's repo already exists, so its work goes through normal issue-first, not the pre-issue exception.
• github-security-response — replaces the public issue/PR path until coordinated disclosure is safe: rotate credentials first, use private advisories, never file an unpatched exploitable finding publicly.
• github-projects — adds a Projects v2 board only when multiple maintainers need shared visualization; never workflow authority, never created by default for a solo maintainer.
• github-for-ado-users — explains Azure DevOps/TFS/Jira → GitHub concept mappings; does not mutate a repository itself.
• github-for-gitlab-users — explains GitLab → GitHub concept mappings (Merge Requests, Epics, Issue Boards, .gitlab-ci.yml); does not mutate a repository itself.
• github-contributing — forks, syncs with upstream, and submits a PR to a repository you don't maintain, then responds to review as the PR's author. Reviewing someone else's fork PR is github-pr-review, not this skill; it never imposes this repo's Refs/Closes conventions on a foreign repo.

The Refs #N / Closes #N closure gate

This is the load-bearing policy invariant repeated verbatim across CONTRIBUTING.md, docs/GUIDE.md, docs/WORKFLOW.md, and docs/MAINTAINING.md, and is itself under automated test (tests/workflow-policy.test.mjs scans policy files for a regex of false closure-safety claims):

• PRs start with Refs #N, not Closes #N.
• Refs #N does not guarantee GitHub keeps the linked issue open — GitHub can still auto-close it via a connected development branch even without a closing keyword.
• After every merge, audit the linked issue; if it closed while an in-scope acceptance criterion is unmet/unevaluated, reopen it and record why.
• Switch to Closes #N only once every criterion has recorded evidence (diff, test, CI run, doc, screenshot, reproduction) — "merged" or "green CI" alone is not evidence.

If you edit this invariant's wording in any one file, update it in all four (see docs/MAINTAINING.md's "Cross-skill invariant review" for the full list, which also includes every skills/*/SKILL.md, the PR template, issue forms, and release automation).

Validation and manifest consistency

The canonical twelve-skill roster (names + required files) is independently hardcoded three times, deliberately — contracts/skill-inventory.json, the CANONICAL_SKILLS constant in scripts/validate-skills.mjs, and $canonicalRequiredFiles in scripts/install-skills.ps1 — as defense in depth, so the installer never blindly trusts the JSON inventory it's installing from. tests/roster-consistency.test.mjs fails automatically if the three diverge, so edit all three when adding/renaming a skill, but drift is now caught by a named test rather than only inferred indirectly. npm run validate separately checks: inventory schema, packageVersion matches package.json, no unregistered skills/github-* directories, every mandatory file exists on disk, and each SKILL.md frontmatter name matches its directory name. Before a release, package.json version, the inventory's packageVersion, and the skillset's git tag (without leading v) must all agree.

Installer safety model

scripts/install-skills.ps1 is defensive by design: it validates the source tree, refuses to overwrite a modified tracked installation without -Force (and backs it up when it does), rejects reparse points/path overlap in the install ancestry, and writes a .doc-github-practice-skills.json marker so it can distinguish "install output" from user files on future runs. Always run with -DryRun first and read the reported source/destination/overwrite/backup plan before running for real — this matches the guidance in CONTRIBUTING.md and docs/claude.md/docs/openai-codex.md/docs/copilot.md.

Architecture decision records

docs/adr/ holds immutable records of why a specific past decision landed where it did — for policy that gets re-litigated, not routine changes. ADR 0001 covers the Refs/Closes connected-branch closure decision above; ADR 0002 covers the github-hygiene split into github-hygiene/github-releases and the github-contributing addition. Check docs/MAINTAINING.md's cross-skill invariant review list, which includes docs/adr/, before assuming a shared-policy change is unprecedented.

Content rules specific to this repo

• Public-content boundary (CONTRIBUTING.md): only generic, sanitized workflow policy belongs here. No company/customer names, private endpoints, credentials, internal policy, or screenshots of private systems.
• Policy changes to any canonical SKILL.md must be considered against all twelve skills and all three consuming platforms (Codex, Claude, Copilot), not just the one file touched.
• Follow the issue-first workflow described above for changes to this repo itself, per CONTRIBUTING.md — issue with acceptance criteria → issue-linked branch via gh issue develop → conventional commits → PR starting Refs #N → evidence per criterion → Closes #N only when every gate passes.