repo-invariant-review
Skill1 starsChanged 2 months agoApache-2.0View on GitHub
Check a change against this repository's mechanically enforced invariants — protected paths, the eval_harness/flow_corpus airgap, the 500-line size budget, the frozen public surface and plugin-registry baselines, CHARTER §4 invariant 1, and README/registry drift. Use before opening a PR, when reviewing someone else's change or proposal, or whenever a plan proposes touching core models, the engine, scorers, judges, gating, or architecture.yaml. Predicts concrete CI failures rather than offering style opinions.
In this repository39 other files it gives its agents.
- agent-core/AGENTS.mdAGENTS.md
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- behavioral-regression/AGENTS.mdAGENTS.md
- claude-foundation/AGENTS.mdAGENTS.md
- config/AGENTS.mdAGENTS.md
- corpora/AGENTS.mdAGENTS.md
- demo/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- examples/AGENTS.mdAGENTS.md
- experiments/AGENTS.mdAGENTS.md
- flow-corpus/AGENTS.mdAGENTS.md
- flow-protocol/AGENTS.mdAGENTS.md
- openspec/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- skills/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- claude-foundation/CLAUDE.mdCLAUDE.md
- merge-gate-auditorSkill
- update-executive-reportSkill
- update-executive-reportSkill
- architecture-drift-guardSkill
- commonSkill
- corpus-guardianSkill
- dataset-lintSkill
- deploySkill
- e2e-matrix-sentinelSkill
- eval-corpus-forgeSkill
- hierarchical-recursive-brainstormSkill
- model-benchSkill
- openai-judgeSkill
- openspec-implementation-reviewSkill
- openspec-peer-reviewSkill
- openspec-quality-planSkill
- pre-pr-gateSkill
- project-setupSkill
- quality-gateSkill
- refactoring-decomposerSkill
- test-completeness-guardSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Every check maps to a gate that exists in CI, so a finding predicts a specific job failing — never a matter of taste.
≈ “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
repo-invariant-review — predict CI collisions before you push
Generic peer review asks whether a change is good. This asks a narrower and more falsifiable question: would this change collide with a rule this repo already enforces?
Every check maps to a gate that exists in CI, so a finding predicts a specific job failing —
never a matter of taste. That is what lets this skill have an honest scripted validation gate,
which openspec-peer-review explicitly cannot ("there is no honest scripted gate for the
quality of a peer review").
1. Preconditions (input contract)
- A git repository, with a base ref to diff against (default
origin/main). Falls back to the working-tree diff when the base ref is unavailable. - Python 3.10+, stdlib only. No network, no external dependencies.
- Best run from the repo root so the checks can read the repo's own sources of truth —
scripts/eval_protected_paths.pyandscripts/check_size_budget.pyare read directly, so the skill cannot drift from the gates it predicts.
2. Procedure (the E2E steps)
# Path is relative to this skill directory. From the repo root (where §1 says to run it),
# spell it out in full — a bare `scripts/check_invariants.py` resolves to the repo's own
# scripts/ directory, which does not contain this checker.
python skills/repo-invariant-review/scripts/check_invariants.py --repo <path> --base origin/main [--has-label] [--strict] [--format {text,json}] [--out report.json]- Run it against the branch before pushing.
- Read each finding:
BLOCKINGpredicts a red CI job;advisorypredicts future pain. - Act on the
remedyline — each names the specific fix, not a general direction. - Pass
--has-labelonceeval-change-approvedis actually on the PR, so the protected-path finding stops masking the others.
3. What it checks, and what each predicts
| Check | Predicts a failure in | Typical remedy |
protected_paths | the protected-path guard | request eval-change-approved + CODEOWNERS review, or split the PR by protection level |
size_budget | scripts/check_size_budget.py (500-line hard fail) | move code into a submodule imported for its registration side effects |
airgap | architecture-drift-guard (F-011, negative test F-012) | route shared code through agent_core; never add the edge to architecture.yaml |
surface_baselines | tests/test_public_surface.py (F-039, exact equality) | python tests/test_public_surface.py --update |
registry_baselines | tests/test_plugin_registry_surface.py | python tests/test_plugin_registry_surface.py --update |
core_model_change | CHARTER §4 invariant 1 review | add a numbered ADR + a §3 Ratified Amendment (CHARTER §6) |
readme_registry_drift | the docs.yml README/registry job | list every registered name verbatim — brace-expansion shorthand does not satisfy it |
4. Output contract (postconditions — what "done" means)
- A report on stdout, and at
--outwhen given. - JSON output is byte-stable for a given input: findings and file lists are sorted, and nothing carries a timestamp or an absolute path, so reports are diffable and committable.
- Exit
0when nothing blocking was found,1when something was,2on usage error. --strictpromotes advisory findings to blocking.
5. Validation gate (before declaring success)
Unlike a subjective review skill, this one has a real gate:
python scripts/validate_skill.py --skill . --tier structural,behavioralThose are the only two tiers the validator implements, and they are exactly what CI runs.
An unrecognised tier is not an error — it simply matches no branch and exits 0, so a
typo here reports success having executed nothing.
The evals in evals/evals.json run the checker against committed fixtures — one clean tree and
one that violates several invariants at once — and assert both the exit code and the specific
findings. A check that silently stops firing fails the eval.
6. Limits worth knowing
- It predicts collisions, not correctness. A change can pass every check here and still be wrong; run the full quality gate as well.
core_model_changeis satisfied by any ADR in the same diff. It cannot tell whether the ADR actually authorises the change — that judgement stays human.surface_baselinesandregistry_baselinesare advisory because not everysrc/change adds an export. They flag the risk; only the real guard knows.
7. Examples
See evals/evals.json and its fixtures for the exact invocations and expected findings.
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.

