pig/pig-farm-controller

Fork 0

Files

huang 426ae41f54 bmad初始化

2025-11-01 19:22:39 +08:00

14 KiB

Raw Blame History

Document Project Workflow

Version: 1.2.0 Module: BMM (BMAD Method Module) Type: Action Workflow (Documentation Generator)

Purpose

Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development. Generates a master index and multiple documentation files tailored to project structure and type.

NEW in v1.2.0: Context-safe architecture with scan levels, resumability, and write-as-you-go pattern to prevent context exhaustion.

Key Features

Multi-Project Type Support: Handles web, backend, mobile, CLI, game, embedded, data, infra, library, desktop, and extension projects
Multi-Part Detection: Automatically detects and documents projects with separate client/server or multiple services
Three Scan Levels (NEW v1.2.0): Quick (2-5 min), Deep (10-30 min), Exhaustive (30-120 min)
Resumability (NEW v1.2.0): Interrupt and resume workflows without losing progress
Write-as-you-go (NEW v1.2.0): Documents written immediately to prevent context exhaustion
Intelligent Batching (NEW v1.2.0): Subfolder-based processing for deep/exhaustive scans
Data-Driven Analysis: Uses CSV-based project type detection and documentation requirements
Comprehensive Scanning: Analyzes APIs, data models, UI components, configuration, security patterns, and more
Architecture Matching: Matches projects to 170+ architecture templates from the solutioning registry
Brownfield PRD Ready: Generates documentation specifically designed for AI agents planning new features

How to Invoke

workflow document-project

Or from BMAD CLI:

/bmad:bmm:workflows:document-project

Scan Levels (NEW in v1.2.0)

Choose the right scan depth for your needs:

1. Quick Scan (Default)

Duration: 2-5 minutes What it does: Pattern-based analysis without reading source files Reads: Config files, package manifests, directory structure, README Use when:

You need a fast project overview
Initial understanding of project structure
Planning next steps before deeper analysis

Does NOT read: Source code files (_.js, _.ts, _.py, _.go, etc.)

2. Deep Scan

Duration: 10-30 minutes What it does: Reads files in critical directories based on project type Reads: Files in critical paths defined by documentation requirements Use when:

Creating comprehensive documentation for brownfield PRD
Need detailed analysis of key areas
Want balance between depth and speed

Example: For a web app, reads controllers/, models/, components/, but not every utility file

3. Exhaustive Scan

Duration: 30-120 minutes What it does: Reads ALL source files in project Reads: Every source file (excludes node_modules, dist, build, .git) Use when:

Complete project analysis needed
Migration planning requires full understanding
Detailed audit of entire codebase
Deep technical debt assessment

Note: Deep-dive mode ALWAYS uses exhaustive scan (no choice)

Resumability (NEW in v1.2.0)

The workflow can be interrupted and resumed without losing progress:

State Tracking: Progress saved in project-scan-report.json
Auto-Detection: Workflow detects incomplete runs (<24 hours old)
Resume Prompt: Choose to resume or start fresh
Step-by-Step: Resume from exact step where interrupted
Archiving: Old state files automatically archived

Example Resume Flow:

> workflow document-project

I found an in-progress workflow state from 2025-10-11 14:32:15.

Current Progress:
- Mode: initial_scan
- Scan Level: deep
- Completed Steps: 5/12
- Last Step: step_5

Would you like to:
1. Resume from where we left off - Continue from step 6
2. Start fresh - Archive old state and begin new scan
3. Cancel - Exit without changes

Your choice [1/2/3]:

What It Does

Step-by-Step Process

Detects Project Structure - Identifies if project is single-part or multi-part (client/server/etc.)
Classifies Project Type - Matches against 12 project types (web, backend, mobile, etc.)
Discovers Documentation - Finds existing README, CONTRIBUTING, ARCHITECTURE files
Analyzes Tech Stack - Parses package files, identifies frameworks, versions, dependencies
Conditional Scanning - Performs targeted analysis based on project type requirements:
- API routes and endpoints
- Database models and schemas
- State management patterns
- UI component libraries
- Configuration and security
- CI/CD and deployment configs
Generates Source Tree - Creates annotated directory structure with critical paths
Extracts Dev Instructions - Documents setup, build, run, and test commands
Creates Architecture Docs - Generates detailed architecture using matched templates
Builds Master Index - Creates comprehensive index.md as primary AI retrieval source
Validates Output - Runs 140+ point checklist to ensure completeness

Output Files

Single-Part Projects:

index.md - Master index
project-overview.md - Executive summary
architecture.md - Detailed architecture
source-tree-analysis.md - Annotated directory tree
component-inventory.md - Component catalog (if applicable)
development-guide.md - Local dev instructions
api-contracts.md - API documentation (if applicable)
data-models.md - Database schema (if applicable)
deployment-guide.md - Deployment process (optional)
contribution-guide.md - Contributing guidelines (optional)
project-scan-report.json - State file for resumability (NEW v1.2.0)

Multi-Part Projects (e.g., client + server):

index.md - Master index with part navigation
project-overview.md - Multi-part summary
architecture-{part_id}.md - Per-part architecture docs
source-tree-analysis.md - Full tree with part annotations
component-inventory-{part_id}.md - Per-part components
development-guide-{part_id}.md - Per-part dev guides
integration-architecture.md - How parts communicate
project-parts.json - Machine-readable metadata
project-scan-report.json - State file for resumability (NEW v1.2.0)
Additional conditional files per part (API, data models, etc.)

Data Files

The workflow uses a single comprehensive CSV file:

documentation-requirements.csv - Complete project analysis guide

Location: /bmad/bmm/workflows/document-project/documentation-requirements.csv
12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
24 columns combining:
- Detection columns: project_type_id, key_file_patterns (identifies project type from codebase)
- Requirement columns: requires_api_scan, requires_data_models, requires_ui_components, etc.
- Pattern columns: critical_directories, test_file_patterns, config_patterns, etc.
Self-contained: All project detection AND scanning requirements in one file
Architecture patterns inferred from tech stack (no external registry needed)

Use Cases

Primary Use Case: Brownfield PRD Creation

After running this workflow, use the generated index.md as input to brownfield PRD workflows:

User: "I want to add a new dashboard feature"
PRD Workflow: Loads docs/index.md
→ Understands existing architecture
→ Identifies reusable components
→ Plans integration with existing APIs
→ Creates contextual PRD with epics and stories

Other Use Cases

Onboarding New Developers - Comprehensive project documentation
Architecture Review - Structured analysis of existing system
Technical Debt Assessment - Identify patterns and anti-patterns
Migration Planning - Understand current state before refactoring

Requirements

Recommended Inputs (Optional)

Project root directory (defaults to current directory)
README.md or similar docs (auto-discovered if present)
User guidance on key areas to focus (workflow will ask)

Tools Used

File system scanning (Glob, Read, Grep)
Code analysis
Git repository analysis (optional)

Configuration

Default Output Location

Files are saved to: {output_folder} (from config.yaml)

Default: /docs/ folder in project root

Customization

Modify documentation-requirements.csv to adjust scanning patterns for project types
Add new project types to project-types.csv
Add new architecture templates to registry.csv

Example: Multi-Part Web App

Input:

my-app/
├── client/     # React frontend
├── server/     # Express backend
└── README.md

Detection Result:

Repository Type: Monorepo
Part 1: client (web/React)
Part 2: server (backend/Express)

Output (10+ files):

docs/
├── index.md
├── project-overview.md
├── architecture-client.md
├── architecture-server.md
├── source-tree-analysis.md
├── component-inventory-client.md
├── development-guide-client.md
├── development-guide-server.md
├── api-contracts-server.md
├── data-models-server.md
├── integration-architecture.md
└── project-parts.json

Example: Simple CLI Tool

Input:

hello-cli/
├── main.go
├── go.mod
└── README.md

Detection Result:

Repository Type: Monolith
Part 1: main (cli/Go)

Output (4 files):

docs/
├── index.md
├── project-overview.md
├── architecture.md
└── source-tree-analysis.md

Deep-Dive Mode

What is Deep-Dive Mode?

When you run the workflow on a project that already has documentation, you'll be offered a choice:

Rescan entire project - Update all documentation with latest changes
Deep-dive into specific area - Generate EXHAUSTIVE documentation for a particular feature/module/folder
Cancel - Keep existing documentation

Deep-dive mode performs comprehensive, file-by-file analysis of a specific area, reading EVERY file completely and documenting:

All exports with complete signatures
All imports and dependencies
Dependency graphs and data flow
Code patterns and implementations
Testing coverage and strategies
Integration points
Reuse opportunities

When to Use Deep-Dive Mode

Before implementing a feature - Deep-dive the area you'll be modifying
During architecture review - Deep-dive complex modules
For code understanding - Deep-dive unfamiliar parts of codebase
When creating PRDs - Deep-dive areas affected by new features

Deep-Dive Process

Workflow detects existing index.md
Offers deep-dive option
Suggests areas based on project structure:
- API route groups
- Feature modules
- UI component areas
- Services/business logic
You select area or specify custom path
Workflow reads EVERY file in that area
Generates deep-dive-{area-name}.md with complete analysis
Updates index.md with link to deep-dive doc
Offers to deep-dive another area or finish

Deep-Dive Output Example

docs/deep-dive-dashboard-feature.md:

Complete file inventory (47 files analyzed)
Every export with signatures
Dependency graph
Data flow analysis
Integration points
Testing coverage
Related code references
Implementation guidance
~3,000 LOC documented in detail

Incremental Deep-Diving

You can deep-dive multiple areas over time:

First run: Scan entire project → generates index.md
Second run: Deep-dive dashboard feature
Third run: Deep-dive API layer
Fourth run: Deep-dive authentication system

All deep-dive docs are linked from the master index.

Validation

The workflow includes a comprehensive 160+ point checklist covering:

Project detection accuracy
Technology stack completeness
Codebase scanning thoroughness
Architecture documentation quality
Multi-part handling (if applicable)
Brownfield PRD readiness
Deep-dive completeness (if applicable)

Next Steps After Completion

Review docs/index.md - Your master documentation index
Validate - Check generated docs for accuracy
Use for PRD - Point brownfield PRD workflow to index.md
Maintain - Re-run workflow when architecture changes significantly

File Structure

document-project/
├── workflow.yaml                    # Workflow configuration
├── instructions.md                  # Step-by-step workflow logic
├── checklist.md                     # Validation criteria
├── documentation-requirements.csv   # Project type scanning patterns
├── templates/                       # Output templates
│   ├── index-template.md
│   ├── project-overview-template.md
│   └── source-tree-template.md
└── README.md                        # This file

Troubleshooting

Issue: Project type not detected correctly

Solution: Workflow will ask for confirmation; manually select correct type

Issue: Missing critical information

Solution: Provide additional context when prompted; re-run specific analysis steps

Issue: Multi-part detection missed a part

Solution: When asked to confirm parts, specify the missing part and its path

Issue: Architecture template doesn't match well

Solution: Check registry.csv; may need to add new template or adjust matching criteria

Architecture Improvements in v1.2.0

Context-Safe Design

The workflow now uses a write-as-you-go architecture:

Documents written immediately to disk (not accumulated in memory)
Detailed findings purged after writing (only summaries kept)
State tracking enables resumption from any step
Batching strategy prevents context exhaustion on large projects

Batching Strategy

For deep/exhaustive scans:

Process ONE subfolder at a time
Read files → Extract info → Write output → Validate → Purge context
Primary concern is file SIZE (not count)
Track batches in state file for resumability

State File Format

Optimized JSON (no pretty-printing):

{
  "workflow_version": "1.2.0",
  "timestamps": {...},
  "mode": "initial_scan",
  "scan_level": "deep",
  "completed_steps": [...],
  "current_step": "step_6",
  "findings": {"summary": "only"},
  "outputs_generated": [...],
  "resume_instructions": "..."
}

14 KiB Raw Blame History