Brownfield Project Documentation Generator

Generate comprehensive architecture documentation automatically by analyzing existing codebase structure, patterns, and conventions.

Purpose

Analyze an existing codebase and generate three comprehensive documentation files:

1. architecture.md - Project structure, tech stack, data models, API specifications
2. standards.md - Coding standards, best practices, discovered conventions
3. patterns.md - Design patterns, architectural patterns, common conventions

This enables BMAD Enhanced to work with brownfield projects by reverse-engineering architecture from code.

When to Use This Skill

This skill should be used when:

• Starting BMAD Enhanced with existing project (brownfield onboarding)
• Architecture documentation is outdated or missing
• Need to discover implicit patterns and conventions
• Onboarding to unfamiliar codebase

This skill should NOT be used when:

• Greenfield projects (write docs from scratch instead)
• Project already has current, comprehensive documentation
• Codebase >500K lines (too complex for automated analysis)
• Project has no clear structure

Project Type Support

Well-Supported Languages:

• ✅ Node.js/TypeScript (excellent support)
• ✅ Python (good support)
• ✅ Go (good support)
• ✅ Java/Kotlin (good support)
• ✅ Rust (good support)

Basic Support:

• ⚠️ PHP, Ruby, C#/.NET (basic support)

Optimal Codebase Size: 10K-100K lines

• Smaller: May lack sufficient patterns to analyze
• Larger: Analysis may be too slow or complex

Sequential Documentation Generation

Execute steps in order - each builds on previous analysis:

Step 0: Configuration and Validation

Purpose: Verify project is suitable for automated documentation.

Actions:

1. Load config from .claude/config.yaml (codebasePath, existingDocs, includeTests, maxFiles)
2. Validate structure: Check path exists, identify languages, count files/lines, verify size (10K-100K recommended)
3. Check existing docs: Ask how to handle (merge/replace/supplement)
4. Get confirmation: Show summary (path, language, file count, lines, estimated time), ask to proceed

See: references/templates.md#step-0-configuration-and-validation-output for complete formats

Halt if:

• Codebase path not found
• No recognizable project structure
• Codebase too large (>500K lines)
• Unsupported language
• User declines to proceed

Output: Validation confirmation (project type, lines, existing docs mode, scope, ready status)

Reference: See validation-criteria.md for detailed validation rules.

Step 1: Analyze Project Structure

Purpose: Map file organization and module structure.

Actions:

1. Scan directory structure: Identify main dirs, detect patterns (feature vs type), note nesting
2. Analyze file organization: Files per dir, naming conventions, size distribution, co-location patterns
3. Detect project type: Backend API / Frontend App / Full-Stack / Library / Monorepo (based on directory structure)
4. Map relationships: Analyze imports, build dependency graph, identify core modules, detect circular dependencies

Output: Project structure analysis with type, organization, directory structure (dirs + file counts + line counts), key patterns

See: references/templates.md#step-1-codebase-analysis-output for complete format

Reference: See analysis-techniques.md for detailed analysis methods.

Step 2: Analyze Technology Stack

Purpose: Identify languages, frameworks, and dependencies.

Actions:

1. Read package configuration:

   • Node.js: package.json
   • Python: requirements.txt, pyproject.toml
   • Go: go.mod
   • Java: pom.xml, build.gradle
   • Rust: Cargo.toml

2. Extract dependencies and identify frameworks:

   • Backend: Express, Django, Spring Boot, etc.
   • Frontend: React, Vue, Angular, etc.
   • Database: Prisma, TypeORM, SQLAlchemy, etc.
   • Testing: Jest, Pytest, JUnit, etc.

3. Detect runtime/platform:

   • Node.js/Python/JDK version
   • Database type (PostgreSQL, MySQL, MongoDB)

Output: Tech stack summary (runtime, backend/frontend frameworks, key libraries, testing tools, versions, confidence score)

See: references/templates.md#step-2-technology-stack-analysis for complete format

Step 3: Extract Data Models and Schemas

Purpose: Document data structures and validation rules.

Actions:

1. Locate data model files:

   • Prisma schema: prisma/schema.prisma
   • TypeScript interfaces: src/types/*.ts, src/models/*.ts
   • Database migrations: prisma/migrations/, migrations/
   • Validation schemas: Zod, Yup, Joi schemas

2. Parse data models and extract validation rules

3. Analyze relationships:

   • One-to-many, many-to-many
   • Foreign keys and constraints

4. Detect data flow:

   • Request → Validation → Service → Repository → Database
   • Response transformation (DTOs)

Output: Data models summary (models with fields/types/constraints, validation rules, relationships, confidence score)

See: references/templates.md#complete-architecture-md-template for data model format

Reference: See analysis-techniques.md for model extraction patterns.

Step 4: Analyze API Patterns

Purpose: Document API structure and conventions.

Actions:

1. Locate API definitions:

   • Express routes: src/routes/**/*.ts
   • Controllers: src/controllers/**/*.ts
   • OpenAPI/Swagger spec (if exists)
   • GraphQL schemas (if exists)

2. Extract endpoints and analyze request/response patterns:

   • Request validation (middleware)
   • Error response format
   • Success response format
   • Status codes used

3. Identify authentication:

   • JWT tokens, session-based, API keys, OAuth

4. Detect rate limiting and other middleware

Output: API specs summary (base URL, authentication type/headers/expiry, error/success response formats, confidence score)

See: references/templates.md#complete-architecture-md-template for API specification format

Step 5: Extract Coding Standards and Patterns

Purpose: Document implicit conventions and best practices.

Actions:

1. Analyze code style:

   • Read .eslintrc, .prettierrc, tsconfig.json
   • Detect: indentation, quotes, semicolons
   • Naming conventions: variables, functions, classes, files

2. Identify architectural patterns:

   • Design patterns: Repository, Factory, Strategy
   • Architectural style: Layered, Clean, Hexagonal

3. Extract error handling patterns:

   • Error classes
   • Centralized error handling
   • Logging patterns

4. Detect testing patterns:

   • Test organization
   • Mocking strategy
   • Test data management

Output:

Coding Standards:

Code Style:
- Indentation: 2 spaces
- Quotes: Single quotes
- Naming: camelCase (variables), PascalCase (classes), kebab-case (files)

Architectural Patterns:
1. Layered Architecture
   - Routes (presentation layer)
   - Services (business logic layer)
   - Repositories (data access layer)

2. Dependency Injection
3. Repository Pattern

Error Handling:
- Custom error classes (AppError, ValidationError)
- Centralized error handling middleware
- Never expose stack traces to clients

Confidence: High (90%)

Reference: See pattern-detection.md for pattern identification techniques.

Step 6: Generate Architecture Documentation

Purpose: Create comprehensive architecture.md from findings.

Actions:

1. Load architecture template structure

2. Populate sections with analyzed data from Steps 1-5:

   • Overview, tech stack, project structure
   • Data models, API specifications
   • Include confidence scores where applicable
   • Add source file references

3. Generate diagrams (optional):

   • Mermaid diagrams for architecture layers
   • Data model ERD
   • API endpoint map

4. Add human review notes for medium/low confidence sections

5. Write documentation file:

   • Create docs/architecture.md
   • Or merge with existing docs if "merge" mode selected

Output:

✓ Architecture documentation generated
✓ File: docs/architecture.md (2,450 lines)
✓ Sections: 12
✓ Overall confidence: 85%
✓ Human review items: 5

Reference: See documentation-templates.md for template structures.

Step 7: Generate Standards Documentation

Purpose: Create standards.md from discovered patterns.

Actions:

1. Extract standards from code analysis:

   • Security standards (from security practices)
   • Testing standards (from test patterns)
   • Code quality standards (from ESLint rules)
   • Performance standards (from observed patterns)

2. Document best practices:

   • Observed consistently across codebase
   • Mark as "discovered" vs "recommended"

3. Create standards document with examples and consistency scores

Output:

✓ Standards documentation generated
✓ File: docs/standards.md (850 lines)
✓ Standards extracted: 18
✓ Consistency scores: 75-100%

Step 8: Generate Patterns Documentation

Purpose: Document discovered design patterns and conventions.

Actions:

1. Extract design patterns:

   • Repository, Factory, Strategy, Middleware patterns

2. Document usage examples:

   • Show code examples of each pattern
   • Explain when to use
   • Link to existing implementations

3. Identify anti-patterns:

   • Code smells detected
   • Inconsistencies
   • Technical debt

4. Create patterns document

Output:

✓ Patterns documentation generated
✓ File: docs/patterns.md (620 lines)
✓ Patterns identified: 8
✓ Anti-patterns noted: 3

Reference: See pattern-detection.md for pattern documentation templates.

Step 9: Validation and Confidence Scoring

Purpose: Score accuracy and identify areas needing human review.

Actions:

1. Calculate confidence: Score each section (tech stack, structure, data models, API, standards) and compute overall
2. Identify low-confidence areas: Find sections <70%, conflicting patterns, missing info
3. Generate review checklist: List high/medium priority items needing human verification
4. Create validation report

Output: Validation summary (overall confidence %, high/medium priority review item counts)

See: references/templates.md#review-checklist-template and references/confidence-scoring.md for formats

Reference: See confidence-scoring.md for scoring guidelines.

Step 10: Summary and Next Steps

Purpose: Provide user with clear summary and action items.

Actions:

1. Generate summary report: Project name, duration, files analyzed, confidence, generated docs (paths + line counts), key findings (type, arch, tech stack, test coverage), next steps
2. Create review checklist file: docs/REVIEW_CHECKLIST.md
3. Update config: Set brownfield flag, doc paths, documented=true
4. Prompt next action: Review items, create task spec, run index-docs, or exit

Output: Summary confirmation (report generated, checklist created, config updated, ready status)

See: references/templates.md for complete summary formats

Confidence Scoring Guidelines

High (85-100%): Explicit in code/config, consistent patterns, no conflicts | Medium (70-84%): Inferred from patterns, some inconsistencies, needs validation | Low (<70%): Missing/unclear info, conflicts, high uncertainty, MUST review

See: references/confidence-scoring.md for detailed scoring methodology

Limitations

Cannot: Understand business logic without context, document deployment infrastructure, capture tribal knowledge, understand legacy decisions, document external integrations perfectly

Requires: Readable structured codebase, standard organization, supported language/framework, 10K-100K lines (optimal)

Best Practices

Run periodically (every 3-6 months) | Always review low-confidence sections | Supplement with manual docs (business context, deployment) | Use as starting point, enhance with team input

Integration with Planning Workflow

Brownfield: document-project → index-docs → create-task-spec (use generated docs) | Greenfield: Write docs manually first | Brownfield: Generate from code, then refine

References

Detailed documentation in references/:

• templates.md: All output formats, complete architecture/standards/patterns templates, analysis summaries, review checklists, error templates
• analysis-techniques.md: Analysis methods for structure, tech stack, models, APIs, patterns
• pattern-detection.md: Pattern identification and documentation techniques
• documentation-templates.md: Templates for architecture, standards, patterns docs
• confidence-scoring.md: Confidence calculation methodology and validation criteria
• validation-criteria.md: Project validation rules and sizing guidelines