agentleFS
akshaypimprikarakshaypimprikar/pragma/.claude/skills/gates/SKILL.md

gates

Skill4 starsChanged 5 days agoMITView on GitHub

Verify a feature branch meets all pre-PR criteria (build, tests, coverage, gate integrity, and more) before opening the pull request. Invoke at the end of a feature session, passing the branch name.

  • Commits and pushes

10 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 4 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All commands run from the git root (see AGENTS.md/CLAUDE.md for the exact path and project name).

    line 17
  2. Very specific:

    Read .claude/context/invariants.md if it exists — skip silently if absent.

    line 19
  3. Distinctive:

    Every deterministic check lives in one script, so no model transcribes a result:

    line 21
  4. Very specific:

    No listed file → Gates 1 and 2 report skipped (no build-relevant changes).

    line 60
  5. Very specific:

    Every hit in a changed .swift file is listed with its line.

    line 75
  6. Very specific:

    Commit it and re-run the script.

    line 87
  7. Distinctive:

    When Gates 1 and 2 are skipped:

    line 194
  8. Very specific:

    If gates fail and need iterative fixes, use the /loop prompts in reference.md § Autonomous gate-fixing loop, run as a separate top-level …

    line 215
  9. Very specific:

    If any gate caught a violation pattern that is NOT already listed in .claude/context/invariants.md, write it as a candidate comment:

    line 220
  10. Very specific:

    Do not promote it to a numbered invariant — that is a human decision made during the next /pipeline-review.

    line 229
  11. Very specific:

    If the Lane: line says pipeline (or the PR touches pipeline paths alongside app code), also add a Motivating incident: <what went wrong, …

    line 235
  12. Very specific:

    If /gates is re-run after the PR is open (a fix cycle changes HEAD), update the PR body's gate section with the new summary — gh pr edit …

    line 260
  13. Distinctive:

    All 11 gates (Gates 1–11; Gate 0 only decides whether Gates 1–2 run) report: the 10 blocking gates pass and Gate 8, advisory, is listed, PR …

    line 270
  14. Distinctive:

    If you're adopting this command as part of the full pipeline, this file remains the source of truth for your project.

    line 280

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “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

Gates Agent

You are the Gates Agent for an iOS app project. Your job is to verify a feature branch meets all pre-PR criteria before opening the pull request.

Trigger

Invoked at the end of every /feature session before gh pr create (e.g. /gates feature/recurring-transactions).

Process

All commands run from the git root (see AGENTS.md/CLAUDE.md for the exact path and project name).

Read .claude/context/invariants.md if it exists — skip silently if absent. Any gate that catches a violation not already listed as an invariant should append it as a [CANDIDATE] entry (see "## After all gates pass").

Every deterministic check lives in one script, so no model transcribes a result:

scripts/check_gates.sh            # --base main on release/* and hotfix/* (the default there); --branch <name> on a detached HEAD

It runs the pre-step and Gates 0–11 in order, prints each gate's details, and ends with the Gate summary block (Gates run at <sha>, Lane:, one line per gate). Paste that block into the PR body as printed; never retype or edit it. Exit 0: every blocking gate passed. Exit 1: a blocking gate failed — fix it, commit, and re-run. Exit 2: a usage or config error. Exit 3: the tree is dirty. Exit 4: every blocking gate passed but Gate 7 printed [!] Security; run the security review (Gate 7) before you call /gates done. A [✗] File names row means a changed path has a newline in its name, which the gates cannot check: rename it. If scripts/check_gates.sh is missing, /gates FAILS; do not fall back to running the checks by hand.

Your part is only the judgment the script can't make: filling an empty CHANGELOG (Gate 5), running the security-review skill when Gate 7 asks for it, weighing Gate 8's advisory candidates, and writing candidate invariants. The script reads its project settings from the gates key of scripts/pipeline_lanes.json:

KeyUsed byValue
schemeGates 1–2<AppName> (setup.sh fills it). Unset → Gates 1–2 fail as not configured.
build_targetGates 1–2Optional xcodebuild container flag (<BuildTarget>); default is what scripts/detect_build_target.sh prints.
destinationGates 1–2Optional, e.g. platform=iOS Simulator,name=<simulator from AGENTS.md/CLAUDE.md>,OS=<runtime>; default the latest standard iPhone from scripts/select_simulator.py.
sensitive_pathsGate 7Regex over changed .swift paths that handle external input, persistence or authentication, e.g. <ImportLayer>|<AuthLayer>.
app_dir, ui_tests_dir, ui_selector_allowGate 10<AppName>, <AppName>UITests, and selector literals accepted without a match.
rulesGate 10Your AGENTS.md/CLAUDE.md layer and type rules (format under Gate 10).

Pre-step — clean tree and pinned SHA (runs before Gate 0; applies to every gate)

The script stops with exit 3 if git status --porcelain prints anything — Gates 1–2 build the working tree, while Gates 3–11 read the committed git diff <base>...HEAD, so a dirty tree makes the two halves describe different code — and records git rev-parse HEAD as the summary's first line. Any fix made while gates are failing (including Gate 5's CHANGELOG fill) is a new commit, so re-run the script: the summary must describe the commit that actually opens the PR.

Gate 0 — Build-relevant change check (runs first; determines if Gates 1–2 apply)

The script holds the only copy of the build-relevance list: *.swift, the *.xcodeproj/** and *.xcworkspace/** bundles (so project.pbxproj, the Xcode 27.2 project.xcproj, shared schemes and workspace settings all count), *.xcconfig, *Info.plist, *.entitlements, Package.swift/Package.resolved and *.xctestplan. A build-setting change can break the build without touching a .swift file; add any other build input your project has (asset or string catalogs, data models) to that list in the script. scripts/tests/test_gate0_pathspec.py fails if a second copy appears or if it stops matching those files. No listed file → Gates 1 and 2 report skipped (no build-relevant changes).

Gate 1 — Build (conditional: Gate 0 listed files)

xcodebuild build with the configured scheme and destination. Pass: non-empty log, exit 0, and the BUILD SUCCEEDED marker; anything else fails — never "no errors seen". A failed build skips Gate 2 (a test run on a broken build is meaningless). Why the log is captured instead of piped to xcsift, and the Xcode 27 SDK-break advisory: reference.md § Gate 1.

Gate 2 — Full test suite (conditional: Gate 0 listed files)

xcodebuild test, with coverage on when Gate 6 needs it. Pass: exit 0, TEST SUCCEEDED, no failed test case and an executed-test count above zero, reported in the summary (why zero fails, and how the count is read: reference.md § Gate 2). A test that fails once and passes on -retry-tests-on-failure still counts as failed — fail-closed on purpose.

Gate 3 — No TODO/FIXME/HACK in changed files

Every hit in a changed .swift file is listed with its line. Pass: none.

Gate 4 — Branch naming convention

Pass: feature/*, fix/*, hotfix/*, release/*, spec/*, design/*, ci/* or chore/*. Anything else (including main, develop, a detached HEAD without --branch) fails — ask the user to rename.

Gate 5 — CHANGELOG.md has Unreleased entries

Pass: at least one non-empty line in the ## [Unreleased] section, read up to the next ## heading (### subheadings, CRLF blank lines and link definitions such as [1.0.0]: https://... are not entries). Fail: section missing or empty — create the section and add a one-line summary per task, using git log develop..HEAD --oneline to enumerate commits. /feature's two-commit-per-task structure means only the GREEN (implementation) commit carries user-facing content — summarize those, skipping RED (test-only) commits. Commit it and re-run the script. N/A: a PR that changes only .claude/context/feature-log.md (/release puts its entry in the release commit); the script reports [–] CHANGELOG — N/A (feature-log only).

Gate 6 — Coverage (conditional: new Swift files on branch)

Each new non-test .swift file must reach ≥80% line coverage in Gate 2's result bundle (xccov). Skipped: test files (in a *Tests/ folder or named *Test(s).swift), UI-only files (*View.swift, *Sheet.swift, *Row.swift, Color+*), main.swift, and scripts/check_coverage.py's HARDWARE_DEPENDENT_EXCEPTIONS, which the script reads from that file. A new file missing from the report fails. Skipped when the branch adds no files.

Gate 7 — Security (conditional: sensitive code paths)

Changed .swift paths are matched against gates.sensitive_paths. On a match the summary line reads [!] Security — security-review required: <files>: run the security-review skill, fix what it finds, and add one line under the pasted summary in the PR body: Security review: <result>. The summary block itself stays as printed. Skipped when nothing matches, or not configured when the key is empty — set it. A pattern that is not a valid regex fails the gate.

Gate 8 — Abstraction bloat / duplication (heuristic, advisory)

The script lists new protocols with at most one conforming type and runs of 3+ consecutive added lines that each appear 2+ times in the diff. A single-conformer protocol inside the established <RepositoryProtocol>-style pattern (one implementation plus a test mock) is expected, not a candidate. The gate never blocks; final judgment on extracting or inlining is a human or /review call.

Gate 9 — RED-before-GREEN commit order (conditional: new files in a layer that expects a matching test)

Runs scripts/check_tdd_commit_order.py <base>. For every new file in a layer with a 1:1 "<Type>.swift → <Type>Tests.swift" convention (mvvm: ViewModels, Services, Repositories; mvc: Controllers, Services; viper: Presenters, Interactors, Entities — set project.architecture in scripts/pipeline_lanes.json, or list your own folders in project.scoped_layer_dirs) that has a matching test file, the test file must be added in a strictly earlier commit than the implementation. Why from git history: reference.md § Gate 9. Fail: fix by re-doing the task as two commits (test-only, confirm it fails, then implementation). Exit 2 (unconfigured — the layer names match nothing in this repo) is reported [✗], never a pass. A branch that adds no .swift file has nothing to check, so the script skips the gate without running the TDD script; an unconfigured repo still fails on its first branch that adds one. No new files in the scoped layers → skipped. Rewriting already-pushed history is not required.

Gate 10 — Architecture & layer-rule compliance (instantiate from your AGENTS.md/CLAUDE.md's enforced rules)

The single authoritative check for layer-separation, type-safety and pattern rules, before the PR opens rather than only at /review. Two generic checks always run: no try!/as! in changed production code (paths with Tests/ excluded), and every app.buttons/textFields/staticTexts["…"] literal in ui_tests_dir either appears as a string in app_dir (an accessibilityIdentifier or label) or is text the tests type themselves (typeText("…")). Project rules go in gates.rules; each checks the changed .swift files:

FieldMeaning
nameRule name shown with each hit.
patternPython regex, or a list of them.
paths / excludeRegex a file path must / must not match.
added_onlyOnly files added on the branch.
ignore_caseCase-insensitive pattern.
modelines (default): each matching line is a violation. missing: a file that matches no pattern is one.
dropRegex(es); a matching line that also matches one of these is not a hit (e.g. a computed var).
allowRegex(es) over path:line: text; a match is reported as an accepted exception, not a violation.
"rules": [
  {"name": "Domain layer imports <forbidden import>", "paths": "<path to the constrained layer>", "pattern": "^import <forbidden import>"},
  {"name": "Protocol layer imports <persistence or UI framework>", "paths": "<path to your repository-protocol layer>", "pattern": "^import (<persistence framework>|<UI framework>)"},
  {"name": "ViewModel uses a concrete repository", "paths": "<path to your ViewModel layer>", "exclude": "Tests/", "pattern": "<concrete type, e.g. SwiftData\\w*Repository>"},
  {"name": "View imports <persistence framework>", "paths": "<path to your View layer>", "pattern": "^import <persistence framework>"},
  {"name": "Money typed as <forbidden type>", "ignore_case": true, "pattern": [
    "\\b\\w*(<name stems>)\\w*\\s*:\\s*(\\[\\s*(\\w+\\s*:\\s*)?)?<forbidden type>\\b",
    "func\\s+\\w*(<name stems>)\\w*\\s*\\(.*\\)\\s*(async\\s+)?(throws\\s+)?->\\s*(\\[\\s*(\\w+\\s*:\\s*)?)?<forbidden type>\\b",
    "\\b\\w*(<name stems>)\\w*\\s*=\\s*-?[0-9]+\\.[0-9]+\\b",
    "<conversion into the forbidden type, e.g. its .<x>Value accessor>"]},
  {"name": "Unit tests use <forbidden alternative framework>", "paths": "^<your test target>/", "pattern": "<e.g. XCTestCase>"},
  {"name": "New model is not a final class", "paths": "<path to your Models layer>", "added_only": true, "mode": "missing", "pattern": "final class"},
  {"name": "New model has no id", "paths": "<path to your Models layer>", "added_only": true, "mode": "missing", "pattern": "<e.g. var id: UUID>"},
  {"name": "Relationship without a delete rule", "paths": "<path to your Models layer>", "pattern": "<e.g. @Relationship>", "drop": "<e.g. deleteRule>"},
  {"name": "Stored var in a new Domain Service", "paths": "<path to the constrained layer>", "added_only": true, "pattern": "^\\s*(private\\s+)?var\\s+\\w+\\s*[:=]", "drop": ["\\{\\s*$", "\\{ get"]}
]

These are regex heuristics over names, not an AST check: they miss a forbidden type behind a typealias or generic, and can flag an unrelated identifier containing a stem — put each accepted hit in allow so /review can tell it from a new one. With no rules set, the summary line says generic checks only (no gates.rules); every consuming project should have at least its layer-separation and type-safety rules here.

Gate 11 — Gate integrity (floor-guard)

Runs scripts/check_gate_integrity.py <base> <branch> (main on release/* and hotfix/*). Detects gate-weakening — a gate-definition file edited on a feature/* branch, a test deleted instead of fixed, a new suppression marker, an unfinished stub, or a lowered threshold — rather than code-quality issues. It catches the diff-detectable half of "Guard against self-modifying guardrail files" below. The exact pattern list lives in CONSTRAINTS.md's gate-integrity dimension (canonical if it and the script's docstring disagree). Numbered Gate 10 in the standalone deterministic-pr-gates skill — same script, one number lower there because that file has no TDD-commit-order gate. Fail: fix the underlying issue, or move a legitimate gate-definition change to its own chore/* or fix/* branch. A missing script fails as [✗] Gate integrity — script missing.

Gate summary

The script prints this block last; paste it into the PR body exactly as printed. The first line is the full SHA from the pre-step: /review compares it to the PR HEAD and rejects a summary that is missing or stale. The Lane: line is scripts/check_pr_lane.py's answer for this branch and base.

Gates run at <full 40-char SHA from `git rev-parse HEAD`>
Lane: <output of `python3 scripts/check_pr_lane.py --git origin/<base> --head-branch <branch> --base-branch <base>`, where <base> is the PR's base: `develop`, or `main` for `release/*` and a hotfix's first PR>
Gates:
[✓] Build
[✓] Tests — <N> tests executed
[✓] No TODO/FIXME/HACK
[✓] Branch naming
[✗] CHANGELOG — Unreleased section missing or empty
[–] Coverage — skipped (no new files)
[–] Security — skipped (no sensitive files)
[i] Abstraction bloat — no candidates found
[✓] RED-before-GREEN commit order
[✓] Architecture & layer-rule compliance
[✓] Gate integrity

When Gates 1 and 2 are skipped:

Gates run at <full 40-char SHA>
Lane: <lane>
Gates:
[–] Build — skipped (no build-relevant changes)
[–] Tests — skipped (no build-relevant changes)
[✓] No TODO/FIXME/HACK
[✓] Branch naming
[✓] CHANGELOG
[–] Coverage — skipped (no new files)
[–] Security — skipped (no sensitive files)
[i] Abstraction bloat — 1 candidate(s) found (see report)
[–] RED-before-GREEN commit order — skipped (no new files in scoped layers)
[✓] Architecture & layer-rule compliance
[✓] Gate integrity

Fix any failures, commit, and re-run the script before continuing.

Autonomous gate-fixing loop

If gates fail and need iterative fixes, use the /loop prompts in reference.md § Autonomous gate-fixing loop, run as a separate top-level command. Adding, renaming or removing a gate: update that loop's stop condition (gate count, advisory list) in the same commit.

After all gates pass — open the PR

Write candidate invariants (conditional)

If any gate caught a violation pattern that is NOT already listed in .claude/context/invariants.md, write it as a candidate comment:

<!-- [CANDIDATE] YYYY-MM-DD: <describe the violation pattern — e.g. "ViewModel imported SwiftDataRepository directly in feature/X"> -->
  • On a feature/* branch, do not write to invariants.md — .claude/hooks/guard_protected_paths.py blocks the edit and Gate 11 flags it, and the write would also change the tree after the SHA was pinned. Put the comment line under a ## Candidate invariants heading in the PR body instead; it gets appended to the file from a chore/* branch.
  • On any other branch, append it at the bottom of that file, commit it, and restart from the pre-step — the commit moves HEAD, so the gate summary must be re-run against the new SHA.

Do not promote it to a numbered invariant — that is a human decision made during the next /pipeline-review.

Include the actual Gate summary output (from above, starting with its Gates run at <sha> line) in the PR body under its own section — /review checks that SHA against the PR HEAD and re-runs the deterministic gates itself, comparing its results to this block.

If the Lane: line says pipeline (or the PR touches pipeline paths alongside app code), also add a Motivating incident: <what went wrong, with a link or date> line to the PR body, or Motivating incident: none (<reason>). The review-evidence check fails a pipeline-lane PR without a non-empty one.

gh pr create \
  --title "<type>(<scope>): <description>" \
  --base develop \
  --body "$(cat <<'EOF'
## Summary
- <bullet per task from the plan>

## Gates
<paste the actual Gate summary block from this run — the `Gates run at <sha>` line, plus each gate's ✓/✗/– status>

## Test plan
- [ ] Full test suite passes (TEST SUCCEEDED)
- [ ] Tested on simulator (see AGENTS.md/CLAUDE.md)

<append your coding agent's own PR-attribution footer here, if it uses one — e.g. Claude Code appends "🤖 Generated with [Claude Code](https://claude.com/claude-code)">
EOF
)"

If /gates is re-run after the PR is open (a fix cycle changes HEAD), update the PR body's gate section with the new summary — gh pr edit <PR> --body-file <file> — so its Gates run at <sha> matches the new HEAD; /review rejects a stale one.

Always pass --base develop — gh pr create defaults to main (repo default), which bypasses gitflow. Exceptions: release/* and hotfix/* branches use --base main, except a hotfix's second PR back to develop, which uses --base develop (see /bugfix).

Guard against self-modifying guardrail files

.claude/hooks/guard_protected_paths.py (a PreToolUse hook) blocks edits to the guarded files on a feature/* branch, and Gate 11 plus the gates CI job catch the same set on a plain commit and push. What each layer covers, what it misses, and where the pattern came from: reference.md § Guard. Known gaps, so a clean gate summary is not read as proof: the hook fails open on a detached HEAD and allows every edit off feature/*, it does not load in a session started from a parent directory, its Bash-write detection is best effort, a branch renamed away from feature/* escapes it, and .claude/settings.local.json (which can carry disableAllHooks) is not protected.

Done when

All 11 gates (Gates 1–11; Gate 0 only decides whether Gates 1–2 run) report: the 10 blocking gates pass and Gate 8, advisory, is listed, PR is open, and the PR URL is returned to the user.

Tip — chain into code-review + review

Once the PR is open, run /pr-followup <PR> to run code-review (medium, app lane only) and then /review, and record each in the PR body for the review-evidence check. /test runs before /gates, not after the PR opens.

Standalone version

The gate logic above also exists as an installable skill independent of this pipeline: skills/deterministic-pr-gates/SKILL.md. If you're adopting this command as part of the full pipeline, this file remains the source of truth for your project; the skill is for using the gate pattern without the rest of the pipeline.

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.