---

name: code-standards-analyzer description: Coding standards discovery and documentation expert. Analyzes codebase to detect naming conventions, patterns, anti-patterns, and best practices. Generates or updates coding standards documentation in .specweave/docs/internal/governance/. Detects ESLint/Prettier configs, analyzes TypeScript/JavaScript patterns, finds security issues, and creates evidence-based standards with confidence levels. Activates for analyze coding standards, discover conventions, code style analysis, detect patterns, coding guidelines, what are the standards, code quality check, naming conventions, linting rules, best practices analysis, standards audit, code review standards, detect anti-patterns. allowed-tools: Read, Grep, Glob, Bash, Write, Edit

Code Standards Analyzer

Purpose: Discover, document, and maintain coding standards from existing codebases using evidence-based analysis.

Philosophy: Standards should reflect REALITY (what the code actually does) not ASPIRATIONS (what we wish it did). Measure, then document.

---

When to Use

Primary Use Cases:

1. Brownfield Onboarding - "What are this project's coding conventions?"
2. Standards Audit - "Are we following our declared standards?"
3. New Contributor Onboarding - "Teach me the project patterns"
4. Living Documentation - "Keep standards in sync with codebase"
5. Greenfield Setup - "Initialize standards from best practices"

Activation Triggers

Keywords: analyze coding standards, discover conventions, code style, detect patterns, coding guidelines, what are the standards, naming conventions, best practices, code quality, standards audit, anti-patterns

User Requests:

• "What are the coding standards for this project?"
• "Analyze the codebase and document our conventions"
• "Check if we're following our declared standards"
• "Find anti-patterns in the code"
• "Generate coding standards documentation"
• "What naming conventions does this project use?"

---

Capabilities

1. Explicit Standards Discovery (Fast - 5 seconds)

• ✅ Detect existing .specweave/docs/internal/governance/coding-standards.md
• ✅ Parse ESLint configuration (.eslintrc.json, .eslintrc.js)
• ✅ Parse Prettier configuration (.prettierrc, .prettierrc.json)
• ✅ Parse TypeScript configuration (tsconfig.json)
• ✅ Parse EditorConfig (.editorconfig)
• ✅ Extract standards from CLAUDE.md, CONTRIBUTING.md

2. Implicit Standards Detection (Medium - 30 seconds)

• ✅ Naming convention analysis (variables, functions, classes, constants)
• ✅ Import pattern detection (extensions, ordering, aliasing)
• ✅ Function characteristics (avg length, max length, arrow vs regular)
• ✅ Type safety analysis (any usage, interface vs type preference)
• ✅ Error handling patterns (try/catch usage, custom errors)
• ✅ Comment style analysis
• ✅ File organization patterns

3. Anti-Pattern Detection (Fast - 15 seconds)

• 🚨 console.* usage in production code
• 🚨 Hardcoded secrets (API keys, passwords)
• 🚨 any type overuse
• 🚨 Large files (>500 lines)
• 🚨 Long functions (>100 lines)
• 🚨 Missing error handling
• 🚨 N+1 query patterns
• 🚨 Security vulnerabilities

4. Documentation Generation (Fast - 10 seconds)

• ✅ Generate standards document with examples
• ✅ Include statistical confidence levels
• ✅ Extract real code examples from codebase
• ✅ Highlight inconsistencies and conflicts
• ✅ Provide actionable recommendations
• ✅ Link to violating files

---

Analysis Process

Phase 1: Explicit Standards (5 seconds)

Sources Checked:

1. .specweave/docs/internal/governance/coding-standards.md (HIGH confidence)
2. CLAUDE.md (HIGH confidence - AI instructions)
3. .eslintrc.json (ENFORCED by tooling)
4. .prettierrc (ENFORCED by tooling)
5. tsconfig.json (ENFORCED by compiler)
6. .editorconfig (ENFORCED by editor)
7. CONTRIBUTING.md (MEDIUM confidence - may be outdated)

Output:

## Explicit Standards Found

✅ .eslintrc.json (ENFORCED - ESLint active)
✅ .prettierrc (ENFORCED - Prettier active)
✅ tsconfig.json (ENFORCED - TypeScript compiler)
✅ CLAUDE.md (HIGH - AI development rules)
⚠️  CONTRIBUTING.md (MEDIUM - human guidelines)
❌ No .specweave/docs/internal/governance/coding-standards.md

Phase 2: Implicit Standards (30 seconds)

Analysis Performed:

• Scan src/**/*.{ts,js,tsx,jsx} files
• Parse Abstract Syntax Trees (AST)
• Calculate statistical patterns
• Identify dominant conventions

Example Output:

## Detected Patterns

### Naming Conventions (Confidence: 95%)
- Variables: camelCase (1,234 samples, 98% compliance)
- Functions: camelCase (567 samples, 100% compliance)
- Classes: PascalCase (89 samples, 100% compliance)
- Constants: UPPER_SNAKE_CASE (234 samples, 92% compliance)
  ⚠️ 8% use camelCase (inconsistency detected)

### Import Patterns (Confidence: 100%)
- Extensions: .js suffix required (100% compliance)
- Order: external → internal → types (87% compliance)

### Function Characteristics
- Average length: 35 lines
- Max length: 156 lines (src/core/analyzer.ts:45)
- Style: Arrow functions (78%), Regular (22%)

### Type Safety (Confidence: 85%)
- any usage: 12 instances (REVIEW NEEDED)
- Preference: Interfaces (89%) over Types (11%)

Phase 3: Anti-Pattern Detection (15 seconds)

Checks Performed:

• Security: Hardcoded secrets, SQL injection risks
• Maintainability: Large files, complex functions
• Performance: N+1 queries, missing caching
• Robustness: Missing error handling

Example Output:

## Issues Found

### 🔴 CRITICAL (2 issues)
- Hardcoded Secrets: 2 instances
  - src/config/api.ts:12
  - src/utils/auth.ts:45
  Fix: Use process.env variables

### 🟠 HIGH (5 issues)
- console.* Usage: 5 instances in src/
  - src/core/analyzer.ts:67
  Fix: Use logger abstraction

### 🟡 MEDIUM (12 issues)
- Large Files: 3 files > 500 lines
  - src/core/orchestrator.ts (678 lines)
  Fix: Split into modules

Phase 4: Documentation Generation (10 seconds)

Merge Strategy:

1. Explicit standards = source of truth
2. Implicit standards = fill gaps
3. Anti-patterns = warnings + recommendations

Output: .specweave/docs/internal/governance/coding-standards-analysis.md

---

Integration Points

1. Brownfield Analyzer Integration

Automatic: Runs as part of brownfield analysis

User: "Analyze this brownfield project"

Workflow:
1. Scan project structure
2. Classify documents
3. Detect external tools
4. → RUN code-standards-detective agent
5. → GENERATE coding-standards.md
6. Generate migration plan

2. Increment Planning

Reference: Standards included in technical constraints

## Technical Constraints

Coding Standards: .specweave/docs/internal/governance/coding-standards.md
- Naming: camelCase (vars), PascalCase (classes)
- Functions: < 50 lines target
- No console.* - use logger

3. Increment Completion

Optional: Re-analyze on increment done

/sw:done 0046 --update-standards

---

Usage Examples

Example 1: First-Time Analysis

User: "What are the coding standards for this project?"

Skill: code-standards-analyzer

Actions:
1. Check for existing standards (none found)
2. Parse .eslintrc.json, .prettierrc
3. Analyze 1,234 TypeScript files
4. Detect patterns with 95% confidence
5. Generate standards document

Output:
"✅ Analysis complete! Generated coding standards at:
.specweave/docs/internal/governance/coding-standards-analysis.md

Key findings:
- Naming: 98% camelCase compliance
- Imports: 100% use .js extensions
- Issues: 5 console.* usages, 2 hardcoded secrets
- Recommendation: Formalize detected patterns as official standards"

Example 2: Standards Audit

User: "Check if we're following our declared standards"

Skill: code-standards-analyzer

Actions:
1. Read existing coding-standards.md
2. Analyze current codebase
3. Compare declared vs actual
4. Report violations

Output:
"📊 Standards Compliance: 87%

✅ Passing:
- Naming conventions: 98% compliant
- Import patterns: 100% compliant

⚠️ Violations:
- console.* usage: 12 instances (should be 0)
- Large files: 3 files > 500 lines (should be 0)

Recommendation: Fix violations or update standards to reflect reality"

Example 3: New Contributor Onboarding

User: "I'm new to this codebase. What conventions should I follow?"

Skill: code-standards-analyzer

Actions:
1. Load existing coding-standards.md
2. Extract key rules with examples
3. Highlight SpecWeave-specific patterns

Output:
"📚 Coding Standards Summary

1. Naming:
   - Variables: camelCase (e.g., `userId`, `isActive`)
   - Functions: camelCase (e.g., `getUserById()`)
   - Classes: PascalCase (e.g., `UserService`)

2. Imports:
   - Always use .js extensions
   - Example: import { foo } from './bar.js'

3. Error Handling:
   - Use custom error types
   - Example: throw new UserNotFoundError(id)

4. Logging:
   - NEVER use console.*
   - Use logger abstraction instead

Full standards: .specweave/docs/internal/governance/coding-standards.md"

---

Commands

Manual Analysis

# Full analysis
/sw:analyze-standards

# Drift detection only
/sw:analyze-standards --drift

# Update existing standards
/sw:analyze-standards --update

---

Output Files

1. coding-standards-analysis.md (Auto-Generated)

Location: .specweave/docs/internal/governance/coding-standards-analysis.md

Purpose: Latest analysis report (gitignored, temporary)

Contents:

• Detected patterns with confidence levels
• Real code examples
• Statistical evidence
• Violation warnings
• Recommendations

2. coding-standards.md (Source of Truth)

Location: .specweave/docs/internal/governance/coding-standards.md

Purpose: Official coding standards (git-tracked, manual + auto)

Contents:

• Naming conventions
• Import patterns
• Function guidelines
• Type safety rules
• Error handling
• Security practices
• Performance guidelines

3. coding-standards-history.md (Change Log)

Location: .specweave/docs/internal/governance/coding-standards-history.md

Purpose: Track standard evolution over time

Contents:

• Timestamp of each analysis
• Changes detected
• Migration guides
• Rationale for updates

---

Best Practices

1. Run During Onboarding

• Analyze standards as part of brownfield analysis
• Generate baseline documentation
• Establish project context

2. Periodic Re-Analysis

• Quarterly reviews
• After major refactors
• On team onboarding

3. Team Review Required

• Don't auto-commit changes
• Review generated standards
• Discuss inconsistencies
• Formalize decisions

4. Living Documentation

• Keep standards in sync with code
• Update when patterns change
• Track evolution in history

5. Enforcement Through Tooling

• Most standards → ESLint/Prettier
• This skill → document what tools can't catch
• Focus on SpecWeave-specific patterns

---

Related Documentation

• Coding Standards - Official standards
• Code Review Standards - Review process
• Brownfield Analyzer - Project analysis

---

Technical Details

Supported Languages

• ✅ TypeScript (primary)
• ✅ JavaScript (ES6+)
• ✅ Python (pyproject.toml, .pylintrc, ruff.toml, .flake8, mypy.ini)
• ✅ Java/Kotlin (checkstyle.xml, pmd.xml, spotbugs.xml, detekt.yml)
• ✅ Go (go.mod, .golangci.yml, staticcheck.conf)
• ✅ C#/.NET (.editorconfig, StyleCop.json, Directory.Build.props)
• ✅ Rust (rustfmt.toml, clippy.toml, Cargo.toml)
• ✅ React (package.json, ESLint plugin:react/*)
• ✅ Angular (angular.json, ESLint @angular-eslint)
• ✅ Vue (package.json, ESLint plugin:vue/*)
• ✅ Svelte (package.json, svelte.config.js)

Detection Algorithms

Naming Convention Detection:

• Regex pattern matching
• Statistical frequency analysis
• AST node analysis
• Confidence scoring (samples / total)

Anti-Pattern Detection:

• Static analysis (grep, AST parsing)
• Rule-based checks
• Security scanning
• Complexity metrics

Confidence Levels:

• ENFORCED: Linter/compiler enforced (100%)
• HIGH: 90%+ compliance in codebase
• MEDIUM: 70-89% compliance
• LOW: 50-69% compliance
• CONFLICT: <50% compliance (inconsistent)

---

Limitations

1. Implicit Standards: Requires representative codebase sample
2. False Positives: Anti-pattern detection may flag intentional code
3. Context: Can't understand business rationale for patterns

---

Multi-Technology Support

Status: ✅ Implemented (increment 0122-multi-technology-governance)

Technology	Config Files	Status
TypeScript/JavaScript	.eslintrc.*, .prettierrc, tsconfig.json	✅ Implemented
Python	pyproject.toml, .pylintrc, ruff.toml, .flake8, mypy.ini	✅ Implemented
Go	go.mod, .golangci.yml, staticcheck.conf	✅ Implemented
Java/Kotlin	checkstyle.xml, pmd.xml, spotbugs.xml, detekt.yml	✅ Implemented
C#/.NET	.editorconfig, StyleCop.json, Directory.Build.props	✅ Implemented
Rust	rustfmt.toml, clippy.toml, Cargo.toml	✅ Implemented
React	ESLint + plugin:react/*, package.json	✅ Implemented
Angular	angular.json, .eslintrc	✅ Implemented
Vue	ESLint + plugin:vue/*, vite.config.*	✅ Implemented
Svelte	svelte.config.js, package.json	✅ Implemented

Output Structure:

.specweave/docs/internal/governance/
├── coding-standards.md          # Unified summary of ALL technologies
├── shared-conventions.md        # EditorConfig, Git conventions
└── standards/
    ├── typescript.md
    ├── python.md
    ├── golang.md
    ├── java.md
    ├── react.md
    ├── angular.md
    ├── vue.md
    └── svelte.md

Usage:

import {
  detectEcosystems,
  parsePythonStandards,
  parseGoStandards,
  parseJavaStandards,
  parseFrontendStandards,
  generateStandardsMarkdown,
  generateUnifiedSummary
} from 'src/core/living-docs/governance/index.js';

---

Future Enhancements

• Auto-generate ESLint rules from detected patterns
• AI-powered suggestions from top OSS projects
• Team-specific standards in multi-project mode
• Pre-commit hook integration for enforcement
• Real-time drift alerts
• Standards comparison across projects