convention — extract code patterns

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–P6	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.

conventions mode stops at P6. P7 is Rules Organization, the phase that writes .claude/rules/, so “skip rules extraction” means the run must end one phase earlier — a skip gate at the P7 header enforces it. Only conventions mode leaves .claude/rules/ untouched; full and paths both reach P7.

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

Delegation

One subagent = ONE bounded unit — here, ONE layer analysis or ONE document: roughly 5 files, roughly 10 steps. Anything bigger is split into N tasks fired in ONE message. That sizing rule is exactly why P2 runs as 10 layer agents and P4 as 3 document agents rather than one agent owning the whole codebase.

The contract binds every Task spawn in the skill — P2, P3, P4, P5 and P7.4. 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

A P2 layer agent is therefore told: the stack was already detected in P1 (do not re-detect), nine siblings own the other layers (do not report on theirs), and P3 parses its tables as-is — so it must return file paths and scored candidates in the exact column shape, not prose. The same brief is carried in references/rules-guide.md for the P7.4 bc-rules-organizer spawn.

Phase internals — agent prompts, layer table, error handling

Layer → agent mapping (P2)

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