Rules Organizer

Note

Internal agent — no direct or automatic use. bc-rules-organizer is spawned only by /brewcode:rules, never by you directly and never auto-selected by Claude for an unrelated prompt. It exists as a page here because it ships as one of brewcode’s 5 agents and deserves the same reference treatment as the other 4.

Quick reference

FieldValue
Modelhaiku — pinned, cheap file reorganization
ToolsRead, Write, Edit, Glob, Grep, Bash, Agent
Write access.claude/rules/ directory only
maxTurns60 — anti-loop stop, not a budget
InvocationSpawned by /brewcode:rules via the Task tool — not a slash command, no manual trigger

Scope guard

Rules Organizer never sizes or splits a brief itself — /brewcode:rules already batches and confirms the rule set before the single spawn, so scope is fixed to what it was handed.

SituationWhat the agent does
Brief matches the accepted rule batchWrites only inside .claude/rules/ — every other path is off-limits
Request reaches beyond rule organizationReports it back instead of expanding scope
Brief omits CONTEXT (what the skill already did) or CONSUMER (who reads the rules next)States the assumption in the report, or asks once — never invents scope
maxTurns: 60 is hit mid-runRun aborts; rules already written survive, next run resumes from the last file logged in the report

What it does

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

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

  2. Extraction

    Groups rules by logical scope (component, API, test, build, module) and classifies each as anti-pattern (avoid) or best practice.

  3. 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.

  4. File creation

    Writes or updates files under .claude/rules/ — global avoid.md/best-practice.md with no paths:, or {prefix}-avoid.md style files scoped with quoted glob patterns. Max 20 rows per table; splits into a new specialized file once exceeded.

  5. Checkpoint per file

    Appends each finished file (path + what changed) to .claude/reports/YYYYMMDD-HHMMSS_rules-organizer/report.md right after writing it — not held to the end. If maxTurns is hit, written rules survive; the run resumes from the last file listed in that report.

  6. Optimize and report

    Spawns brewtools:text-optimizer once per created/updated file, all in one message — skipped with a note if brewtools is not installed, never a blocker. Returns a final report: files created/updated table, rule counts, and next-step checklist.

Technical details — frontmatter, dedup protocol, file naming

paths: frontmatter — the only supported field

Source: code.claude.com/docs/en/memory. Only paths: is a valid field — globs, alwaysApply, description are not.

---
paths:
  - "src/components/**/*.tsx"
  - "!src/components/**/*.test.tsx"
---

Patterns must be quoted ("**/*.tsx", not bare). Bug #16299: all rules load at session start regardless of paths: — lazy loading is not actually working upstream, so the agent still scopes files correctly but the load-time benefit doesn’t apply yet.

Rules that fire before a file is in context — search policy, tool-choice policy, delegation policy — stay unscoped (no paths:), because paths: only matches files already in context.

3-Check Dedup Protocol

CheckScopeAction
1. Within-fileSame target file>70% similarity skip; 40-70% merge
2. Cross-file antonymPaired avoid/best-practice fileSame concept as opposite — keep the avoid entry, delete the best-practice one
3. CLAUDE.md duplicateProject CLAUDE.mdAlready documented there — skip entirely, "CLAUDE.md" is a forbidden Source value

File naming

PatternExampleContent
Globalavoid.md, best-practice.mdNo paths:
Path-scoped pair{'{prefix}'}-avoid.md, {'{prefix}'}-best-practice.mdCommon prefixes: test, sql, api, security, kotlin, java, react
Domain-specificbq-core.md, logging.mdMixed 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.

🔗

rules skill

The only entry point that spawns this agent — interactive extraction and batching.

🔗

GitHub source

Agent definition, table formats, and dedup protocol in full.

📄

Brewcode overview

All brewcode skills and agents in one place.

Updating plugins

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