Generate File Name Gate
Purpose
A naming rule that nothing enforces decays back into a mixed tree, one file at a time. This skill writes the thing that enforces it: a checker over the tracked set, plus the suite that proves the checker still means what it says.
The checker is the consumer's file, not this plugin's. The rule, the roots, and every exemption are inlined at emission, so a checkout with the plugin uninstalled, or a CI runner that never had it, still enforces what the team agreed.
A path-scoped rule file is not a substitute. A rule is guidance Claude reads during its own session: it blocks nothing, binds no human editor or other tool, and never runs in CI. The gate runs over the whole tracked set wherever it is invoked. That is why the gate is the deliverable and the rule is the option.
- Pointer: when weighing whether a rule could stand in for the gate, fetch memory § Path-specific rules live.
- As of: 2026-10-11
- Recheck trigger: that section gives a path-scoped rule a way to block a tool call, or to apply outside a Claude session.
Emit
${CLAUDE_SKILL_DIR}/scripts/emit-gate.sh --root <repo> [--out-dir <dir>] [--rule] [--force]
--out-dirplaces the pair somewhere other thanscripts/. The emitted checker resolves the repository from its own location, so any depth works.--rulealso writes.claude/rules/file-names.md.--forceoverwrites. Without it an existing target refuses the run and nothing is written, including the files that did not exist yet.
The output is EMITTED rows for what it wrote, possibly a REINDEX row, and
NOT-WIRED rows for what it did not. Report all three kinds; the NOT-WIRED
rows are the point of the run as much as the files are.
What the templates render
| Template | Emitted as | Carries |
|---|---|---|
templates/check-file-names.sh.tmpl |
<out-dir>/check-file-names.sh |
the rule, the roots, the exemptions, and the case-collision pass |
templates/check-file-names.test.sh.tmpl |
<out-dir>/check-file-names.test.sh |
one case per declared exemption, seeded with a name the rule would reject |
templates/file-names-rule.md.tmpl |
.claude/rules/file-names.md, only with --rule |
the rule in prose, scoped to the roots, naming the gate |
Read a template only when a rendered file looks wrong; the emitted files are what the operator reviews.
After emitting, say what is left
Emission writes files. It does not wire them, because each of these is a repository-shaped decision with no single right answer:
- A CI step invoking the checker. Name the emitted path and let the operator place it in their own workflow.
- A registry row, if the repository keeps a list of its gates.
- An architecture decision record for the rule itself. Offer
/architecture:record-decision; do not write one unprompted.
If a REINDEX row appeared, the repository's AGENTS.md or CLAUDE.md carries
a generated instruction-placement rules index, and the new rule file is not in
it yet. Say so and name /instruction-placement:check; do not edit the block.
Verify before handing back
Run the emitted pair once, from the consumer's root:
bash <out-dir>/check-file-names.sh --check
bash <out-dir>/check-file-names.test.sh
The checker's exit is the answer about the tree, not about the emission: a 1
here means the repository already has offenders, which is a finding to report
and route to /docs-naming:audit-file-names, not a failed run.
Completion criteria
The run is done when the EMITTED rows name files that exist, the emitted suite
exits 0, the checker has been run once and its verdict reported, and every
NOT-WIRED row has been said out loud to the operator.
What this skill does NOT do
- Wire the gate into CI, a registry, or a decision record. It names each one and stops.
- Edit a generated rules index. It reports that one needs re-rendering.
- Rename anything. An existing offender is
/docs-naming:audit-file-namesto plan and/docs-naming:realign-file-namesto apply. - Write the configuration. That is
/docs-naming:setup apply, which owns the plugin's own artifact and nothing else. - Overwrite silently. A target that exists refuses the whole run.
- Commit, stage, or push.
Next
/architecture:record-decision
For the rule itself, once the gate is wired and green.
Gotchas
- A rule file is a pointer surface a repository may deliberately not carry.
Some trees strip pointer rules that already have an owner document and a
deterministic oracle, on the argument that the gate is the oracle.
--ruleis opt-in for exactly that reason; offer it and let the operator decide. - A configuration value is untrusted text, and the emitted gate runs in CI.
Three hazards, each closed at a different layer: rendering is a literal splice
rather than a
sedsubstitution, so an&or a|in a regex cannot be re-read; values travel through the environment rather thanawk -v, which performs escape processing and would halve a doubled backslash; and every value reaching the emitted shell is single-quoted, so a backtick or a$(...)in a root or an exemption cannot execute on a CI run. - A rendered file that bash cannot parse is a refusal, not an
EMITTEDrow. Each rendered script goes throughbash -nbefore it is claimed, and a failure removes it and stops the run. - The emitted suite's probe names come from the rule, not from the template. A rule that admits no probe name, or rejects none, is refused at emission rather than handed over as a suite that fails on its own clean fixture.
- Re-emit rather than hand-edit. The configuration is what the audit and realign skills read; an edit made only in the emitted checker drifts from them with nothing to catch it.
- A refused run writes nothing at all. The overwrite check runs over every target before the first write, so a partial emission cannot happen.
- The emitted checker is only as current as the configuration was. Changing
a root or an exemption means emitting again with
--force.