style-guide

# Style Guide: Multi-Agent Convention Analyzer

Spawns specialized analyzer agents to discover and document a codebase's conventions, patterns, and style. Each agent focuses on one aspect and explores independently.

**Use this when:**
- Starting work on an unfamiliar codebase
- You want AI to match existing patterns exactly
- Making implicit conventions explicit
- Before running feature-council on a new project

## Output

Generates `.claude/codebase-style.md` - a comprehensive style guide that can be referenced by other skills and agents.

---

## CRITICAL: Language-Agnostic Design

Each analyzer:
1. **Discovers the language/framework first** - Don't assume anything
2. **Finds relevant files itself** - Uses Glob, Grep, LS to explore
3. **Extracts patterns from what exists** - Not what "should" exist
4. **Reports findings in structured format** - For synthesis

This works for: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, or any other language.

---

## Workflow

### Step 0: Check for Existing Style Guide

**Before starting, check if `.claude/codebase-style.md` already exists.**

If it exists, ask the user:

```
A style guide already exists for this codebase (.claude/codebase-style.md).

Options:
1. View the existing style guide
2. Regenerate it (will overwrite)
3. Cancel

What would you like to do?
```

Only proceed with analysis if the user chooses to regenerate.

### Step 1: Quick Language/Framework Detection

Before spawning analyzers, do a quick check:

```bash
# Check for common indicators
ls -la  # Look for package.json, requirements.txt, go.mod, Cargo.toml, etc.
```

Note the primary language(s) and framework(s) detected. Pass this context to analyzers.

### Step 2: Spawn Analyzer Agents IN PARALLEL

Spawn ALL analyzers simultaneously with the same context:

```
CONTEXT: [Primary language/framework detected in Step 1]
TASK: Analyze the codebase for [YOUR SPECIALTY] conventions and patterns.

Return a structured report of what you find.
```

```
Task(agent: "style-structure", prompt: "CONTEXT: [lang/framework]. Analyze folder structure, file organization, and module patterns.")
Task(agent: "style-naming", prompt: "CONTEXT: [lang/framework]. Analyze naming conventions for files, variables, functions, classes, constants.")
Task(agent: "style-patterns", prompt: "CONTEXT: [lang/framework]. Analyze code patterns: error handling, data access, configuration, logging.")
Task(agent: "style-testing", prompt: "CONTEXT: [lang/framework]. Analyze testing patterns: file locations, naming, structure, assertions.")
Task(agent: "style-frontend", prompt: "CONTEXT: [lang/framework]. Analyze frontend/UI patterns if applicable: components, styling, state. If not a frontend project, report 'N/A'.")
```

**ALL agents spawn in the SAME batch - parallel execution.**

### Step 3: Track Progress

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                   ANALYZER PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☐ Structure Analyzer - Working...
☐ Naming Analyzer - Working...
☐ Patterns Analyzer - Working...
☐ Testing Analyzer - Working...
☐ Frontend Analyzer - Working...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Update as each completes.

### Step 4: Collect and Synthesize

Each analyzer returns structured findings. Merge into a unified style guide.

**Handle conflicts:** If analyzers disagree (rare), note both patterns.

### Step 5: Generate Style Guide

Create `.claude/codebase-style.md`:

```markdown
# Codebase Style Guide
> Auto-generated by codebase-style skill on [DATE]
> Primary: [Language] | Framework: [Framework] | [X] files analyzed

---

## Project Structure

[From style-structure analyzer]

### Directory Layout
- `src/` - Source code
- `tests/` - Test files
- ...

### File Organization Pattern
[Description with examples]

---

## Naming Conventions

[From style-naming analyzer]

| Element | Convention | Example |
|---------|------------|---------|
| Files | [pattern] | `user_service.py` |
| Classes | [pattern] | `UserService` |
| Functions | [pattern] | `get_user_by_id` |
| Variables | [pattern] | `user_count` |
| Constants | [pattern] | `MAX_RETRIES` |

---

## Code Patterns

[From style-patterns analyzer]

### Error Handling
```[language]
[Actual example from codebase]
```

### Data Access Pattern
```[language]
[Actual example from codebase]
```

### Logging Pattern
```[language]
[Actual example from codebase]
```

### Configuration Pattern
[Description]

---

## Testing Patterns

[From style-testing analyzer]

### Test Location
[Where tests live relative to source]

### Test Naming
[Convention for test files and functions]

### Test Structure
```[language]
[Actual example from codebase]
```

### Assertion Style
[What assertion library/style is used]

---

## Frontend Patterns (if applicable)

[From style-frontend analyzer, or "N/A - Not a frontend project"]

### Component Structure
[Pattern]

### Styling Approach
[CSS-in-JS, Tailwind, CSS Modules, etc.]

### State Management
[Pattern]

---

## Quick Reference

| Category | Convention |
|----------|------------|
| File naming | [pattern] |
| Function naming | [pattern] |
| Error handling | [pattern name] |
| Test files | [location pattern] |
| Imports | [order/style] |

---

## Examples to Follow

### Good Example (matches codebase style)
```[language]
[Real example from codebase that exemplifies the patterns]
```

### Anti-pattern (avoid this)
```[language]
[What NOT to do based on codebase conventions]
```
```

### Step 6: Save and Report

1. Create `.claude/` directory if needed
2. Write `.claude/codebase-style.md`
3. Report summary to user

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 CODEBASE STYLE ANALYSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Analysis Summary

| Analyzer | Files Checked | Patterns Found |
|----------|---------------|----------------|
| Structure | [N] | [N] |
| Naming | [N] | [N] |
| Patterns | [N] | [N] |
| Testing | [N] | [N] |
| Frontend | [N or N/A] | [N or N/A] |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Generated: .claude/codebase-style.md

Key Findings:
- Language: [Primary language]
- Framework: [If detected]
- Naming: [Quick summary, e.g., "snake_case for files, PascalCase for classes"]
- Structure: [Quick summary, e.g., "Feature-based organization"]
- Testing: [Quick summary, e.g., "pytest, tests/ directory"]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 This style guide will be referenced by other skills to ensure
   consistent code that matches your codebase conventions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Agents

5 specialized analyzer agents in `agents/` directory:

| Agent | Focus | What It Looks For |
|-------|-------|-------------------|
| `style-structure` | Organization | Folders, modules, file grouping, imports |
| `style-naming` | Naming | Files, variables, functions, classes, constants |
| `style-patterns` | Code patterns | Error handling, data access, logging, config |
| `style-testing` | Testing | Location, naming, structure, assertions |
| `style-frontend` | Frontend/UI | Components, styling, state (if applicable) |

All analyzers:
- Explore the codebase independently
- Language-agnostic (detect, don't assume)
- Return structured findings
- Use Read, Grep, Glob, LS tools

---

## Integration with Other Skills

The generated `.claude/codebase-style.md` can be referenced by:

- **feature-council** - Agents can check style guide before implementing
- **debug-council** - Ensure fixes match codebase patterns
- **parallel-builder** - Each builder follows the style guide

To explicitly include:
```
Before implementing, read .claude/codebase-style.md to understand codebase conventions.
```

---

## When to Re-run

Run `codebase-style` again when:
- Major refactoring has occurred
- New patterns have been introduced
- Moving to a new framework/library
- Style guide feels outdated

---

## Triggers

```
"style guide"
"generate style guide"
"analyze codebase style"
"what are the conventions in this codebase"
"codebase conventions"
"analyze this codebase"
"extract code style"
"document coding patterns"
```