agentleFS
y-miyazakiy-miyazaki/config/.github/actions/CLAUDE.md

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

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

    Do not patch a symptom in the layer where it surfaced.

    line 22
  2. Very specific:

    Every new skip condition adds a skip_reason value from the shared vocabulary and a Bats case that proves the run is skipped.

    line 26
  3. Very specific:

    Every new outcome adds a row to the outcome mapping table and a Bats case for the counter, pending and prune effect.

    line 27
  4. Very specific:

    When a design doc's Unhandled cases gains a Follow-up row, name the gate that should own the fix.

    line 29

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

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

@../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 judgementPut it inNever 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 dataA skip decision inside the detect script
Outcome handling (counter change, pending clear, prune eligibility)The single outcome mapping table in lib/loop/outcome.shA 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 onlyA 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_reason each 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 in lib/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> through lib/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_reason value 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, pending and 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 cases gains a Follow-up row, 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 stemRoleRule
admission.shThe gate: every decision whether a run proceeds or is skippedOnly .github/actions/lib/loop/admission.sh; functions start with admission_
detect.shCollects facts and builds the target set; makes no shared admission decisionloop-detect/lib, loop-entity-detect/lib; skill scripts are detect_<loop>.sh
outcome.shMaps an outcome to its effect (counter, prune); the one outcome tableOnly .github/actions/lib/loop/outcome.sh; functions start with outcome_
run.shAction entry point; orchestrates, decides nothing itselfOne per action, <action>/lib/run.sh
check_*.shValidates inputs or a contract and returns a status; no side effectsValidators use check_, never validate_
push_race.sh, state_pr.sh, ...One mechanism per file, named for the mechanismFunctions start with the file stem (push_race_, state_pr_)

Rules:

  • A function in a shared lib/loop/<stem>.sh file starts with <stem>_. main is the only exception. A new or renamed function that does not follow this is rejected in review.
  • A run or skip decision outside admission.sh is a defect (see Loop judgements go through the gate). A function named admission_* 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.bats fails on a shared lib/loop/<stem>.sh function 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):

FunctionDecides
admission_evaluateRun admission from result.gate, in one fixed order (the entry point)
admission_evaluate_targetCircuit breaker, then pending PR, from the target state and the pending PR state fact (before the detect script runs)
admission_evaluate_deliveryA delivery that needs a PR number (pr_push) has one
admission_circuit_breaker_verdictThe one place that reads a target state and applies the breaker
admission_actor_is_botThe one bot definition
admission_actor_trustedTrusted author association, on every repository
admission_budget_exceededDaily run and token budget
admission_circuit_breaker_openCircuit breaker with the 30-day half-open window
admission_read_budget_limits, admission_read_budget_cost_limitBudget caps read for the budget check
admission_resultBuilds the {admit, skip_reason, detail} object

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.