local-ci-parity
Skill0 starsChanged 50 days agoApache-2.0View on GitHub
Keep one canonical credential-free gate that runs identically on a developer machine and in GitHub Actions, with no step that only exists in one place.
- Reads credentials
- Installs packages
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- changesets-releaseSkill
- npm-releaseSkill
- package-architectureSkill
- package-artifact-validationSkill
- pnpm-supply-chainSkill
- provider-adapter-developmentSkill
- public-api-evolutionSkill
- runtime-contract-evolutionSkill
- runtime-lifecycle-coordinationSkill
- workspace-lifecycleSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Use this skill when a change touches any of:
- Distinctive: line 22
Do not use this skill when:
- Distinctive: line 66
Credential-free, always: No gate step may require:
- Very specific: line 82
Every matrix job runs the complete canonical gate, including package artifact checks.
- Very specific: line 83
Update this table and engines together.
- Very specific: line 86
Use actions/checkout with credential persistence disabled, then pnpm/setup to install exact pnpm 11.25.0 and the matrix runtime in one step.
- Very specific: line 107
Concurrency and permissions: Every workflow sets permissions: contents: read at the top level and a concurrency group keyed on the ref, so …
- Very specific: line 124
After changing a workflow, confirm the step ids in the workflow match node tools/repo/gate.ts --list exactly.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Local / CI parity
Trigger
Use this skill when a change touches any of:
.github/workflows/**tools/repo/gate.tsor any script it invokes- the
scriptsblock of the rootpackage.json - the supported Node version matrix or
.nvmrc
Counter-trigger
Do not use this skill when:
- you are changing what a single gate step checks — use that step's owning skill
(
package-artifact-validation,runtime-contract-evolution, …) - you are changing dependency install policy — use
pnpm-supply-chain - you are changing the release workflow, or anything about how publication works — use
npm-release. No workflow this skill owns may publish, reference a secret, or hold a publish credential.
Owns
.github/workflows— every hosted workflow exceptrelease.yml, and the rule that a new one must be classified incheck-engines.tsbefore it can existtools/repo/gate.ts— the canonical step listtools/repo/check-engines.ts— supported-runtime and hosted-workflow bootstrap policy.nvmrc— the baseline Node version and, with it, the supported matrixdocs/adr/ADR-0014-ci-and-gate-parity.md— the parity decision record
Does not own
tools/repo/check-artifacts.ts— owned bypackage-artifact-validationtools/repo/generate-schemas.ts— owned byruntime-contract-evolutiontools/repo/check-dag.ts— owned bypackage-architecturepnpm-lock.yaml— owned bypnpm-supply-chain.changeset— owned bychangesets-release.github/workflows/release.yml— owned bynpm-release; this skill owns every other workflowtools/release— owned bynpm-release, including thereleasegate step's implementation
Relationships
depends-on→pnpm-supply-chain— CI installs with a frozen lockfile.boundary-with→package-artifact-validation— that skill defines the artifact checks; this skill guarantees they run in both places.boundary-with→changesets-release— this skill owns workflows but may not add a publishing job.boundary-with→npm-release— the release workflow is the one exception to "every workflow here is credential-free"; it lives inside this skill's directory but is owned, and structurally checked, there.
Procedure
- One step list, two callers.
tools/repo/gate.tsholds the ordered array of gate steps.pnpm gateruns it. CI runs the same steps by id. A workflow must never inline a check thatgate.tsdoes not know about — if CI can fail in a way a developer cannot reproduce with one command, that is the bug. - Order steps cheapest-first so feedback is fast: format → lint → typecheck → schema drift → skills → dag → test → build → artifacts.
Credential-free, always. No gate step may require:
- a model provider API key (no live Codex/Claude calls, ever, in any test)
- an
NPM_TOKENor any publish credential - a GitHub token beyond the default read-only
GITHUB_TOKEN
A test that needs a provider must use the deterministic scripted provider from
@relvo-labs/agent-provider/testing.Node matrix. Support only maintained lines. Current matrix:
Line Status In CI Notes 22.18+ Maintenance LTS yes lower bound; oldest supported 24.20.0 Active LTS yes .nvmrcbaseline, primary job26.x Current yes supported, bounded to major 26 Every matrix job runs the complete canonical gate, including package artifact checks. Update this table and
enginestogether.Pin actions and lock the toolchain. Pin every action to its full immutable commit. Use
actions/checkoutwith credential persistence disabled, thenpnpm/setupto install exact pnpm 11.25.0 and the matrix runtime in one step. Enable its cache, require the lockfile, disable its implicit install, and run the repository's explicit frozen install next. Do not depend onactions/setup-nodeor Corepack: supported Node installations, including Node 26, need not ship Corepack. Nevernpm i -g pnpm@latest.The managed runtime is a
nodebinary and nothing else.pnpm/setupinstalls the runtime withpnpm runtime set node <version> -g, which resolves thenodepackage into the pnpm store:$PNPM_HOME/bin/nodeis a link to…/store/v11/links/@/node/<version>/<hash>/node_modules/node/bin/node, and there is nonpm,npxorlib/node_modulesanywhere near it. Nothing in this repository may assume otherwise. A tool that is not pnpm, Node or this workspace's own code is a dependency: pin it in the catalog and resolve it throughnode_modules, never fromprocess.execPath's neighbours and never fromPATH.tools/release/lib/npm-tool.tsis the worked example — the npm that publishes is pinned, because assuming the runtime carried one is what broke run 34699256419.Changesets needs its configured base as a local Git ref. Checkout must fetch complete history and materialize
refs/heads/mainfromrefs/remotes/origin/main; full history with only the remote-tracking ref still failsgit merge-base main HEAD.- Concurrency and permissions. Every workflow sets
permissions: contents: readat the top level and aconcurrencygroup keyed on the ref, so superseded runs cancel. The release workflow is the deliberate exception to cancellation: its group is a constant andcancel-in-progressisfalse, because interrupting a run half way through a sequence of irreversible publications is worse than queueing it. - Do not add a step that is green because it is skipped. The canonical gate has no environment-dependent skip path. If a required step cannot run, it fails.
Verification
pnpm gate # must pass locally with no network beyond the npm registry
node tools/repo/gate.ts --list # the step list CI consumes
act -j gate # optional, if you have `act` installedAfter changing a workflow, confirm the step ids in the workflow match
node tools/repo/gate.ts --list exactly. A mismatch is a parity break.
Parity is about the toolchain as well as the step list, and a developer Node from nvm or a distro package is not the runtime CI uses. When a change could depend on the runtime's layout, reproduce the hosted one before trusting a local green:
export PNPM_HOME=/tmp/setup-pnpm # stands in for ~/setup-pnpm on the runner
"$PNPM_HOME/pnpm" runtime set node 24.20.0 -g # the pinned pnpm executable, as the action installs it
PATH="$PNPM_HOME:$PNPM_HOME/bin:$PATH" pnpm gateProvenance
- Source: independent — authored for this repository against the GitHub Actions
documentation (
concurrency,permissions, immutable action references), thepnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9baction contract, the pnpm CI guide and the Node.js release schedule. - Incorporated:
antfu/skills@a74f281a27dadc02397bc1a174b0f2c97531b6ae(MIT) — the single-canonical-gate framing and the cheapest-first step ordering were adapted from its CI skill guidance.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

