conventions

What this skill does

# Conventions — Analyze Codebase & Build Convention Files

You analyze the codebase and create or update the `.conventions/` directory. This directory is the **single source of truth** for project patterns — it encodes taste once, so every agent (and human) follows the same conventions.

## Target Structure

```
.conventions/
  gold-standards/           # 20-30 line exemplary code snippets
    [pattern-name].tsx/ts   # one file per pattern (form, api-endpoint, hook, etc.)
  anti-patterns/            # what NOT to do (with code examples)
    [avoid-something].md    # one file per anti-pattern
  checks/                   # automated pass/fail rules
    naming.md               # naming conventions (regex patterns, examples)
    imports.md              # allowed/forbidden import patterns
```

## How It Works

### Step 1: Check current state

```
Glob(".conventions/**/*")
```

- If `.conventions/` exists → this is an **update** (add missing patterns, refresh stale ones)
- If `.conventions/` does not exist → this is a **bootstrap** (create from scratch)

### Step 2: Dispatch researchers (parallel)

Spawn 3 researchers in parallel to scan the codebase:

```
Task(
  subagent_type="Explore",
  prompt="Analyze this project's STRUCTURE and STACK.
  Return: framework, language, package manager, DB, key libraries,
  directory structure, where API routes/pages/components live.
  Be specific — file paths and command names. Under 30 lines."
)

Task(
  subagent_type="Explore",
  prompt="Find the 5-7 BEST example files in this codebase — files that represent
  'how things are done here'. Look for:
  - A well-structured UI component
  - An API endpoint / router
  - A custom hook
  - A form component
  - A test file
  - A database query / migration
  For each: return the file path, what pattern it shows, and the FULL file content.
  Skip patterns that don't exist in this project."
)

Task(
  subagent_type="Explore",
  prompt="Analyze NAMING CONVENTIONS and IMPORT PATTERNS in this codebase.
  Check:
  - File naming: kebab-case? camelCase? PascalCase? (check src/ files)
  - Function/variable naming: camelCase? snake_case?
  - Component naming: PascalCase?
  - DB tables/columns: snake_case? camelCase?
  - API endpoints: /kebab-case? /camelCase?
  - Import patterns: what's imported from where, any barrel exports, any forbidden imports
  - Design system: what UI library, any wrapper components
  Return specific patterns with regex examples where possible. Under 40 lines."
)
```

### Step 3: Build conventions

From researcher findings, create the files:

**Gold standards** — For each pattern found by the reference researcher:
- Extract the BEST 20-30 lines that demonstrate the pattern
- Strip implementation-specific details, keep the structural skeleton
- Add a 2-line comment at the top: what this file demonstrates and what to pay attention to
- File name = pattern name in kebab-case (e.g., `api-endpoint.ts`, `form-component.tsx`)

**Anti-patterns** — Look for:
- Inconsistencies found by researchers (some files do X, others do Y → the minority is an anti-pattern)
- Common mistakes visible in the codebase (raw HTML where design system should be used, direct DB calls where ORM should be used)
- Each anti-pattern file: short description, BAD example, GOOD example

**Checks** — From naming researcher:
- `naming.md`: file naming, function naming, component naming, DB naming — with regex patterns and examples
- `imports.md`: what should be imported from where, forbidden imports

### Step 4: Write files

If **bootstrap** (no `.conventions/` yet):
- Create the full directory structure
- Write all discovered gold standards, anti-patterns, and checks

If **update** (`.conventions/` already exists):
- Read existing files first
- Add new patterns that weren't covered
- Update patterns that have drifted from what the codebase actually does
- Do NOT delete existing files — only add or update
- Report what was added/changed

### Step 5: Report

```
══════════════════════════════════════════════════
CONVENTIONS {CREATED / UPDATED}
══════════════════════════════════════════════════

Gold standards:
  [created/updated] .conventions/gold-standards/api-endpoint.ts
  [created/updated] .conventions/gold-standards/form-component.tsx
  ...

Anti-patterns:
  [created] .conventions/anti-patterns/avoid-inline-styles.md
  ...

Checks:
  [created/updated] .conventions/checks/naming.md
  [created/updated] .conventions/checks/imports.md

Total: N files created, M files updated
══════════════════════════════════════════════════
```

## Rules

- Gold standards are **20-30 lines max** — short enough to include in agent prompts as few-shot examples
- Every gold standard has a **2-line header comment** explaining what it demonstrates
- Anti-patterns always show **BAD → GOOD** comparison
- Checks use **regex patterns** where possible for automated verification
- Do NOT invent patterns — only document what actually exists in the codebase
- If the codebase is inconsistent (50/50 split), pick the better pattern and note the inconsistency in an anti-pattern file
- Skip categories that don't apply (no DB? skip DB gold standard)

## Reference Files

- **`references/examples.md`** — Example convention files showing the expected format and quality level for gold standards, anti-patterns, and checks. Read this before generating convention files to ensure consistent quality and format.