agentleFS
relvo-labsrelvo-labs/agent-runtime/.agents/skills/local-ci-parity/SKILL.md

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

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
  1. Distinctive:

    Use this skill when a change touches any of:

    line 13
  2. Distinctive:

    Do not use this skill when:

    line 22
  3. Distinctive:

    Credential-free, always: No gate step may require:

    line 66
  4. Very specific:

    Every matrix job runs the complete canonical gate, including package artifact checks.

    line 82
  5. Very specific:

    Update this table and engines together.

    line 83
  6. Very specific:

    Use actions/checkout with credential persistence disabled, then pnpm/setup to install exact pnpm 11.25.0 and the matrix runtime in one step.

    line 86
  7. Very specific:

    Concurrency and permissions: Every workflow sets permissions: contents: read at the top level and a concurrency group keyed on the ref, so …

    line 107
  8. Very specific:

    After changing a workflow, confirm the step ids in the workflow match node tools/repo/gate.ts --list exactly.

    line 124

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Local / CI parity

Trigger

Use this skill when a change touches any of:

  • .github/workflows/**
  • tools/repo/gate.ts or any script it invokes
  • the scripts block of the root package.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 except release.yml, and the rule that a new one must be classified in check-engines.ts before it can exist
  • tools/repo/gate.ts — the canonical step list
  • tools/repo/check-engines.ts — supported-runtime and hosted-workflow bootstrap policy
  • .nvmrc — the baseline Node version and, with it, the supported matrix
  • docs/adr/ADR-0014-ci-and-gate-parity.md — the parity decision record

Does not own

  • tools/repo/check-artifacts.ts — owned by package-artifact-validation
  • tools/repo/generate-schemas.ts — owned by runtime-contract-evolution
  • tools/repo/check-dag.ts — owned by package-architecture
  • pnpm-lock.yaml — owned by pnpm-supply-chain
  • .changeset — owned by changesets-release
  • .github/workflows/release.yml — owned by npm-release; this skill owns every other workflow
  • tools/release — owned by npm-release, including the release gate 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

  1. One step list, two callers. tools/repo/gate.ts holds the ordered array of gate steps. pnpm gate runs it. CI runs the same steps by id. A workflow must never inline a check that gate.ts does not know about — if CI can fail in a way a developer cannot reproduce with one command, that is the bug.
  2. Order steps cheapest-first so feedback is fast: format → lint → typecheck → schema drift → skills → dag → test → build → artifacts.
  3. Credential-free, always. No gate step may require:

    • a model provider API key (no live Codex/Claude calls, ever, in any test)
    • an NPM_TOKEN or 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.

  4. Node matrix. Support only maintained lines. Current matrix:

    LineStatusIn CINotes
    22.18+Maintenance LTSyeslower bound; oldest supported
    24.20.0Active LTSyes.nvmrc baseline, primary job
    26.xCurrentyessupported, bounded to major 26

    Every matrix job runs the complete canonical gate, including package artifact checks. Update this table and engines together.

  5. Pin actions and lock the toolchain. Pin every action to its full immutable commit. Use actions/checkout with credential persistence disabled, then pnpm/setup to 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 on actions/setup-node or Corepack: supported Node installations, including Node 26, need not ship Corepack. Never npm i -g pnpm@latest.

    The managed runtime is a node binary and nothing else. pnpm/setup installs the runtime with pnpm runtime set node <version> -g, which resolves the node package into the pnpm store: $PNPM_HOME/bin/node is a link to …/store/v11/links/@/node/<version>/<hash>/node_modules/node/bin/node, and there is no npm, npx or lib/node_modules anywhere 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 through node_modules, never from process.execPath's neighbours and never from PATH. tools/release/lib/npm-tool.ts is 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/main from refs/remotes/origin/main; full history with only the remote-tracking ref still fails git merge-base main HEAD.

  6. Concurrency and permissions. Every workflow sets permissions: contents: read at the top level and a concurrency group keyed on the ref, so superseded runs cancel. The release workflow is the deliberate exception to cancellation: its group is a constant and cancel-in-progress is false, because interrupting a run half way through a sequence of irreversible publications is worse than queueing it.
  7. 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` installed

After 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 gate

Provenance

  • Source: independent — authored for this repository against the GitHub Actions documentation (concurrency, permissions, immutable action references), the pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b action 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.