rules sonnet

Project scope only

Writes to project .claude/rules/ only — never ~/.claude/rules/.

Quick reference

Field	Value
Command	`/brewcode:rules`
Input	free-form prompt, or empty
Model	sonnet
Specialist	bc-rules-organizer (Task)
List source	`rules.sh list` (Bash)
Target dir	`.claude/rules/` (project only)

When to use

After fixing a bug: capture what went wrong and the correct pattern
After a code review: lock in the standards that were enforced
After a session with many learnings: extract the 5 most impactful findings
To inspect which rules already exist in the project
To import structured knowledge from a KNOWLEDGE.jsonl file

Examples

/brewcode:rules
/brewcode:rules what is the current state of our rules
/brewcode:rules capture what we learned fixing the auth bug
/brewcode:rules path/to/KNOWLEDGE.jsonl add new entries
/brewcode:rules list

How it works

Input gate
Treats the whole of $ARGUMENTS as ONE free-form sentence — no keyword grammar, no argument parser. A non-empty prompt goes to mode selection; an empty one goes to the menu.
Auto-mode select
Announces Mode: <mode> (rules) — chosen because <evidence quoted from the prompt>. Defaults to status for any “show me” intent; detects create, improve, or review from explicit cues; list only on an explicit “list” / “список” / “перечисли”. A .jsonl path or inline prompt is treated as a knowledge source passed to the organizer, not a separate mode.
No-prompt menu
When no arguments are given and mode cannot be inferred, sends a single AskUserQuestion with options in this order: Status (rules) (recommended), Status (all: agents+rules+skills), Create, Improve, Review, List (plain), Cancel.
Dispatch
Routes to bc-rules-organizer via the Task tool, passing the prepared knowledge block and mode. For list mode, runs rules.sh list directly via Bash instead.
Real status
Reports which files were created or updated (avoid.md, best-practice.md, or prefix variants). If bc-rules-organizer is unavailable, outputs: bc-rules-organizer not available — install brewcode plugin.
Final output
Prints a summary of rules added, merged, or skipped, grouped by target file. Skipped entries include the dedup reason (similarity %, cross-file antonym, or CLAUDE.md duplicate).

Modes

Mode	Trigger	Execution
`status` (default)	Any “show me” / “состояние” / health intent	Reports current rule files and coverage; delegates to bc-rules-organizer
`list`	Explicit “list” / “список” / “перечисли” only	Runs `rules.sh list` directly — no agent spawned, no status assembly
`create`	Conversational cue or menu selection	Creates missing rule files from plugin templates; accepts KNOWLEDGE.jsonl or inline prompt as knowledge source
`improve`	Conversational cue or menu selection	Rewrites weak or redundant entries for clarity; accepts KNOWLEDGE.jsonl or inline prompt as knowledge source
`review`	Conversational cue or menu selection	Reads all rule files and reports coverage gaps
`batch`	Auto fan-out flag	Processes multiple knowledge entries in one pass alongside the selected mode

Delegation

Why the rule exists

A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target.

One subagent = ONE bounded unit — here, ONE rule file: roughly 5 files, roughly 10 steps. A batch is split into N tasks fired in ONE message, one bc-rules-organizer per target.

Every spawn prompt carries six fields. A bare one-line task is never enough:

Field	Content
GOAL	the overall task and why it exists — the point beyond the file edit
ROLE	what this agent owns; what it must NOT touch
SCOPE	exact paths/commands in bounds + explicit out-of-bounds
CONTEXT	what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs
CONSUMER	who or what uses the result next, and the shape it must fit
DONE	acceptance criteria + the exact report shape you want back

For the organizer: ROLE is the target rule files only — never CLAUDE.md, never global rules. CONTEXT says the knowledge source is already chosen (do not re-ask) and the existing .claude/rules/*.md are the dedup baseline. CONSUMER is the sharpest constraint: Claude Code auto-loads .claude/rules/*.md into every session, so entries must be table rows, not prose.

Knowledge sources & dedup

Sources accepted:

KNOWLEDGE.jsonl path — parses each line; t:"❌" maps to avoid, t:"✅" maps to best-practice
File path + inline prompt — organizer reads the file and uses the prompt as instruction
Session learnings — the skill selects the 5 most impactful findings from the current conversation and formats them as ❌/✅ pairs

Output files: avoid.md, best-practice.md, {prefix}-avoid.md, {prefix}-best-practice.md — all inside .claude/rules/

3-Check dedup protocol:

Within-file similarity: >70% match → skip; 40–70% match → merge into existing entry
Cross-file antonym check: if the same pattern appears in both avoid and best-practice → keep the avoid entry only
CLAUDE.md duplicate: if the content already appears in CLAUDE.md, skip entirely. The string "CLAUDE.md" is forbidden as a Source value in rule entries

Specialist: bc-rules-organizer — acts as organizer only (no separate creator agent). Spawned via the Task tool; the agent resolves paths via native ${CLAUDE_PLUGIN_ROOT} (substituted in its .md at Task spawn).

⚙️

Updating plugins

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