agentvibes 2.12.4 → 2.12.6

package/.bmad/bmm/docs/workflow-document-project-reference.md

@@ -1,489 +0,0 @@
-# Document Project Workflow - Technical Reference
-
-**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
-
-```bash
-workflow document-project
-```
-
-Or from BMAD CLI:
-
-```bash
-/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
-
-1. **Detects Project Structure** - Identifies if project is single-part or multi-part (client/server/etc.)
-2. **Classifies Project Type** - Matches against 12 project types (web, backend, mobile, etc.)
-3. **Discovers Documentation** - Finds existing README, CONTRIBUTING, ARCHITECTURE files
-4. **Analyzes Tech Stack** - Parses package files, identifies frameworks, versions, dependencies
-5. **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
-6. **Generates Source Tree** - Creates annotated directory structure with critical paths
-7. **Extracts Dev Instructions** - Documents setup, build, run, and test commands
-8. **Creates Architecture Docs** - Generates detailed architecture using matched templates
-9. **Builds Master Index** - Creates comprehensive index.md as primary AI retrieval source
-10. **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 FRs and NFRs
-Architecture Workflow: Creates architecture design
-Create-Epics-and-Stories Workflow: Breaks down into 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:
-
-1. **Rescan entire project** - Update all documentation with latest changes
-2. **Deep-dive into specific area** - Generate EXHAUSTIVE documentation for a particular feature/module/folder
-3. **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
-
-1. Workflow detects existing `index.md`
-2. Offers deep-dive option
-3. Suggests areas based on project structure:
-   - API route groups
-   - Feature modules
-   - UI component areas
-   - Services/business logic
-4. You select area or specify custom path
-5. Workflow reads EVERY file in that area
-6. Generates `deep-dive-{area-name}.md` with complete analysis
-7. Updates `index.md` with link to deep-dive doc
-8. 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
-
-1. **Review** `docs/index.md` - Your master documentation index
-2. **Validate** - Check generated docs for accuracy
-3. **Use for PRD** - Point brownfield PRD workflow to index.md
-4. **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):
-
-```json
-{
-  "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": "..."
-}
-```
-
----
-
-**Related Documentation:**
-
-- [Brownfield Development Guide](./brownfield-guide.md)
-- [Implementation Workflows](./workflows-implementation.md)
-- [Scale Adaptive System](./scale-adaptive-system.md)