config / actions
CLAUDE.md1 starsChanged 3 days agoApache-2.0View on GitHub
@../workflows/CLAUDE.md Behavioral rules for .github/actions/**. The rules of .github/workflows/CLAUDE.md apply here too (imported above). This file adds the loop-engineering code rules; design background: Loop Engineering Design. Applies when adding or changing any rule that decides whether a loop run proceeds, is skipped, or how an outcome is counted (.github/**/loop-*, .github/actions/lib/loop/, .apm/packages/**/detect_*.sh, on-loop-*.yaml). Background: Design Invariants 8 and 9 in Loop Engineering Design. Applies to scripts under `.github/a
In this repository57 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .apm/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .github/workflows/CLAUDE.mdCLAUDE.md
- .cursor/rules/agent-skills.mdcCursor rule
- .cursor/rules/bats.mdcCursor rule
- .cursor/rules/github-actions-workflow.mdcCursor rule
- .cursor/rules/go.mdcCursor rule
- .cursor/rules/go-test.mdcCursor rule
- .cursor/rules/instructions.mdcCursor rule
- .cursor/rules/markdown.mdcCursor rule
- .cursor/rules/shell-script.mdcCursor rule
- .cursor/rules/terraform.mdcCursor rule
- agent-skills-reviewSkill
- changelogSkill
- ci-sweeperSkill
- docs-creatorSkill
- docs-updaterSkill
- github-actions-reviewSkill
- github-actions-validationSkill
- github-issue-autofixSkill
- github-issue-triageSkill
- github-pr-bodySkill
- github-pr-reviewSkill
- github-pr-reviseSkill
- go-reviewSkill
- go-validationSkill
- instructions-reviewSkill
- loop-verifierSkill
- markdown-validationSkill
- refactorSkill
- shell-script-reviewSkill
- shell-script-validationSkill
- tech-debtSkill
- test-gapSkill
- agent-skills-reviewSkill
- changelogSkill
- ci-sweeperSkill
- docs-creatorSkill
- docs-updaterSkill
- github-actions-reviewSkill
- github-actions-validationSkill
- github-issue-autofixSkill
- github-issue-triageSkill
- github-pr-bodySkill
- github-pr-reviewSkill
- github-pr-reviseSkill
- go-reviewSkill
- go-validationSkill
- instructions-reviewSkill
- loop-verifierSkill
- markdown-validationSkill
- refactorSkill
- shell-script-reviewSkill
- shell-script-validationSkill
- tech-debtSkill
- test-gapSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Do not patch a symptom in the layer where it surfaced.
- Very specific: line 26
Every new skip condition adds a skip_reason value from the shared vocabulary and a Bats case that proves the run is skipped.
- Very specific: line 27
Every new outcome adds a row to the outcome mapping table and a Bats case for the counter, pending and prune effect.
- Very specific: line 29
When a design doc's Unhandled cases gains a Follow-up row, name the gate that should own the fix.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
@../workflows/CLAUDE.md
CLAUDE.md
Behavioral rules for .github/actions/**. The rules of .github/workflows/CLAUDE.md apply here too (imported above). This file adds the loop-engineering code rules; design background: Loop Engineering Design.
Loop judgements go through the gate (MUST)
Applies when adding or changing any rule that decides whether a loop run proceeds, is skipped, or how an outcome is counted (.github/**/loop-*, .github/actions/lib/loop/, .apm/packages/**/detect_*.sh, on-loop-*.yaml). Background: Design Invariants 8 and 9 in Loop Engineering Design.
| Kind of judgement | Put it in | Never in |
| Run admission (entity state, actor trust, mention, pending, circuit breaker, budget) | The admission gate (.github/actions/lib/loop/admission.sh) | Job if, a detect script, finalize |
| Facts about the entity (state, author, labels, linked PRs) | The detect script, returned as data | A skip decision inside the detect script |
Outcome handling (counter change, pending clear, prune eligibility) | The single outcome mapping table in lib/loop/outcome.sh | A per-action case on OUTCOME |
| Self-retrigger and abuse filter (bot sender, event type, label name; author association or mention only as a strict subset of the gate) | Job if, static and cheap only | A bypass of a gate check, repository visibility |
Rules:
- Do not patch a symptom in the layer where it surfaced. Find the gate that owns the judgement and change it there; if no gate owns it, add the judgement to the gate, not beside it.
- One definition per concept: bot actor, trusted author association, open entity, and
skip_reasoneach have exactly one definition. Do not add a second. The same holds for the names actions validate: a branch name, the loop name and the state file path have one definition inlib/loop/check_names.sh(check_names_branch,check_names_loop_name,check_names_state_file); a copy of their regex elsewhere is a defect, and a Bats case fails on it. - State data (the state file and the run log) is read from
origin/<state_branch>throughlib/loop/state_snapshot.sh, never from the checked-out tree, which may be a PR head. The budget file is policy configuration, not state: read it from the trusted checkout. Code that runs with a write token comes from the trusted ref (see Trusted ref). - Repository visibility is never a trust signal. Actor trust is
author_association(MEMBER, OWNER, COLLABORATOR) on every repository. - Every new skip condition adds a
skip_reasonvalue from the shared vocabulary and a Bats case that proves the run is skipped. - Every new outcome adds a row to the outcome mapping table and a Bats case for the counter,
pendingand prune effect. - Missing facts fail closed: a gate that cannot read a fact skips the run with a reason, never proceeds.
- When a design doc's
Unhandled casesgains aFollow-uprow, name the gate that should own the fix.
Script and function naming (MUST)
Applies to scripts under .github/actions/**/lib/ and .github/actions/lib/loop/. The file stem tells the role, and the function prefix tells the file, so grep finds every judgement of one kind.
| File stem | Role | Rule |
admission.sh | The gate: every decision whether a run proceeds or is skipped | Only .github/actions/lib/loop/admission.sh; functions start with admission_ |
detect.sh | Collects facts and builds the target set; makes no shared admission decision | loop-detect/lib, loop-entity-detect/lib; skill scripts are detect_<loop>.sh |
outcome.sh | Maps an outcome to its effect (counter, prune); the one outcome table | Only .github/actions/lib/loop/outcome.sh; functions start with outcome_ |
run.sh | Action entry point; orchestrates, decides nothing itself | One per action, <action>/lib/run.sh |
check_*.sh | Validates inputs or a contract and returns a status; no side effects | Validators use check_, never validate_ |
push_race.sh, state_pr.sh, ... | One mechanism per file, named for the mechanism | Functions start with the file stem (push_race_, state_pr_) |
Rules:
- A function in a shared
lib/loop/<stem>.shfile starts with<stem>_.mainis the only exception. A new or renamed function that does not follow this is rejected in review. - A run or skip decision outside
admission.shis a defect (see Loop judgements go through the gate). A function namedadmission_*is the only kind of function that returns an admit or skip decision. - Facts are named for what they read (
detect_*,read_*), decisions for what they refuse (admission_*), effects for what they write (write_*,deliver_*). test/bats/.github/actions/lib/loop/naming.batsfails on a sharedlib/loop/<stem>.shfunction that does not follow this, so a rename is part of the change that adds or edits the function.
Gate map (.github/actions/lib/loop/admission.sh):
| Function | Decides |
admission_evaluate | Run admission from result.gate, in one fixed order (the entry point) |
admission_evaluate_target | Circuit breaker, then pending PR, from the target state and the pending PR state fact (before the detect script runs) |
admission_evaluate_delivery | A delivery that needs a PR number (pr_push) has one |
admission_circuit_breaker_verdict | The one place that reads a target state and applies the breaker |
admission_actor_is_bot | The one bot definition |
admission_actor_trusted | Trusted author association, on every repository |
admission_budget_exceeded | Daily run and token budget |
admission_circuit_breaker_open | Circuit breaker with the 30-day half-open window |
admission_read_budget_limits, admission_read_budget_cost_limit | Budget caps read for the budget check |
admission_result | Builds the {admit, skip_reason, detail} object |
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.

