conventions

Conventions — Analyze Codebase & Build Convention Files

Analyzes the codebase and creates or updates 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
  tool-chains/              # persistent build/test/lint commands
    commands.yml            # verified project commands
  decisions/                # reusable architectural decisions
    [topic].md              # one file per decision (e.g., state-management.md)

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="team:codebase-researcher",
  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="team:codebase-researcher",
  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="team:codebase-researcher",
  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 2b: Generate project profile and tool-chains

From the structure researcher's findings, generate two operational files:

.conventions/tool-chains/commands.yml — verified build/test/lint commands:

build: {detected build command}
test: {detected test command}
lint: {detected lint command}
typecheck: {detected typecheck command}
format: {detected format command}

Run each command in a dry/check mode to verify it works before persisting. Skip commands that don't apply.

.project-profile.yml — project summary for cold-start optimization:

# Auto-generated by /conventions — do not edit manually
generated: {date}
stack:
  language: {language}
  framework: {framework}
  package_manager: {package manager}
  database: {database or "none"}
  key_libraries: [{list}]
structure:
  source: {src directory}
  tests: {test directory}
  api: {api routes directory}
  components: {components directory}
  pages: {pages directory}
conventions_version: {hash of .conventions/ content}

How /build uses .project-profile.yml:

• If profile exists and conventions_version matches current .conventions/ → skip codebase-researcher (cold-start eliminated)
• If profile is stale → re-dispatch codebase-researcher
• --fresh flag forces re-scan regardless of profile

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

Decisions — If reusable architectural decisions are visible in the codebase:

• State management approach, auth strategy, API design patterns
• Each file: context, decision, alternatives, consequences
• Only create for decisions that affect multiple files/modules — not one-off choices

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

Tool chains:
  [created/updated] .conventions/tool-chains/commands.yml

Decisions:
  [created] .conventions/decisions/state-management.md
  ...

Project profile:
  [created/updated] .project-profile.yml

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

Error Handling

Situation	Action
Researcher agent fails or returns empty	Re-dispatch with narrower scope (specific directory). If still fails, proceed with Glob/Grep output only.
Command verification fails (build/test/lint)	Skip unverifiable commands. Note in output: "Command not verified: {cmd}."
Multiple researchers fail	Proceed with available data. Mark "DEGRADED RESEARCH" in output.
Write fails for .conventions/ files	Output file contents directly to the user for manual creation.
Project has no package.json or recognizable build system	Skip tool-chains/commands.yml creation. Note: "No build system detected."

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)