diff --git a/.gitignore b/.gitignore index e55e43e0..9eff8ef1 100644 --- a/.gitignore +++ b/.gitignore @@ -34,7 +34,7 @@ Thumbs.db .bmad*/.cursor/ # AI assistant files -# CLAUDE.md # we need this for Claude Code reviews +CLAUDE.md .ai/* cursor .gemini diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 89e735e6..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,670 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Repository Overview - -**BMad-CORE** is a universal human-AI collaboration framework powering multiple modules for AI-driven development, creative work, and custom solutions. The repository contains the core framework plus three official modules (BMM, BMB, CIS). - -**Current version:** v6.0.0-alpha.6 (near-beta quality) - ---- - -## Development Commands - -### Testing & Validation - -```bash -# Run ALL quality checks (comprehensive - use before pushing) -npm test - -# Individual test suites -npm run test:schemas # Agent schema validation (fixture-based) -npm run test:install # Installation component tests (compilation) -npm run validate:schemas # YAML schema validation -npm run validate:bundles # Web bundle integrity - -# Coverage -npm run test:coverage # Run schema tests with coverage report -``` - -**Note:** Requires Node.js 22+ (see .nvmrc). Run `nvm use` to switch to correct version. - -### Code Quality - -```bash -# Lint check -npm run lint - -# Auto-fix linting issues -npm run lint:fix - -# Format check (Prettier) -npm run format:check - -# Auto-format all files -npm run format:fix -``` - -### Building & Bundling - -```bash -# Bundle all modules for web deployment -npm run bundle - -# Rebundle (updates existing bundles) -npm run rebundle - -# Install BMAD locally (test installer) -npm run install:bmad -``` - -### Releases (GitHub Actions) - -```bash -# Trigger manual releases (requires gh CLI) -npm run release:patch -npm run release:minor -npm run release:major -npm run release:watch # Watch release workflow status -``` - ---- - -## High-Level Architecture - -### 1. Agent Compilation System (YAML → XML/Markdown) - -**Two compilation targets with different outputs:** - -**IDE Installation (filesystem-aware):** - -- Source: `src/modules/{module}/agents/*.agent.yaml` -- Output: `bmad/{module}/agents/{name}.md` (Markdown with XML) -- Features: File paths, customization via `bmad/_cfg/agents/`, IDE slash commands -- Compiled by: `tools/cli/bmad-cli.js install` - -**Web Bundles (self-contained):** - -- Source: Same YAML files -- Output: `src/modules/{module}/sub-modules/{platform}/sub-agents/{name}.md` -- Features: All dependencies embedded, no file I/O, platform-specific (claude-code, cursor, etc.) -- Compiled by: `npm run bundle` - -**Key difference:** `forWebBundle: true/false` flag changes compilation behavior (paths vs inline content). - -### 2. Workflow Execution Engine - -**All workflows are governed by:** `src/core/tasks/workflow.xml` - -**Workflow definition structure:** - -```yaml -# Example: src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml -name: 'prd' -config_source: '{project-root}/bmad/bmm/config.yaml' -instructions: '{installed_path}/instructions.md' -template: '{installed_path}/prd-template.md' -default_output_file: '{output_folder}/PRD.md' -``` - -**Execution flow:** - -1. Load workflow.yaml and resolve all variables (`{config_source}`, `{project-root}`, `{installed_path}`) -2. Read instructions.md (XML/Markdown with ``, ``, `` tags) -3. Execute steps sequentially, prompting user at `` tags -4. Write/edit output file after each template section -5. Run checklist.md validation if exists - -**Special tags in instructions:** - -- `` - Define workflow steps (execute in numerical order) -- `` - Perform an action -- `section_name` - Save content to file and show user for approval -- `` - Call another workflow -- `` - Conditional execution - -### 3. Module System Architecture - -**Directory structure:** - -``` -src/ -├── core/ # Framework foundation -│ ├── agents/ # BMad Master orchestrator -│ ├── tasks/ # Shared task definitions (workflow.xml) -│ ├── workflows/ # Core workflows (party-mode, brainstorming) -│ └── _module-installer/ # Module installation infrastructure -└── modules/ # Three official modules - ├── bmm/ # BMad Method (software development) - │ ├── agents/ # 12 agent YAML definitions - │ ├── workflows/ # 34 workflows across 4 phases - │ ├── testarch/ # TEA knowledge base (21 fragments, tea-index.csv) - │ └── docs/ # User-facing documentation - ├── bmb/ # BMad Builder (create custom solutions) - └── cis/ # Creative Intelligence Suite -``` - -**Installation creates:** - -``` -{target-project}/bmad/ -├── core/ # Compiled core framework -├── bmm/ # Compiled BMM module -├── bmb/ # Compiled BMB module -├── cis/ # Compiled CIS module -└── _cfg/ # User customizations (survives updates) - └── agents/ # Agent customization files -``` - -### 4. BMM Planning Tracks & Phase System - -**3 Planning Tracks (scale-adaptive):** - -- **Quick Flow**: Tech-spec only (Phase 2 → Phase 4) - bug fixes, simple features -- **BMad Method**: PRD + Architecture (Phases 1→2→3→4) - products, platforms -- **Enterprise Method**: BMad Method + extended planning (all phases) - compliance, security - -**4-Phase Methodology:** - -- **Phase 0** (Optional): Documentation - `*document-project` (brownfield prerequisite) -- **Phase 1** (Optional): Analysis - `*brainstorm`, `*research`, `*product-brief` -- **Phase 2** (Required): Planning - `*prd` or `*tech-spec` (creates epics) -- **Phase 3** (Track-dependent): Solutioning - `*architecture` (BMad Method/Enterprise only) -- **Phase 4** (Required): Implementation - Story-centric development - -**Matrix of possibilities:** - -- 3 tracks × 2 field types (greenfield/brownfield) = 6 combinations -- Tracked via YAML files: `src/modules/bmm/workflows/workflow-status/paths/*.yaml` - -**Important:** Phase numbering in YAML is 0-indexed, documentation is user-facing: - -- YAML `phase: 0` = Docs "Phase 1 (Analysis)" -- YAML `phase: 1` = Docs "Phase 2 (Planning)" -- YAML `phase: 2` = Docs "Phase 3 (Solutioning)" -- YAML `phase: 3` = Docs "Phase 4 (Implementation)" - -### 5. Test Architect (TEA) Special Architecture - -**TEA is unique:** Only BMM agent with dedicated knowledge base. - -**Structure:** - -``` -src/modules/bmm/testarch/ -├── knowledge/ # 21 production-ready test pattern fragments -│ ├── fixture-architecture.md -│ ├── network-first.md -│ ├── data-factories.md -│ └── [18 more...] -└── tea-index.csv # Fragment lookup index (21 rows) -``` - -**TEA execution model:** - -- **Phase 2** (once per project): `*framework`, `*ci` - test infrastructure setup -- **Phase 4** (per epic): `*test-design` - creates `test-design-epic-N.md` -- **Phase 4** (per story): `*atdd`, `*automate`, `*test-review`, `*trace` -- **Release Gate**: `*nfr-assess`, `*trace` (Phase 2 mode) - -**Critical actions:** TEA agents must consult `tea-index.csv` and load relevant knowledge fragments from `knowledge/` before giving recommendations. - -### 6. Document Sharding (Token Optimization) - -**Problem:** Large PRDs/Architecture docs (1000+ lines) consume massive context in Phase 4. - -**Solution:** Split by level-2 headings into separate files: - -``` -# Whole document -docs/PRD.md (2000 lines) - -# Sharded version -docs/PRD/ -├── index.md # Table of contents -├── section-1.md # First ## heading -├── section-2.md # Second ## heading -└── ... -``` - -**Workflow support:** All BMM workflows automatically detect and handle both formats using fuzzy matching. - -**Tool:** Use `/bmad:core:tools:shard-doc` to split large documents. - -### 7. Workflow Status Tracking - -**Two status systems:** - -**workflow-status.yaml** (Phases 0-3 + Phase 4 start): - -- Tracks planning workflows (PRD, architecture, sprint-planning) -- Generated by `*workflow-init`, updated by `*workflow-status` -- Lives in `{output_folder}/bmm-workflow-status.yaml` - -**sprint-status.yaml** (Phase 4 execution): - -- Tracks per-epic and per-story development -- Generated by `*sprint-planning` -- Lives in `{output_folder}/bmm-sprint-status.yaml` - -**Status values:** - -- Initial: `required`, `optional`, `recommended`, `conditional` -- Completed: File path (e.g., `docs/PRD.md`) -- Skipped: `skipped` - -### 8. Agent Customization System - -**Override agent properties without modifying core files:** - -```yaml -# bmad/_cfg/agents/pm-overrides.yaml -name: 'Sarah' # Override PM agent name -icon: '📊' # Override icon -persona: - communication_style: 'Concise and data-driven' -``` - -**Merging behavior:** User configs override core agent definitions during installation. - -**Survives updates:** `bmad/_cfg/` directory persists through all module updates. - ---- - -## Working with Workflows - -### Finding Workflow Paths - -**Agent menu triggers → workflow paths:** - -```yaml -# In agent YAML definition -menu: - - trigger: prd - workflow: '{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml' -``` - -**Slash command format:** - -``` -/bmad:{module}:workflows:{workflow-name} - -Examples: -/bmad:bmm:workflows:prd -/bmad:bmm:workflows:dev-story -/bmad:core:workflows:party-mode -``` - -### Workflow Components - -Every workflow directory contains: - -- `workflow.yaml` - Configuration and metadata -- `instructions.md` - Step-by-step execution guide (XML/Markdown) -- `template.md` (optional) - Output document template -- `checklist.md` (optional) - Validation criteria -- Additional data files (CSV, YAML) referenced in instructions - -### Creating New Workflows - -Use BMad Builder module: - -``` -Load bmb agent → *create-workflow -``` - -Follows BMAD v6 conventions: - -- YAML-based configuration -- XML-tagged instructions -- Template-driven or action-based -- Validation checklists - ---- - -## Module Development - -### Adding a New Module - -1. Create directory: `src/modules/{your-module}/` -2. Required structure: - ``` - {module}/ - ├── agents/ # Agent YAML definitions - ├── workflows/ # Workflow directories - ├── _module-installer/ - │ └── installer-manifest.yaml - └── README.md - ``` -3. Register in `tools/cli/modules/` for installation support - -### Agent YAML Schema - -Required fields: - -```yaml -agent: - metadata: - id: 'bmad/{module}/agents/{name}.md' - name: 'Agent Name' - title: 'Agent Title' - icon: '🎯' - module: '{module}' - - persona: - role: 'Role description' - identity: 'Background and expertise' - communication_style: 'How agent communicates' - principles: - - 'Core principle 1' - - 'Core principle 2' - - menu: - - trigger: workflow-name - workflow: '{project-root}/bmad/{module}/workflows/{path}/workflow.yaml' - description: 'Workflow description' -``` - -**Validation:** Run `npm run validate:schemas` to check agent YAML compliance. - ---- - -## Critical Implementation Notes - -### When Editing TEA Workflows - -1. **Always consult tea-index.csv** before modifying knowledge fragments -2. **21 fragments total** - don't break the index -3. **TEA operates in Phase 2 and Phase 4 only** (no Phase 3 workflows) -4. **test-design is per-epic** - outputs `test-design-epic-{N}.md` - -### When Editing Workflow Status Paths - -**Location:** `src/modules/bmm/workflows/workflow-status/paths/*.yaml` - -**Only include phase-level gates:** - -- ✅ Include: `*prd`, `*architecture`, `*sprint-planning` (once per project) -- ❌ Don't include: `*test-design`, `*create-story`, `*atdd`, `*automate` (per-epic/per-story) - -**Reason:** workflow-status tracks planning phases. Per-epic/per-story workflows tracked in sprint-status.yaml. - -### Phase vs Track vs Field Type - -**Don't confuse these three dimensions:** - -**3 Planning Tracks** (how much planning): - -- Quick Flow (tech-spec only) -- BMad Method (PRD + Architecture) -- Enterprise Method (BMad Method + extended) - -**2 Field Types** (project state): - -- Greenfield (new project) -- Brownfield (existing codebase) - -**4 Phases** (when): - -- Phase 1: Analysis (optional) -- Phase 2: Planning (required) -- Phase 3: Solutioning (track-dependent) -- Phase 4: Implementation (required) - -**Example:** "Enterprise Method Track for Brownfield" = Track (Enterprise) + Field Type (Brownfield) spanning Phases 0-4. - -### Document Editing Conventions - -**When updating phase-related documentation:** - -- Use consistent phase numbering (Phase 1-4, not Level 0-4) -- Reference the 3 tracks (Quick Flow, BMad Method, Enterprise) -- For TEA: Always show `*test-design` as per-epic in Phase 4 - -**Key documents:** - -- `src/modules/bmm/docs/test-architecture.md` - TEA agent guide -- `src/modules/bmm/docs/scale-adaptive-system.md` - 3-track explanation -- `src/modules/bmm/docs/workflows-*.md` - Phase-specific workflow guides - ---- - -## Installation System Architecture - -### Compilation Flow - -``` -1. User runs: npx bmad-method@alpha install - ↓ -2. CLI prompts: module selection, IDE choice, user preferences - ↓ -3. For each module: - - Copy files from src/modules/{module}/ to {target}/bmad/{module}/ - - Compile agents: YAML → Markdown (using tools/cli/compiler/) - - Merge customization files if exist - - Generate manifests (agent-manifest.csv, workflow-manifest.csv) - ↓ -4. IDE Integration: - - Generate slash commands for selected IDE - - Create IDE-specific config files - - Execute platform hooks (if defined) - ↓ -5. Post-install: - - Display success message with next steps - - Create bmad/_cfg/ structure for future customizations -``` - -### Module Manifests - -**agent-manifest.csv:** - -- Lists all agents for a module -- Format: `name,title,icon,description,agent_file_path` -- Auto-generated during installation -- Used by party-mode to discover agents - -**workflow-manifest.csv:** - -- Lists all workflows with their commands -- Format: `command,workflow_path,description` -- Powers slash command discovery - -### Cross-Module Dependencies - -**Example:** BMM's `*brainstorm-project` uses CIS's brainstorming workflow. - -**Resolution:** 4-pass dependency system in installer: - -1. Direct dependencies declared in installer-manifest.yaml -2. Workflow invocations parsed from instructions.md -3. Shared task references resolved -4. Circular dependency detection - ---- - -## Testing Patterns in This Repo - -### Agent Schema Tests - -**Location:** `test/fixtures/agent-schema/` - -**Structure:** - -``` -valid/ # Should pass validation -├── critical-actions/ -├── menu-items/ -└── ... - -invalid/ # Should fail validation -├── missing-required-fields/ -├── invalid-types/ -└── ... -``` - -**Test metadata in YAML comments:** - -```yaml -# Expected: FAIL -# Error code: INVALID_TYPE -# Error path: agent.metadata.name -``` - -**Runner:** `test/test-agent-schema.js` parses metadata and validates expectations. - -### Adding Test Cases - -1. Create YAML file in appropriate directory (valid/ or invalid/) -2. Add metadata comments for expected behavior -3. Run `npm test` to verify - ---- - -## Common Development Scenarios - -### Updating an Agent - -1. Edit source: `src/modules/{module}/agents/{name}.agent.yaml` -2. Test locally: `npm run install:bmad` (installs to ./bmad/) -3. Validate: `npm run validate:schemas` -4. Bundle for web: `npm run bundle` (if agent has `forWebBundle: true`) - -### Creating a New Workflow - -**Use BMB module:** - -``` -Load bmb agent → *create-workflow -``` - -**Manual creation:** - -1. Create directory: `src/modules/{module}/workflows/{category}/{name}/` -2. Required files: - - `workflow.yaml` - Configuration - - `instructions.md` - Step-by-step execution - - `template.md` (if template-based workflow) -3. Add to parent agent's menu in `agents/{agent}.agent.yaml` -4. Test by running workflow in IDE - -### Modifying TEA Knowledge Base - -1. Edit fragment: `src/modules/bmm/testarch/knowledge/{fragment}.md` -2. Update index: `src/modules/bmm/testarch/tea-index.csv` (if adding/removing) -3. Reference in TEA critical_actions or workflow instructions -4. Test by loading TEA agent and running workflows that use the fragment - ---- - -## Documentation Maintenance - -### Key Documentation Files - -**Module-level:** - -- `src/modules/bmm/docs/README.md` - Documentation hub (index to all BMM guides) -- `src/modules/bmm/docs/agents-guide.md` - All 12 agents (45 min read) -- `src/modules/bmm/docs/test-architecture.md` - TEA comprehensive guide -- `src/modules/bmm/docs/workflows-{phase}.md` - Phase-specific workflow guides - -**Project-level:** - -- `README.md` - Main project overview -- `docs/index.md` - Complete documentation map -- `CONTRIBUTING.md` - Contribution guidelines - -### Redoc System - -**BMB has automated documentation workflow:** - -``` -/bmad:bmb:workflows:redoc -``` - -Uses reverse-tree approach (leaf folders first, then parents) to maintain module documentation. - -### When to Update Documentation - -**After changing:** - -- Agent definitions → Update `agents-guide.md` -- Workflow behavior → Update phase-specific `workflows-*.md` -- Phase structure → Update `scale-adaptive-system.md`, `test-architecture.md` -- TEA knowledge → Update `tea-index.csv` and `test-architecture.md` - -**After new features:** - -- Update relevant README.md files -- Consider adding FAQ entries -- Update glossary if new terminology - ---- - -## Git Workflow - -**Main branch:** `main` - Production-ready code -**Development:** Feature branches with descriptive names - -**Commit message format (auto-enforced by hooks):** - -``` -type: brief description - -Detailed explanation if needed -Related to #123 -``` - -**Git Hooks (via Husky):** - -- **Pre-commit:** `.husky/pre-commit` - Two-stage validation - 1. `lint-staged` - Auto-fixes changed files and stages them (linting + formatting) - 2. `npm test` - Validates everything (schemas, compilation, bundles, lint, format) - -**Why lint-staged?** It automatically stages the auto-fixed files so they're included in the commit. Without it, fixes would be made but not committed. - -**CI Workflow:** `.github/workflows/quality.yaml` runs all quality checks in parallel on PRs (6 jobs: prettier, eslint, schema-validation, agent-schema-tests, installation-components, bundle-validation) - -**Release process:** GitHub Actions workflows (triggered by npm run release:\* commands) - ---- - -## IDE-Specific Notes - -**Slash command format varies:** - -- **Claude Code:** `/bmad:bmm:workflows:prd` -- **Cursor/Windsurf:** May use different syntax -- **VS Code:** Check IDE-specific docs - -**Configuration location:** - -- Claude Code: `.claude/` directory -- Cursor: `.cursor/` or `.cursorrules` -- See `docs/ide-info/` for IDE-specific setup - ---- - -## Troubleshooting Development Issues - -**Agent not showing in menu:** - -- Check `bmad/{module}/agents/agent-manifest.csv` was generated -- Verify agent YAML compiles: `npm run validate:schemas` -- Reinstall: `npm run install:bmad` - -**Workflow not executing:** - -- Verify workflow.yaml has all required fields -- Check instructions.md syntax (XML tags must close) -- Ensure config_source points to valid config.yaml - -**Bundle validation fails:** - -- Run `npm run validate:bundles` for detailed errors -- Check web_bundle: true in workflow.yaml if bundling workflow -- Verify all dependencies are embedded (no file paths in bundles) - ---- - -**Repository Documentation:** Complete guides in `src/modules/bmm/docs/README.md`