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:

# 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:

# 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

[Actual example from codebase]

Logging Pattern

[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

[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)

[Real example from codebase that exemplifies the patterns]

Anti-pattern (avoid this)

[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"