hiroro-work/claude-plugins/rules-review

Rules Review

Usage

/rules-review --base-commit <sha>    # Check diff from specified commit
/rules-review                        # Check diff from HEAD~1

Two optional values may also be passed as natural-language arguments. Each is an independent optional field, not part of a fixed-arity mode gate.

• Model: — one of the model ids the current Agent tool's model parameter accepts (check the tool's live schema loaded in the current session). When present and valid it becomes the model parameter on each reviewer Agent dispatch in § 5. Review; absent or invalid, the reviewer inherits the session model. It is only effective on the Claude Code `Agent`-dispatch path — on the inline / Codex fallback path the executing agent's own model governs.
• Files: — a comma- or newline-separated list of repo-relative file paths. When present, § 1. Prepare narrows the changed-file set to its intersection with the diff's changed files, so the review covers only those; absent or invalid, all changed files are reviewed. An empty intersection fires § 1. Prepare's No changed files early exit (a loud no-issues), so an empty scope never silently passes.

Dispatch authorization

This skill's procedure dispatches subagents, so invoking the skill is the request to use that mechanism: an ambient instruction allowing subagent dispatch only when the user asked for it — a permission-shaped restriction — is already satisfied by this invocation. Do not ask the user to re-confirm the dispatch, and do not silently substitute inline execution for a dispatch this procedure specifies. Only two things justify that substitution: technical availability (the dispatch tool is not present and callable on the current tool surface), and an explicit contract term from the caller bounding this skill to its own thread. A permission-shaped restriction is neither.

Processing Flow

1. Prepare

1. Parse --base-commit <sha> from $ARGUMENTS; if not provided, use git rev-parse HEAD~1. Parse the optional Model: and Files: values per § Usage
2. Get changed files: git diff --name-only <base-commit>. When Files: was provided, narrow this set to its intersection with the parsed paths (repo-relative match). Every downstream step operates on this possibly-narrowed set
3. If no changed files, output No changed files as the final prose result, then emit the verdict per ## Return contract and end the processing flow

2. Collect Rules

1. Find rule files: Glob(".claude/rules/**/*.md"). Also Glob(".claude/rules-extras/**/*.examples.md")
2. Exclude *.examples.md from the check targets. Keep them in step 1's path lists — § 5. Review's pre-split fallback reads the co-located ones from there
3. If the check targets are empty after step 2's exclusion — output No rule files found in .claude/rules/ as the final prose result, then emit the verdict per ## Return contract and end the processing flow

3. Match Rules to Changed Files

For each rule file:

1. Read the file and parse YAML front-matter for paths: globs
2. If paths: exists: match each glob against the changed file list. If at least one changed file matches, include this rule
3. If paths: does not exist (e.g., project.md): apply to all changed files
4. Record which changed files each rule applies to

4. Group Rules by Category

Group matched rules into categories based on their directory path:

• project: Files directly under .claude/rules/ (e.g., project.md, project.local.md)
• {subdirectory}: Files under .claude/rules/{subdirectory}/ (e.g., languages, frameworks, or any custom directory)

Within a category, group related rules by filename prefix into families (rails.md, rails-controllers.md, rails-models.md = one family).

Grouping policy (deterministic):

• Default: 1 group per category (one Agent per category).
• Split a category by family only when it contains more than 3 matched rule files. A family of more than 3 matched files is its own group. Pack the other families in filename order, starting a new group once the current one holds 3 or more files. Never split a family across groups.
• Never merge across categories, even if each category has only 1 rule file.
• Discard empty groups.

If no rules matched any changed files, output No applicable rules for changed files as the final prose result, then emit the verdict per ## Return contract and end the processing flow.

5. Review

Launch one reviewer per group through the current host's reviewer-dispatch mechanism, in parallel where the host allows it:

• Claude Code path: when the Agent tool is exposed and callable and no caller-imposed nesting bound applies (see the Fallback path bullet), launch one reviewer Agent per group — passing the parsed Model: value (§ 1. Prepare) as the Agent model parameter when present, omitting it when absent (inherit).
• Codex path: when Codex exposes a subagent / delegation mechanism in the current session, launch one reviewer per group through that mechanism.
• Fallback path: when no host-provided reviewer dispatch is available — the Agent tool is absent from the tool surface (e.g. a nested subagent context), or the invoking request explicitly bounds this skill to its own thread (a caller-imposed nesting bound) — execute the same reviewer prompt inline sequentially for each group; the current agent acts as the reviewer, reading the embedded rules / examples / diff and producing the reviewer report in the same format. Decide by whether Agent is exposed and callable and whether such a bound applies, not by invocation lineage: being invoked as a sub-skill does not trigger this path, and neither does a permission-shaped restriction (see § Dispatch authorization).

Detect availability by inspecting the current tool surface. Do not attempt speculative tool calls just to probe availability. Do not substitute claude -p, codex, or other external CLIs; the inline path is the defined fallback. Collect results identically in all paths.

No stall after dispatch: once the reviewer Agents are launched (Claude Code path) or the subagent / delegation mechanism is invoked (Codex path), do not end the response with a status-only message such as "dispatched — will report when complete". Continue to § 6. Aggregate Results as soon as the dispatched reviewers' results are available in the same flow; a dispatch is not itself a stopping point.

Scoped re-check note: when Files: narrowed the changed-file set (§ 1. Prepare), append this sentence to the end of the reviewer prompt's **Scope** paragraph — This review is scoped to a caller-specified subset of the changed files. If you suspect a change in these files has a rule-relevant ripple effect on files outside this subset, raise it as a finding. Omit it when Files: was absent.

Each reviewer (dispatched or inline) receives the following prompt:

You are a rules compliance reviewer. Check ONLY whether the code changes comply with the project rules below.
Do NOT report general code quality, bugs, or design issues — only check what is explicitly stated in the rules.
 
**Scope**: only the lines added or modified in the diff are in-scope. Pre-existing patterns elsewhere in the file are out-of-scope unless the rule text itself demands file-wide / project-wide consistency ("across the file", "project-wide", "every occurrence", or equivalent).
 
**Cross-file scope**: when a rule's text does not restrict its scope to a single file (i.e., contains no "in this file", "within this file", or equivalent limiting phrase), apply it across all changed files in the diff — including cross-file references, imports, and shared contracts between changed files.
 
**Same-rule complete enumeration**: when a rule fires at one location, sweep the **full diff** for further same-rule violations instead of reporting only the first. When the violations cluster around a shared identifier, anchor, naming token, or cross-reference shape, grep the diff for the violation's defining token and emit a separate entry for every match.
 
**Existing-baseline judgment**: when the new diff follows the same pattern as a heavily-used existing baseline, judge the new addition against the rule on its own merits — do not let the existing baseline either excuse or condemn the new lines unless the rule's own scope clause says so.
 
Rules may include hard rules (binary compliance) and intent rules (judgment-based). Evaluate both. Report a borderline intent-rule case in the violation list with the `low-confidence` marker; the exact "No rule violations found" response is reserved for cases where you are confident no violations exist.
 
For low-confidence intent-rule findings, make `Suggested fix` a resolution direction rather than a bare flag: check first whether the rule's intent is satisfied by relocating the flagged content to a more appropriate place, and say where, instead of proposing deletion.
 
**Rule-doc drift classification**: when the code follows one behavior consistently across the diff and the surrounding codebase while the rule's text describes a different one, and the pattern looks intentionally established rather than an oversight, classify the finding as **`rule-doc-drift`** instead of a code violation. Supporting signals — judgment, not an automatic trigger: (i) the same "non-compliant" pattern at 3+ sites, all the same shape; (ii) the rule cites an **external platform signal** (a documented threshold, a version-pinned default, a documented API behavior) that the diff updates, with surrounding code or companion docs aligned to the new value; (iii) the rule cites a **numeric value / token / literal** conflicting with the diff's new default for the same concept, plus one further signal that the referent shifted intentionally. A sole new occurrence with no corroborating signal is a code violation. Report drift per `## Report Format`, with the Suggested fix set to the literal string `Route to extract-rules to update the rule document rather than fixing the code`. The caller decides whether to fix the code or update the rule; never apply a code change for one yourself.
 
**Group-exception membership verification**: when a rule's exception clause is conditioned on the target being a member of a named group — for example "references to siblings within the same bundle are permitted" — verify membership from the authoritative source (the distribution manifest, package declaration, module registry, or equivalent) before applying it. Co-location in the same repository, directory, or naming domain is not membership. When membership cannot be confirmed, treat the exception as inapplicable and report the reference as a violation.
 
**Reference/citation matching strictness**: judge a required quotation or citation of a stable heading, section title, or bold-prose label against whichever form the citing rule's own text or an established sibling convention documents as canonical, and use no other criterion. Report a citation as non-compliant only when it deviates from that documented form — never merely for using a permitted prefix / pair variant such as `§ <Heading>'s "<bold label>" paragraph`.
 
## Rules to Check
 
<Rule file contents with file paths>
 
## Reference: Code Examples
 
<Corresponding .examples.md content, if available>
 
## Diff to Review
 
<Scoped git diff for the matched files>
 
## Report Format