MANDATORY: Use codebase-rules-extractor-specialist agent MANDATORY: Conduct a comprehensive analysis of the codebase to extract rules and conventions.

Your objective is to thoroughly analyze a codebase and extract all coding rules, patterns, conventions, best practices, and anti-patterns that should guide future code creation.

==================== PHASE 1 — CODEBASE DISCOVERY & MAPPING

Structure Analysis
- Map the directory structure and identify modules/domains
- Identify project type(s) (frontend, backend, full-stack, library, etc.)
- Document technology stack and frameworks used
- List all programming languages present
Documentation Review
- Read ALL markdown files: README.md, docs/SUMMARY.md, design docs, ADRs, RFCs
- Check for existing style guides, conventions documents, or coding standards
- Identify any .instructions.md, .rules, or similar documentation files
- Extract explicit rules already documented
Code Pattern Analysis
- Scan key files from each domain/module
- Identify naming conventions (functions, classes, variables, constants)
- Analyze code structure patterns (architecture, design patterns used)
- Document folder organization and file naming patterns
- Identify error handling approaches
- Analyze dependency management and import patterns
- Study test structure and testing conventions

==================== PHASE 2 — RULES EXTRACTION

Extract both explicit rules (documented, commented) and implicit rules (inferred from consistent patterns):

Categories to Extract:

Naming Conventions
- Function/method naming (camelCase, snake_case, PascalCase, prefixes/suffixes)
- Variable naming conventions (abbreviations usage, boolean prefixes like is, has)
- Class/type naming rules
- Constant naming (UPPER_SNAKE_CASE, other)
- File naming conventions
Code Structure & Organization
- Module organization principles
- File size/complexity limits (if observed)
- Function/method length preferences
- Code grouping strategies
- Import organization and ordering
- Export patterns
Architecture & Design Patterns
- Architectural patterns observed (MVC, MVVM, layered, hexagonal, etc.)
- Design patterns consistently used (Singleton, Factory, Observer, etc.)
- Component structure (if applicable)
- Dependency injection approaches
- State management patterns
Type System & Safety
- Type annotation requirements
- Null/undefined handling strategies
- Generic type usage patterns
- Type narrowing approaches
- Any/unknown type usage policy
Error Handling & Validation
- Error throwing conventions
- Error catching and handling patterns
- Input validation approaches
- Error recovery strategies
- Logging patterns
Testing Conventions
- Test file naming and location patterns
- Testing framework preferences
- Test structure conventions (describe/it patterns)
- Mocking/stubbing approaches
- Test data management
- Coverage targets (if documented)
Code Style & Formatting
- Indentation (spaces/tabs, size)
- Line length preferences
- Whitespace usage
- Comment style and conventions
- Documentation comment format (JSDoc, docstrings, etc.)
- Import/export statement formatting
Performance & Optimization
- Performance constraints observed
- Caching strategies
- Lazy loading patterns
- Memory management considerations
- Bundle size considerations (if applicable)
Security Practices
- Authentication/authorization patterns
- Data protection approaches
- Input sanitization methods
- Secret management approaches
- XSS/CSRF prevention patterns
Dependencies & Libraries
- Library selection criteria
- Version constraints and policies
- Polyfill/compatibility strategies
- Internal vs external library usage patterns

==================== PHASE 3 — VALIDATION & ORGANIZATION

Cross-reference patterns across multiple files to confirm they are consistent rules, not one-offs
Distinguish between:
- MUST: Non-negotiable rules (critical for consistency, security, or functionality)
- SHOULD: Strong conventions (break only with justification)
- MAY/OPTIONAL: Flexible patterns (context-dependent)
Identify contradictions or evolving patterns
Document the frequency and consistency of each rule

==================== PHASE 4 — DOCUMENTATION GENERATION

Generate a comprehensive rules document and save it as:

docs/agents/rules/<LANGUAGE>-rules-<timestamp>.md

Where <LANGUAGE> is: typescript, python, javascript, golang, rust, java, etc. Or "multi-language" if analyzing multiple languages.

⚠️ Use the EXACT format below:

Codebase Rules & Conventions

Project: [Project Name] Analysis Date: [ISO Date] Languages: [List of languages] Frameworks: [Framework list] Analyzer Version: 1.0

1. Naming Conventions

Functions & Methods

MUST: [Rule with examples from codebase or code snippets]
SHOULD: [Rule with reasoning]
Examples: Code references or snippets

Variables

MUST: [Rule]
SHOULD: [Rule]

Classes & Types

MUST: [Rule]

Constants

MUST: [Rule]

Files & Folders

MUST: [Rule]
SHOULD: [Rule]

2. Code Organization & Architecture

Project Structure

[Diagram or description of folder structure]
MUST: [Rule for organizing modules]

File Organization

MUST: [Rule for imports, exports, order]
SHOULD: [Rule for file grouping]

Module Patterns

Observed Pattern: [Pattern name with description]
Usage: [When and where this pattern is used]
Example Reference: [File paths using this pattern]

Architectural Principles

[List principles (e.g., separation of concerns, DRY, SOLID)]

3. Type System & Safety

Type Annotations

MUST: [Rule about required type annotations]
SHOULD: [Rule about optional types]
Avoid: Types that are discouraged

Null/Undefined Handling

MUST: [Strategy observed]
Examples: Code references

Generic Types

SHOULD: [Conventions for generic usage]

4. Error Handling & Validation

Error Throwing

MUST: [Error convention observed]
Pattern: [Error structure/wrapping pattern]
Example: Code reference

Error Catching

MUST: [How errors are caught]
SHOULD: [Error recovery patterns]

Input Validation

MUST: [Validation approach]
Location: [Where validation occurs]

Logging

Standard: [Log level conventions]
Pattern: [Log message structure]

5. Testing Conventions

Test Structure

File Naming: [Pattern: e.g., *.test.ts, *.spec.ts]
Location: [Path pattern relative to source]
Framework: [Testing framework used]

Test Writing

MUST: [Rule for test structure]
Pattern: [Test organization pattern]
Mocking: [Mocking/stubbing approach]

Coverage Targets

[If documented: minimum coverage %]

6. Code Style & Formatting

Indentation

MUST: [Spaces/tabs and size]

Line Length

SHOULD: [Maximum line length]

Imports & Exports

MUST: [Import statement rules]
MUST: [Export patterns]

Comments & Documentation

Documentation Format: [JSDoc, docstrings, etc.]
MUST: [What must be documented]
SHOULD: [What should be commented]

7. Performance & Optimization

Patterns Observed

[Caching strategies]
[Lazy loading patterns]
[Bundle optimization approaches]

Constraints

[Performance targets if any]

8. Security Practices

Authentication & Authorization

Pattern: [How auth is handled]
Reference: [File references]

Data Protection

Approach: [Data protection strategy]

Input Sanitization

MUST: [Sanitization rule]

Secrets Management

MUST: [How secrets are managed]

9. Dependencies & Libraries

Selection Criteria

[Why certain libraries are chosen]

External Dependencies

MUST: [Rules for adding dependencies]

Version Constraints

Policy: [How versions are managed]

10. Anti-Patterns to Avoid

Critical Anti-Patterns (DO NOT USE)

[Pattern 1 - Why it's bad with example reference]
[Pattern 2]
[Pattern 3]

Discouraged Patterns (AVOID when possible)

[Pattern with explanation]
[Pattern with explanation]

11. Best Practices to Follow

Essential Practices

[Practice 1 with explanation]
[Practice 2 with explanation]
[Practice 3 with explanation]

Context-Specific Practices

[For feature A: practice]
[For API code: practice]
[For utilities: practice]

12. Language-Specific Rules

[Language Name]

[Language-specific rules and conventions]

[Other Language]

[Rules]

13. Common Code Patterns

[Pattern Name 1]

Purpose: [What this pattern solves]
Frequency: [How often it appears]
Example References: [File paths or code snippets]
When to Use: [Context for usage]

[Pattern Name 2]

[Similar structure]

14. Tool Configuration & Automation

Linters & Formatters

Tool: [ESLint, Prettier, Black, etc.]
Config File: [Location of config]
MUST: [Non-negotiable rules enforced]

Type Checking

Tool: [TypeScript, mypy, etc.]
Config: [Configuration details]
Strictness: [Level enforced]

Testing Tools

Framework: [Jest, pytest, etc.]
Config: [Location]
Commands: [How to run tests]

15. Documentation & Comments

Code Comments

MUST: [What requires comments]
SHOULD: [What should be explained]
Avoid: [Comment anti-patterns observed]

Function/Class Documentation

Format: [JSDoc, docstring format]
MUST Include: [Required fields]
Example: [Documentation reference]

README & Project Docs

MUST: [What must be documented]
Location: [Where docs are kept]

Appendix A: File Structure Reference

[Map of key directories and files with brief descriptions]

Appendix B: Code Examples

[Link to or quote from exemplary files that follow the rules]

Appendix C: Evolution & Change Log

[Date]: [Rule added/changed/removed with reasoning]

Notes

Analysis performed on: [Codebase version/date]
Total files analyzed: [Number]
Languages analyzed: [List]
Confidence level: [High/Medium based on data consistency]
Potential gaps: [Any areas that were unclear or inconsistent]

⚠️ GENERATION RULES:

Every extracted rule MUST have at least ONE concrete code reference from the actual codebase
Use relative file paths for references: src/utils/helpers.ts#L10-L20
For each rule severity level (MUST/SHOULD/AVOID), provide concrete examples
If contradictory patterns exist, explicitly document both with frequency of usage
Keep examples concise - use line references instead of full code blocks when possible
Date the document and version it if this analysis will be repeated
Document the scope: entire codebase, specific module, specific language, etc.

This document becomes the authoritative reference for how new code should be written in this project.