name: style-guide
description: Analyze a codebase to extract its conventions, patterns, and style. Spawns specialized analyzer agents that each focus on one aspect (structure, naming, patterns, testing, frontend). Generates a comprehensive style guide that other skills can reference. Use when starting work on an unfamiliar codebase, or to create explicit documentation of implicit conventions.

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

```[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:

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"