Rules Organizer

Note

Internal agent with no direct or automatic invocation. The main orchestrator supplies an accepted, bounded rule batch through rules or the rule-writing phase of convention-setup. Convention setup establishes project patterns early, before teams and review setup.

Current execution contract

The organizer writes its briefed rules and its own checkpoint/report. The main caller owns optimizer spawns, snapshots, RUN_DIR and acceptance. Loading behavior was rechecked through Claude Code 2.1.285; the agent uses the existing rule scaffold and validation gates.

Quick reference

Field	Value
Model	`haiku` — pinned, cheap file reorganization
Tools	Read, Write, Edit, Glob, Grep, Bash, Agent
Write access	Briefed `.claude/rules/` files plus its checkpoint/report directory
`maxTurns`	60 — anti-loop stop, not a budget
Invocation	Main-caller `Agent` spawn for the accepted rule batch; no manual trigger

Scope guard

The main caller batches and confirms one bounded unit before spawning the organizer. Scope stays fixed to the brief; out-of-scope work returns to the caller.

Situation	What the agent does
Brief matches the accepted rule batch	Writes the briefed rules and its checkpoint/report; no global rules or CLAUDE.md writes
Request reaches beyond rule organization	Reports it back instead of expanding scope
Brief omits CONTEXT (what the skill already did) or CONSUMER (who reads the rules next)	States a safe assumption or returns the question to main; never invents scope
`maxTurns: 60` is hit mid-run	Written files survive; main checks the partial result before acceptance and can resume with `SendMessage`; the agent reads its checkpoint first
Before writing a new rule file (Scope Fit)	Finds the closest well-built existing rule file in `.claude/rules/*.md` first and takes its principles — additive, never a wholesale replacement; after finishing, one pass to cut files/config/indirection if the result can be simpler

What it does

Ordinary subagents cannot use AskUserQuestion; conversation forks retain the parent’s tool pool. This organizer returns unresolved decisions to the main caller. It never delegates, even though Agent appears in its allowed tools. Main owns all research and optimizer spawns.

Rules Organizer takes rules extracted from a source file (CLAUDE.md, docs, code) and turns them into .claude/rules/*.md files with correct paths: frontmatter — one file per logical scope, deduplicated against everything already there, formatted as numbered tables instead of prose.

It owns two authoritative table formats (| # | Avoid | Instead | Why | and | # | Practice | Context | Source |), a 3-check dedup protocol that catches near-duplicates and avoid/best-practice antonym pairs, and a hard 20-row-per-file ceiling that forces a split into {prefix}-avoid.md / {prefix}-best-practice.md once a file grows past it.

Example

/brewcode:rules "extract logging and SQL conventions from CLAUDE.md"

The skill reads the source, proposes rule candidates, asks you to accept/reject in batches, then spawns bc-rules-organizer once with the accepted set. Expected result: .claude/rules/logging.md and .claude/rules/sql-best-practice.md created or updated, each with paths: frontmatter, numbered tables, and a report listing files created/updated plus a rule count.

Workflow

Analysis
Reads the source file completely, identifies rule categories, maps each to a path pattern (or auto-detects from project structure), checks existing rules first.
Extraction
Groups rules by logical scope (component, API, test, build, module) and classifies each as anti-pattern (avoid) or best practice.
Optimization and dedup
Converts prose to tables, applies abbreviations, adds lazy links for detail. Runs the 3-Check Dedup Protocol: within-file similarity, cross-file avoid/best-practice antonym pairs, and a CLAUDE.md duplicate check — anything already in CLAUDE.md is skipped, never re-added.

File creation

New files scaffold automatically; editing an existing file is manual. Behavior differs by action:

Action	Behavior
Scaffold	`rules.sh create` (global) or `rules.sh create-specialized <prefix> '<paths>'` (scoped) — stamps `doc_type`/`version`/`generated_by`/`last_updated`
Edit existing file	Only refreshes `last_updated` and `version` by hand
Naming	Global `avoid.md`/`best-practice.md` carry no `paths:`; every `{prefix}-avoid.md` style file needs one
Row cap	Max 20 rows per table; splits into a new specialized file once exceeded
Validate	`rules.sh validate` runs after every write and must pass before finishing

Checkpoint per file
Appends each finished file (path + change) to .claude/reports/YYYYMMDD-HHMMSS_rules-organizer/report.md immediately. Claude Code 2.1.246+ returns partial output on turn exhaustion. Main checks that marker before accepting or resuming; the organizer reads the checkpoint first.
Optimize and report
Returns written paths and optimization requests to main. The caller follows the installed brewtools:text-optimize Medium workflow: snapshot before edits, supply RUN_DIR, dispatch optimizers, review the result and rerun rule validation. Required mode gates and any independent verification remain in the caller’s workflow. The organizer never launches an optimizer directly. Missing Brewtools is reported as skipped; valid written rules remain usable.

Technical details — frontmatter, dedup protocol, file naming

Rule-file frontmatter contract

paths: is the only field Claude Code itself reads for scoping — source: code.claude.com/docs/en/memory (globs, alwaysApply, description-as-scoping are not real fields). On top of that, rules.sh validate requires five more keys on every rule file the agent writes: description, doc_type, version, generated_by, last_updated.

---
paths:
  - "src/components/**/*.tsx"
  - "!src/components/**/*.test.tsx"
description: "..."
doc_type: llm
version: "6.1.4"
generated_by: "brewcode:rules"
last_updated: "2026-09-12"
---

Patterns must be quoted ("**/*.tsx", not bare) and given as an array, never a bare string; doc_type is the one unquoted value (doc_type: llm exactly).

Loading (rechecked through 2.1.285)

Frontmatter	Behavior
No `paths`	Loads at session start, same priority as project CLAUDE.md
With `paths`	Loads lazily — only when Claude reads a file matching the glob, not on every tool use

The source reference supersedes the old all-rules-at-start observation in #16299. A rule that must apply before any file is read stays unscoped:

Rule kind	`paths:`?
Language/dir conventions (naming, test layout, SQL style)	yes
Tool-choice and search policy (lsp-first, semble-first)	no
Global anti-patterns	no

3-Check Dedup Protocol

Check	Scope	Action
1. Within-file	Same target file	>70% similarity skip; 40-70% merge
2. Cross-file antonym	Paired avoid/best-practice file	Same concept as opposite — keep the avoid entry, delete the best-practice one
3. CLAUDE.md duplicate	Project CLAUDE.md	Already documented there — skip entirely, `"CLAUDE.md"` is a forbidden Source value

File naming

Pattern	Example	Content
Global	`avoid.md`, `best-practice.md`	No `paths:`
Path-scoped pair	`{'{prefix}'}-avoid.md`, `{'{prefix}'}-best-practice.md`	Common prefixes: test, sql, api, security, kotlin, java, react
Domain-specific	`bq-core.md`, `logging.md`	Mixed avoid + best-practice tables under one `paths:` scope

Version stamping (v5.1.0+)

Its frontmatter version, generated_by, and last_updated are rewritten at release, never edited by hand.

Return Contract

Verdict first, <=30 lines, path:line. No rule-file bodies, no pasted tables, no extraction notes, no preamble. Returns one row per file (path, matched paths:, change) plus totals: new/updated counts, rule counts, dedup skipped/merged, and whether text-optimizer ran. Dedup ledger, per-rule rationale, and source excerpts go to the same .claude/reports/<YYYYMMDD-HHMMSS>_rules-organizer/ checkpoint file — only the path comes back.

/brewtools:agent-return-setup enforces this at ~1000 / ~2500 est-tokens when installed; the contract itself ships unconditionally.

🔗

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.