convention — extract code patterns

Caution

Every project drifts. New developers copy the wrong class, inconsistent naming spreads across modules, anti-patterns accumulate silently. Without explicit etalon classes — reference implementations that define “correct” — code reviews become opinion contests and onboarding takes weeks instead of days.

Tip

One run, three convention documents. The skill spawns up to 10 parallel agents, selects the best etalon per layer, generates .claude/convention/ docs, and optionally extracts rules into .claude/rules/. The outputs persist in your project — they don’t disappear when the session ends.

Quick reference

Field	Value
Command	`/brewcode:convention`
Arguments	`[full\|conventions\|rules\|paths <p1,p2>]`
Model	opus
Tools	Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill

When to use

New team member onboarding — generate etalon docs once, share .claude/convention/ as the canonical style guide
Architecture drift prevention — run after a major refactor to re-anchor conventions to current code
Rules extraction — /brewcode:convention rules turns existing convention docs into .claude/rules/*.md entries
Focused module analysis — /brewcode:convention paths src/payments,src/billing scopes to changed modules only

Modes

Mode	Command	Phases	Prerequisites
`full` (default)	`/brewcode:convention`	P0–P8	None
`conventions`	`/brewcode:convention conventions`	P0–P7	None
`rules`	`/brewcode:convention rules`	P0, P7, P7.5, P8	`.claude/convention/` exists
`paths`	`/brewcode:convention paths src/a,src/b`	P0–P7 scoped	None

rules mode skips analysis entirely — it reads existing convention docs and runs the interactive rules extraction flow. Use it to refresh .claude/rules/ without re-scanning the whole project.

Examples

# Full analysis — detect stack, analyze all layers, generate docs, extract rules
/brewcode:convention

# Natural language also works
"extract conventions from this project"
"find etalon classes and create convention docs"

# Skip rules extraction — just generate the three convention documents
/brewcode:convention conventions

# Focus on two modules only (large projects with >1000 files)
/brewcode:convention paths src/payments,src/billing

# Rules-only pass on existing convention docs
/brewcode:convention rules

Flow

Stack + project scan (P0)
Detects primary stack (Java/Kotlin, TypeScript, Python, Rust, Go, or multi-stack) and scans source directories. If total files exceed 1000, warns and recommends paths mode. Sets up .claude/convention/ output directory.
Parallel layer analysis (P2 — 10 agents)
All agents spawn in a single message. Each covers a specific layer group: build config, utilities, REST endpoints, DI/services, external clients, data access, DTOs/records, DDL/config, test data, and test patterns. Inactive layers for the detected stack are skipped automatically.
Etalon selection (P3 — 1 architect agent)
Receives all 10 layer reports, scores candidates on pattern coverage, naming adherence, and anti-pattern count. Selects 1–2 etalon classes per layer. Resolves conflicts when the same class appears as a candidate for multiple layers.
Document generation (P4 — 3 parallel agents)
Produces three documents: reference-patterns.md (~300 lines, main code layers), testing-conventions.md (~150 lines, test layers), project-architecture.md (~200 lines, build/DDL layers). Each document includes etalon class tables, code patterns, and anti-pattern tables.
Text optimization + user review (P5–P6)
If text-optimizer (brewtools) is installed, three optimizer agents compact the documents in parallel. Then a summary with key etalons is presented — approve, revise (up to 2 iterations), or skip to rules extraction.
Rules extraction + CLAUDE.md update (P7–P7.5)
Anti-patterns become avoid rules; naming conventions and patterns become best-practice rules. Duplicate detection skips entries already covered at >70% similarity. Interactive batching presents 5–7 rules at a time for accept/reject. Optionally adds an etalon reference table to project CLAUDE.md.

Phase internals — agent prompts, layer table, error handling

Layer → agent mapping (P2)

#	Agent	Layers	Focus
1	architect	L1–L3	Build config, dependency management, code generation
2	architect	L4	@UtilityClass, static helpers, shared converters
3	architect	L5+L14	REST endpoints, security, config, caching
4	architect	L6+L9	DI patterns, @Transactional, domain services
5	architect	L7	Feign clients, external API integrations
6	architect	L8	JOOQ DSL, raw SQL, mappers, query patterns
7	architect	L10+L11	Records, @Value @Builder, naming conventions
8	architect	L12+L13	DDL scripts, config files, templates
9	tester	T1–T4	Test data, base classes, helpers, ExpectedData
10	tester	T5–T6	BDD style, assertion patterns, @ParameterizedTest

Active layers by stack

Stack	Active layers
java, kotlin	L1–L14, T1–T6 (all)
typescript	L1–L6, L8, L10–L11, L13–L14, T1–T3, T5–T6
python	L1–L2, L4–L6, L8, L10, L13–L14, T1–T3, T5–T6
rust	L1–L2, L4–L6, L8, L10–L11, T5
go	L1–L2, L4–L6, L8, L10, T5
multi-stack	Union of all detected
unknown	All layers — agent determines relevance per layer

Error handling

Condition	Action
No source files found	Exit: “No source files found for {STACK}“
`rules` mode without `.claude/convention/`	Exit: “Run `/brewcode:convention conventions` first”
>1000 source files	Warn user, suggest `paths` mode
Unknown stack	Continue with generic analysis
Agent timeout	Log warning, continue with available results
grepai unavailable	Fall back to Glob + Grep
Convention doc generation fails	Retry once, then present partial results

Output document paths

Document	Path	Lines
Main code layers	`.claude/convention/reference-patterns.md`	~300
Test layers	`.claude/convention/testing-conventions.md`	~150
Build / DDL layers	`.claude/convention/project-architecture.md`	~200

📄

Updating plugins

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