Brewcode:Convention

<instructions>

Mode Detection

Arguments: $ARGUMENTS

---

P0: Mode + Stack Detection

Parse $ARGUMENTS for mode keyword. Default = full. For paths mode: split comma-separated paths after keyword.

Step 0.1: Detect Stack

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/convention.sh" detect-stack && echo "---DETECT-OK---" || echo "---DETECT-FAILED---"

Output: JSON {"stacks":[...],"primary":"...","build_file":"...","modules":[...]}.

Step 0.2: Scan Project

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/convention.sh" scan && echo "---SCAN-OK---" || echo "---SCAN-FAILED---"

Output: JSON with source_dirs, file_counts, modules, total_files.

If total_files > 1000: warn user, suggest paths mode.

Step 0.3: Setup Convention Directory

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/convention.sh" setup && echo "---SETUP-OK---" || echo "---SETUP-FAILED---"

STOP if FAILED -- cannot proceed without output directory.

Step 0.4: Validate (rules mode only)

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/convention.sh" validate && echo "---VALID---" || echo "---INVALID---"

If rules mode + INVALID -- exit: "Run /brewcode:convention conventions first."

---

P1: Load Layer Definitions

Read references/analysis-layers.md. Filter layers by detected stack from P0. For paths mode: further filter by specified paths — match layer file patterns against provided paths. Build ACTIVE_LAYERS for P2.

---

P2: Parallel Layer Analysis (10 agents, ONE message)

Dynamic Agent Resolution

Before spawning agents, check for project team agents: 1. If .claude/teams/ exists — read team.md for agent roster with domains 2. If team has architecture/testing domain agents — prefer over plugin architect/tester 3. Priority: team agent > project agent > plugin agent > system agent 4. If agent refuses (Task Acceptance Protocol) — re-delegate to suggested colleague (max 2 retries)

Spawn ALL agents in a SINGLE message. Skip agents for inactive layers (filtered in P1).

Per-agent prompt template:

Analyze {LAYERS} in the project.
Stack: {DETECTED_STACK}

Layer definitions:
{LAYER_CRITERIA_FROM_ANALYSIS_LAYERS_MD}

Use grepai_search FIRST for file discovery, then Glob/Grep for verification.
For paths mode, scope analysis to: {SCOPED_PATHS}

Output format:

## Etalon Candidates
| Class | Path | Why Etalon | Score (1-10) |

## Naming Conventions
| Pattern | Example | Frequency |

## Directory Rules
| Rule | Path Pattern |

## Patterns (code snippets, max 3, 5-15 lines each)
### Pattern Name
` ```code```
Why: explanation

## Anti-Patterns
| Class | Problem | Fix |

---

P3: Etalon Selection (1 architect agent)

After all P2 agents complete, spawn 1 architect agent with combined results.

Prompt:

Receive analysis from 10 layer-analysis agents. Select 1-2 etalons per layer based on:
- Highest score from candidates
- Most complete pattern coverage
- Best naming convention adherence
- Fewest anti-patterns

If same class appears as etalon for multiple layers, assign to most relevant layer.

Input: {ALL_10_AGENT_OUTPUTS}

Output:
## Final Etalon Summary
| Layer | Etalon Class | Path | Score | Role |

## Conflict Resolutions
| Class | Claimed By | Assigned To | Reason |

## Coverage Gaps
| Layer | Issue | Recommendation |

---

P4: Document Generation (3 developer agents, PARALLEL)

Read references/conventions-guide.md for templates. Spawn 3 developer agents in ONE message.

Per-agent prompt:

Generate {DOCUMENT_NAME} following the template from conventions-guide.
Target structure: {TEMPLATE_FROM_CONVENTIONS_GUIDE}
Etalon selection: {P3_ETALON_SUMMARY}
Layer analyses: {RELEVANT_P2_OUTPUTS}
Stack: {DETECTED_STACK}
Write to: .claude/convention/{filename}.md
Structure: organized by layer -- each with Etalon Classes table, Patterns (5-15 lines each, max 3/layer), Anti-Patterns table, Quick Reference table at end.
Target: ~{LINE_COUNT} lines.

---

P5: Text Optimization

IF text-optimizer agent is available (brewtools installed):

Spawn 3 text-optimizer agents in ONE message (medium mode):

Task(subagent_type="text-optimizer", prompt="FIRST: Read $BT_PLUGIN_ROOT/skills/text-optimize/references/rules-review.md. THEN optimize .claude/convention/reference-patterns.md using medium mode. Output report with metrics.")
Task(subagent_type="text-optimizer", prompt="FIRST: Read $BT_PLUGIN_ROOT/skills/text-optimize/references/rules-review.md. THEN optimize .claude/convention/testing-conventions.md using medium mode. Output report with metrics.")
Task(subagent_type="text-optimizer", prompt="FIRST: Read $BT_PLUGIN_ROOT/skills/text-optimize/references/rules-review.md. THEN optimize .claude/convention/project-architecture.md using medium mode. Output report with metrics.")

ELSE (brewtools not installed -- fallback):

Read ${CLAUDE_SKILL_DIR}/../convention/references/text-optimize-fallback.md for compact rules. Apply rules manually to all 3 generated documents.

---

P6: User Review

Present summary:

## Convention Documents Generated

| Document | Lines | Key Etalons (top 5) |
|----------|-------|---------------------|
| reference-patterns.md | {N} | {class1}, {class2}, ... |
| testing-conventions.md | {N} | {class1}, {class2}, ... |
| project-architecture.md | {N} | {file1}, {file2}, ... |

AskUserQuestion options:

• A: Approve all -- continue to rules extraction
• B: Revise -- provide feedback (max 2 iterations, re-run P5 after edits)
• C: Skip to rules -- jump to P7

---

P7: Rules Organization

Read references/rules-guide.md for interactive flow.

Step 7.1: Extract Rule Candidates

Step 7.2: Duplicate Detection

Read existing .claude/rules/*.md files.

Step 7.3: Interactive Batching

Present 5-7 rules per batch via AskUserQuestion:

## Rules Batch {N}/{TOTAL}

| # | Type | Rule | Target File |
|---|------|------|-------------|
| 1 | avoid | ... | {prefix}-avoid.md |
| 2 | bp | ... | {prefix}-best-practice.md |

Options: Accept all | Select by number | Skip batch | Stop

Step 7.4: Spawn bc-rules-organizer

Spawn bc-rules-organizer per references/rules-guide.md Section 4. Pass {ACCEPTED_RULES_JSON} from interactive batching.

---

P7.5: Update Project CLAUDE.md

AskUserQuestion: "Update project CLAUDE.md with etalon summary table + convention references?"

• A: Yes -- add etalon table + lazy-load refs
• B: No -- skip

If yes: 1. Read project CLAUDE.md 2. Find or create ## Reference Patterns & Etalon Classes section 3. Add/update:

## Reference Patterns & Etalon Classes
> **Full doc**: `.claude/convention/reference-patterns.md` (lazy-load when writing new code)

| When writing... | Copy from (etalon) |
|-----------------|---------------------|
| {role} | `{ClassName}` -- {key traits} |

### DTO Evolution (prefer top)
1. **{preferred}** -- PREFER for new code
2. **{established}** -- OK for complex entities
3. **{legacy}** -- AVOID

4. Use Edit tool -- preserve all existing CLAUDE.md content.

---

P8: Output Summary

## Convention Analysis Complete

| Document | Path | Lines | Key Etalons |
|----------|------|-------|-------------|
| reference-patterns.md | `.claude/convention/reference-patterns.md` | {N} | {list} |
| testing-conventions.md | `.claude/convention/testing-conventions.md` | {N} | {list} |
| project-architecture.md | `.claude/convention/project-architecture.md` | {N} | {list} |

| When writing... | Copy from... |
|-----------------|-------------|
| {condensed top etalons} | {class} |

| Metric | Value |
|--------|-------|
| Rules extracted | {X} |
| Rules applied | {Y} |
| Duplicates skipped | {Z} |

Next Steps: Review `.claude/convention/` | `/brewcode:convention rules` to re-extract later | `/brewcode:convention paths src/new-module` for new modules

---

Error Handling

</instructions>

Convention

Analyzes a project codebase to extract etalon (reference) classes, coding patterns, and architecture conventions by layer. Produces structured documentation in .claude/convention/ and organizes extracted rules into .claude/rules/.

Quick Start

/brewcode:convention

Runs the full pipeline: detect stack, analyze all layers, generate convention docs, optimize text, review with user, extract rules, update CLAUDE.md.

Modes

Examples

Good Usage

# First-time full analysis of the entire project
/brewcode:convention

# Analyze only specific modules after adding a new service
/brewcode:convention paths src/payment,src/billing

# Regenerate conventions without touching rules
/brewcode:convention conventions

# Refresh rules after manually editing convention docs
/brewcode:convention rules

# Scope analysis to test directories only
/brewcode:convention paths src/test,src/integrationTest

Common Mistakes

# Running rules mode before generating convention docs -- will fail
/brewcode:convention rules
# Fix: run `/brewcode:convention conventions` first, then `/brewcode:convention rules`

# Providing paths without the keyword -- interpreted as full mode
/brewcode:convention src/main
# Fix: always prefix with `paths` keyword
/brewcode:convention paths src/main

# Using spaces instead of commas for multiple paths
/brewcode:convention paths src/a src/b
# Fix: comma-separated, no spaces
/brewcode:convention paths src/a,src/b

Phases

Output

.claude/convention/
  reference-patterns.md       # Main code layers (L4-L11, L14): etalons, patterns, anti-patterns
  testing-conventions.md      # Test layers (T1-T6): test etalons, assertion conventions
  project-architecture.md     # Build layers (L1-L3, L12-L13): build config, deps, migrations

.claude/rules/
  {prefix}-avoid.md           # Extracted anti-patterns as avoid rules
  {prefix}-best-practice.md   # Extracted best practices as rules

Rules extraction uses a 3-Check Deduplication Protocol:

Tips

• When to run: After initial project setup, after major refactoring, or when onboarding new team conventions. Re-run rules mode after manually editing convention docs.
• Large projects (>1000 files): The skill warns automatically. Use paths mode to scope analysis to specific modules for faster, more focused results.
• Iterative workflow: Start with conventions mode to review docs first. Once satisfied, run rules mode separately. This gives you full control over what gets promoted to rules.
• Supported stacks: Java, Kotlin, TypeScript, Python, Rust, Go, and multi-stack projects. Unknown stacks get generic analysis across all layers.

Documentation

Full docs: convention

Analysis Layers

20 layers (14 main + 6 test) for project convention extraction.

Main Layers (L1–L14)

L6/L9 Overlap: L9 (Business Logic) applies only when project has explicit domain/service/, rules/, engine/ packages (DDD structure). Otherwise, merge L9 analysis into L6 (Services) findings.

Test Layers (T1–T6)

Conventions Guide

Document templates and generation rules for convention output files.

1. General Rules

2. reference-patterns.md Template (~300 lines)

Structure follows .claude/convention/reference-patterns-example.md if available in workspace (optional -- not included in plugin distribution).

# Reference Patterns & Etalon Classes

> Comprehensive reference for developers. Organized by layer with etalon classes and code snippets.

## {N}. {Layer Name} Layer

### Etalon Classes

| Aspect | Etalon | Path |
|--------|--------|------|
| {aspect} | `{ClassName}` | `{relative/path}` |

### Patterns

**{N}. {Pattern Name}:** {1-line description}. Etalon: `{ClassName}`

// 5-15 lines of actual code from etalon class

| Variant | Usage | Etalon |
|---------|-------|--------|
| {approach} | {when to use} | `{ClassName}` |

### Anti-Patterns (Avoid)

| Class | Problem | Fix |
|-------|---------|-----|
| `{ClassName}` | {what's wrong} | {how to fix} |

## Quick Reference: Top Etalons by Role

| When writing... | Copy from... |
|-----------------|-------------|
| New {component type} | `{EtalonClass}` |

Layers to Include

Quality Rules

3. testing-conventions.md Template (~150 lines)

# Testing Conventions & Etalon Classes

> Test patterns reference. Organized by test infrastructure layer.

## {N}. {Test Layer Name}

### Etalon Classes

| Aspect | Etalon | Path |
|--------|--------|------|
| {aspect} | `{ClassName}` | `{relative/path}` |

### Patterns

**{N}. {Pattern Name}:** {1-line description}. Etalon: `{ClassName}`

// 5-15 lines of test code

| Pattern | When | Example |
|---------|------|---------|
| {pattern} | {scenario} | `{ClassName}` |

## Quick Reference: Test Etalons

| When writing... | Copy from... |
|-----------------|-------------|
| New integration test | `{TestClass}` |
| New test data | `{ExpectedDataClass}` |

Layers to Include (T1-T6)

4. project-architecture.md Template (~200 lines)

# Project Architecture & Build Conventions

> Build, dependency, codegen, migration, and structural conventions.

## 1. Build Configuration

### Etalon Files

| Aspect | File | Path |
|--------|------|------|
| {aspect} | `{filename}` | `{relative/path}` |

### Build Patterns
- {pattern description}

## 2. Dependency Management

| Strategy | Example | When |
|----------|---------|------|
| BOM import | `spring-boot-dependencies` | Framework deps |
| Property | `{lib}.version` | Direct deps |

| Category | Libraries | Version Source |
|----------|-----------|----------------|
| {category} | {libs} | {source} |

## 3. Code Generation

| Generator | Config | Output | Trigger |
|-----------|--------|--------|---------|
| {name} | `{config file}` | `{output dir}` | {when runs} |

## 4. Migrations

| Tool | Location | Naming | Format |
|------|----------|--------|--------|
| {tool} | `{path}` | `{pattern}` | {SQL/XML/YAML} |

### Schema Management Rules
- {rule}

## 5. Directory Structure

| Module | Package Structure |
|--------|-------------------|
| {module} | `{package layout}` |

src/main/java/{base}/ configuration/ controllers/ services/ repositories/ ...

## 6. Naming Conventions

| Entity Type | Pattern | Example |
|-------------|---------|---------|
| Controller | `*Controller` | `HistoryController` |
| Service | `*Service` | `ProfileKeyCloakService` |
| Repository | `*Repository` | `LoadsHistoryRepository` |

## 7. Constraints

| Constraint | Details |
|------------|---------|
| {constraint} | {explanation} |

Layers to Include

5. Quality Checklist

Rules Guide

Rule extraction, deduplication, and interactive organization from convention docs.

1. Rule Extraction Flow

Convention docs → scan sections → identify patterns/anti-patterns → classify → format

Extraction Priority

2. Duplicate Detection

Comparison process: read all .claude/rules/*.md → compare each candidate against ALL existing entries semantically (same intent = duplicate) → consider: same class, same pattern, same "Instead" suggestion.

When merging (40-70% similar): keep existing rule number, expand "Instead" if new info available, add "Why" if missing, do NOT create duplicate entry.

3. Interactive Batching (AskUserQuestion)

Present 5-7 rules per batch:

## Rules Batch {N}/{TOTAL}

| # | Type | Rule | Target File |
|---|------|------|-------------|
| 1 | avoid | `@Data` on entities -- use `@Value @Builder` | {stack}-avoid.md |
| 2 | bp | `@RequiredArgsConstructor` + final for DI | {stack}-best-practice.md |
| 3 | avoid | Mutable DTOs -- use records | {stack}-avoid.md |
| 4 | bp | Three-class test structure (Test+Expected+Requests) | {stack}-best-practice.md |
| 5 | bp | `.as()` on every AssertJ assertion | {stack}-best-practice.md |

Options: Accept all | Select by number (e.g., "1,3,5") | Skip batch | Stop

Batching Strategy

Target File Selection

4. bc-rules-organizer Spawn

After all batches processed, spawn with accepted rules:

Task(subagent_type="bc-rules-organizer", prompt="
Update PROJECT .claude/rules/ -- NEVER ~/.claude/rules/

Plugin templates: $BC_PLUGIN_ROOT/templates/rules/
Validation: bash \"$BC_PLUGIN_ROOT/skills/rules/scripts/rules.sh\" validate
Create missing: bash \"$BC_PLUGIN_ROOT/skills/rules/scripts/rules.sh\" create

Accepted rules:
{ACCEPTED_RULES_JSON}

Format each rule in table row:
avoid.md: | # | Avoid | Instead | Why |
best-practice.md: | # | Practice | Context | Source |

Source column: 'convention' for all extracted rules.
Check for duplicates with existing rules.
")

5. CLAUDE.md Update Flow

1. AskUserQuestion: "Add etalon quick-reference table to project CLAUDE.md?"

• A: "Yes -- add etalon table + lazy-load refs"
• B: "No -- skip CLAUDE.md update"

2. If yes: read project CLAUDE.md → find/create ## Reference Patterns & Etalon Classes section → add/update:

## Reference Patterns & Etalon Classes
> **Full doc**: `.claude/convention/reference-patterns.md` (lazy-load when writing new code)

| When writing... | Copy from (etalon) |
|-----------------|---------------------|
| New controller | `{ClassName}` -- {key traits} |
| New repository | `{ClassName}` + `{SupportClass}` -- {key traits} |
| New service | `{ClassName}` -- {key traits} |

### DTO Evolution (prefer top)
1. **{preferred style}** -- PREFER for new code
2. **{established style}** -- OK for complex entities
3. **{legacy style}** -- AVOID

3. Use Edit tool -- preserve ALL existing CLAUDE.md content. Keep concise: summary table + lazy-load ref only, no full patterns.

Text Optimization: Compact Rules (Fallback)

Use when brewtools is NOT installed and text-optimizer agent is unavailable.

For full rules: install brewtools plugin and use text-optimizer agent.

Key Rules by Category

C -- Claude Behavior

T -- Token Efficiency

S -- Structure

R -- Reference Integrity

P -- Perception

L -- LLM Comprehension

Self-Apply Instructions

1. Read entire text to understand context 2. Apply T.6 first (remove filler) -- easiest wins 3. Apply T.1 (convert prose lists -> tables where applicable) 4. Apply T.2-T.4 (compress remaining lists/code) 5. Apply S.2 (imperative form) 6. Verify: no information loss, all refs valid 7. Target: 20-40% token reduction

Anti-Patterns

Compression Ratios