diff --git a/.github/workflows/claude-code-review.yaml b/.github/workflows/claude-code-review.yaml
new file mode 100644
index 00000000..da0b6b59
--- /dev/null
+++ b/.github/workflows/claude-code-review.yaml
@@ -0,0 +1,203 @@
+# Sample Claude Code Review Workflow
+#
+# This is a template workflow that demonstrates how to set up automated code reviews
+# using Claude via GitHub Actions. Customize the prompt and focus areas for your project.
+#
+# To use this workflow:
+# 1. Use Claude Code command in your terminal: /install-github-app , this holds your hand throughout the setup
+# 2. Copy this file over to your repository's .github/workflows/claude-code-review.yml , which gets auto-generated
+# 3. Add ANTHROPIC_API_KEY to your repository secrets
+# 4. Customize the prompt section for your project's specific needs
+# 5. Adjust the focus areas, tools, and model as needed
+
+name: Claude Code Review - BMAD Method
+
+on:
+ pull_request:
+ types: [opened, synchronize, ready_for_review, reopened]
+
+# if this branch is pushed back to back, cancel the older branch's workflow
+concurrency:
+ group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ claude-review:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write
+ issues: read
+ id-token: write
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Run Claude Code Review
+ id: claude-review
+ uses: anthropics/claude-code-action@v1
+ with:
+ # Using API key for per-token billing plan
+ anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+ # Track progress creates a comment showing review progress
+ track_progress: true
+
+ prompt: |
+ REPO: ${{ github.repository }}
+ PR NUMBER: ${{ github.event.pull_request.number }}
+
+ # BMAD-METHOD Repository - AI Agent Framework
+
+ IMPORTANT: Skip reviewing files in these directories:
+ - docs/ (user-facing documentation)
+ - bmad/ (compiled installation output, not source)
+ - test/fixtures/ (test data files)
+ - node_modules/ (dependencies)
+
+ **Context:** This is BMAD-CORE, a universal human-AI collaboration framework with YAML-based agent definitions and XML-tagged workflow instructions.
+
+ Perform comprehensive code review focusing on BMAD-specific patterns:
+
+ ## 1. Agent YAML Schema Compliance (CRITICAL)
+
+ **For files in `src/modules/*/agents/*.agent.yaml`:**
+ - ✅ Required fields: metadata (id, name, title, icon, module), persona (role, identity, communication_style, principles), menu items
+ - ✅ Menu triggers must reference valid workflow paths: `{project-root}/bmad/{module}/workflows/{path}/workflow.yaml`
+ - ✅ Critical actions syntax (if TEA agent): Must reference tea-index.csv and knowledge fragments
+ - ✅ Schema validation: Run `npm run validate:schemas` to verify compliance
+ - ❌ No hardcoded file paths outside {project-root} or {installed_path}
+ - ❌ No duplicate menu triggers within an agent
+
+ ## 2. Workflow Definition Integrity
+
+ **For files in `src/modules/*/workflows/**/workflow.yaml`:**
+ - ✅ Required fields: name, config_source, instructions, default_output_file (if template-based)
+ - ✅ Variable resolution: Use {config_source}, {project-root}, {installed_path}, {output_folder}
+ - ✅ Instructions path must exist: `{installed_path}/instructions.md`
+ - ✅ Template path (if template workflow): `{installed_path}/template.md`
+ - ❌ No absolute paths - use variable placeholders
+
+ **For `instructions.md` files:**
+ - ✅ XML tag syntax: ``, ``, `section`, ``
+ - ✅ Steps must have sequential numbering (1, 2, 3...)
+ - ✅ All XML tags must close properly (e.g., ``, ``)
+ - ✅ Template-output tags reference actual template sections
+ - ❌ No malformed XML that breaks workflow execution engine
+
+ ## 3. TEA Knowledge Base Integrity
+
+ **For changes in `src/modules/bmm/testarch/`:**
+ - ✅ tea-index.csv must match knowledge/ directory (21 fragments indexed)
+ - ✅ Fragment file names match csv entries exactly
+ - ✅ TEA agent critical_actions reference tea-index.csv correctly
+ - ✅ Knowledge fragments maintain consistent format
+ - ❌ Don't break the index-fragment relationship
+
+ ## 4. Documentation Consistency (Phase & Track Terminology)
+
+ **For changes in `src/modules/bmm/docs/`:**
+ - ✅ Use 3-track terminology: Quick Flow, BMad Method, Enterprise Method (not Level 0-4)
+ - ✅ Phase numbering: Phase 1 (Analysis), Phase 2 (Planning), Phase 3 (Solutioning), Phase 4 (Implementation)
+ - ✅ TEA operates in Phase 2 and Phase 4 only (not "all phases")
+ - ✅ `*test-design` is per-epic in Phase 4 (not per-project in Phase 2/3)
+ - ❌ Don't mix YAML phase numbers (0-indexed) with doc phase numbers (1-indexed) without context
+
+ **For changes in workflow-status YAML paths:**
+ - ✅ Only include phase-gate workflows (prd, architecture, sprint-planning)
+ - ❌ Don't include per-epic/per-story workflows (test-design, create-story, atdd, automate)
+ - Note: Per-epic/per-story workflows tracked in sprint-status.yaml, not workflow-status.yaml
+
+ ## 5. Cross-Module Dependencies
+
+ - ✅ Verify workflow invocations reference valid paths
+ - ✅ Module dependencies declared in installer-manifest.yaml
+ - ✅ Shared task references resolve correctly
+ - ❌ No circular dependencies between modules
+
+ ## 6. Compilation & Installation
+
+ **For changes affecting `tools/cli/`:**
+ - ✅ Agent compilation: YAML → Markdown/XML for both IDE and web bundle targets
+ - ✅ forWebBundle flag changes compilation behavior (inline vs file paths)
+ - ✅ Manifest generation creates agent-manifest.csv and workflow-manifest.csv
+ - ✅ Platform-specific hooks execute for IDE integrations
+
+ ## 7. Code Quality (Node.js/JavaScript)
+
+ - ✅ Modern JavaScript (ES6+, async/await, proper error handling)
+ - ✅ Schema validation with Zod where applicable
+ - ✅ Proper YAML parsing with js-yaml
+ - ✅ File operations use fs-extra for better error handling
+ - ❌ No synchronous file I/O in async contexts
+
+ ## Review Guidelines
+
+ - Reference CLAUDE.md for repository architecture
+ - Check CONTRIBUTING.md for contribution guidelines
+ - **Validation commands** (deterministic tests):
+ - `npm test` - Comprehensive quality checks (all validations + linting + formatting)
+ - `npm run test:schemas` - Agent schema validation tests (fixture-based)
+ - `npm run test:install` - Installation component tests (compilation)
+ - `npm run validate:schemas` - YAML schema validation
+ - `npm run validate:bundles` - Web bundle integrity
+ - `npm run lint` - ESLint compliance
+ - `npm run format:check` - Prettier formatting
+ - Prioritize issues: **Critical** (breaks workflows/compilation) > **High** (schema violations) > **Medium** (inconsistency) > **Low** (style)
+ - Be specific with file paths and line numbers
+
+ Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+ # Using Sonnet 4.5 for comprehensive reviews
+ # Available models: claude-opus-4-1-20250805, claude-sonnet-4-5-20250929, etc.
+ # Tools can be restricted based on what review actions you want to allow
+ claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+
+ # SETUP INSTRUCTIONS
+# ==================
+#
+# 1. Repository Secrets Setup:
+# - Go to your repository � Settings � Secrets and variables � Actions
+# - Click "New repository secret"
+# - Name: ANTHROPIC_API_KEY
+# - Value: Your Anthropic API key (get one from https://console.anthropic.com/)
+#
+# 2. Permissions:
+# - The workflow needs 'pull-requests: write' to comment on PRs
+# - The workflow needs 'contents: read' to access repository code
+# - The workflow needs 'issues: read' for GitHub CLI operations
+#
+# 3. Customization:
+# - Update the prompt section to match your project's needs
+# - Add project-specific file/directory exclusions
+# - Customize the focus areas based on your tech stack
+# - Adjust the model (opus for more thorough reviews, sonnet for faster)
+# - Modify allowed tools based on what actions you want Claude to perform
+#
+# 4. Testing:
+# - Create a test PR to verify the workflow runs correctly
+# - Check that Claude can comment on the PR
+# - Ensure the review quality meets your standards
+#
+# 5. Advanced Customization:
+# - Add conditional logic based on file types or changes
+# - Integrate with other GitHub Actions (linting, testing, etc.)
+# - Set up different review levels based on PR size or author
+# - Add custom review templates for different types of changes
+#
+# TROUBLESHOOTING
+# ===============
+#
+# Common Issues:
+# - "Authentication failed" � Check ANTHROPIC_API_KEY secret
+# - "Permission denied" � Verify workflow permissions in job definition
+# - "No comments posted" � Check allowed tools and gh CLI permissions
+# - "Review too generic" � Customize prompt with project-specific guidance
+#
+# For more help:
+# - GitHub Actions documentation: https://docs.github.com/en/actions
+# - Claude Code Action: https://github.com/anthropics/claude-code-action
+# - Anthropic API documentation: https://docs.anthropic.com/
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
deleted file mode 100644
index 6d8fab2a..00000000
--- a/.github/workflows/lint.yaml
+++ /dev/null
@@ -1,61 +0,0 @@
-name: lint
-
-"on":
- pull_request:
- branches: ["**"]
- workflow_dispatch:
-
-jobs:
- prettier:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: Prettier format check
- run: npm run format:check
-
- eslint:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: ESLint
- run: npm run lint
-
- schema-validation:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: Validate YAML schemas
- run: npm run validate:schemas
diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml
new file mode 100644
index 00000000..7a32718b
--- /dev/null
+++ b/.github/workflows/quality.yaml
@@ -0,0 +1,123 @@
+name: Quality & Validation
+
+# Runs comprehensive quality checks on all PRs:
+# - Prettier (formatting)
+# - ESLint (linting)
+# - Schema validation (YAML structure)
+# - Agent schema tests (fixture-based validation)
+# - Installation component tests (compilation)
+# - Bundle validation (web bundle integrity)
+
+"on":
+ pull_request:
+ branches: ["**"]
+ workflow_dispatch:
+
+jobs:
+ prettier:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Prettier format check
+ run: npm run format:check
+
+ eslint:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: ESLint
+ run: npm run lint
+
+ schema-validation:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Validate YAML schemas
+ run: npm run validate:schemas
+
+ agent-schema-tests:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run agent schema validation tests
+ run: npm run test:schemas
+
+ installation-components:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Test agent compilation components
+ run: npm run test:install
+
+ bundle-validation:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Validate web bundles
+ run: npm run validate:bundles
diff --git a/.gitignore b/.gitignore
index 9eff8ef1..e55e43e0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,7 +34,7 @@ Thumbs.db
.bmad*/.cursor/
# AI assistant files
-CLAUDE.md
+# CLAUDE.md # we need this for Claude Code reviews
.ai/*
cursor
.gemini
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 7e617c2c..1397d511 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,3 +1,7 @@
#!/usr/bin/env sh
+# Auto-fix changed files and stage them
npx --no-install lint-staged
+
+# Validate everything
+npm test
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..89e735e6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,670 @@
+# 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`
diff --git a/README.md b/README.md
index e9151d4e..d9e8c690 100644
--- a/README.md
+++ b/README.md
@@ -35,11 +35,15 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo
- [C.O.R.E. Philosophy](#core-philosophy)
- [Modules](#modules)
- [BMad Method (BMM) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development)
+ - [v6 Highlights](#v6-highlights)
+ - [🚀 Quick Start](#-quick-start)
- [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions)
- [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
- - [🚀 Quick Start](#-quick-start)
- [Installation](#installation)
- [🎯 Working with Agents \& Commands](#-working-with-agents--commands)
+ - [Method 1: Agent Menu (Recommended for Beginners)](#method-1-agent-menu-recommended-for-beginners)
+ - [Method 2: Direct Slash Commands](#method-2-direct-slash-commands)
+ - [Method 3: Party Mode Execution](#method-3-party-mode-execution)
- [Key Features](#key-features)
- [🎨 Update-Safe Customization](#-update-safe-customization)
- [🚀 Intelligent Installation](#-intelligent-installation)
@@ -47,6 +51,10 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo
- [📄 Document Sharding (Advanced)](#-document-sharding-advanced)
- [Documentation](#documentation)
- [Community \& Support](#community--support)
+ - [Development \& Quality Checks](#development--quality-checks)
+ - [Testing \& Validation](#testing--validation)
+ - [Code Quality](#code-quality)
+ - [Build \& Development](#build--development)
- [Contributing](#contributing)
- [License](#license)
@@ -352,6 +360,56 @@ Optional optimization for large projects (BMad Method and Enterprise tracks):
---
+## Development & Quality Checks
+
+**For contributors working on the BMAD codebase:**
+
+**Requirements:** Node.js 22+ (see `.nvmrc`). Run `nvm use` to switch to the correct version.
+
+### 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
+```
+
+### Code Quality
+
+```bash
+# Lint check
+npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+
+# Format check
+npm run format:check
+
+# Auto-format all files
+npm run format:fix
+```
+
+### Build & Development
+
+```bash
+# Bundle for web deployment
+npm run bundle
+
+# Test local installation
+npm run install:bmad
+```
+
+**Pre-commit Hook:** Auto-fixes changed files (lint-staged) + validates everything (npm test)
+**CI:** GitHub Actions runs all quality checks in parallel on every PR
+
+---
+
## Contributing
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
diff --git a/package-lock.json b/package-lock.json
index 4de233c1..c7a06422 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bmad-method",
- "version": "6.0.0-alpha.5",
+ "version": "6.0.0-alpha.6",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bmad-method",
- "version": "6.0.0-alpha.5",
+ "version": "6.0.0-alpha.6",
"license": "MIT",
"dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1",
diff --git a/package.json b/package.json
index eb9a75c0..41f56180 100644
--- a/package.json
+++ b/package.json
@@ -39,8 +39,10 @@
"release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
"release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
"release:watch": "gh run watch",
- "test": "node test/test-agent-schema.js",
- "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js",
+ "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check",
+ "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+ "test:install": "node test/test-installation-components.js",
+ "test:schemas": "node test/test-agent-schema.js",
"validate:bundles": "node tools/validate-bundles.js",
"validate:schemas": "node tools/validate-agent-schema.js"
},
diff --git a/test/test-installation-components.js b/test/test-installation-components.js
new file mode 100644
index 00000000..464ca613
--- /dev/null
+++ b/test/test-installation-components.js
@@ -0,0 +1,214 @@
+/**
+ * Installation Component Tests
+ *
+ * Tests individual installation components in isolation:
+ * - Agent YAML → XML compilation
+ * - Manifest generation
+ * - Path resolution
+ * - Customization merging
+ *
+ * These are deterministic unit tests that don't require full installation.
+ * Usage: node test/test-installation-components.js
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder');
+const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator');
+
+// ANSI colors
+const colors = {
+ reset: '\u001B[0m',
+ green: '\u001B[32m',
+ red: '\u001B[31m',
+ yellow: '\u001B[33m',
+ cyan: '\u001B[36m',
+ dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+/**
+ * Test helper: Assert condition
+ */
+function assert(condition, testName, errorMessage = '') {
+ if (condition) {
+ console.log(`${colors.green}✓${colors.reset} ${testName}`);
+ passed++;
+ } else {
+ console.log(`${colors.red}✗${colors.reset} ${testName}`);
+ if (errorMessage) {
+ console.log(` ${colors.dim}${errorMessage}${colors.reset}`);
+ }
+ failed++;
+ }
+}
+
+/**
+ * Test Suite
+ */
+async function runTests() {
+ console.log(`${colors.cyan}========================================`);
+ console.log('Installation Component Tests');
+ console.log(`========================================${colors.reset}\n`);
+
+ const projectRoot = path.join(__dirname, '..');
+
+ // ============================================================
+ // Test 1: YAML → XML Agent Compilation (In-Memory)
+ // ============================================================
+ console.log(`${colors.yellow}Test Suite 1: Agent Compilation${colors.reset}\n`);
+
+ try {
+ const builder = new YamlXmlBuilder();
+ const pmAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/pm.agent.yaml');
+
+ // Create temp output path
+ const tempOutput = path.join(__dirname, 'temp-pm-agent.md');
+
+ try {
+ const result = await builder.buildAgent(pmAgentPath, null, tempOutput, { includeMetadata: true });
+
+ assert(result && result.outputPath === tempOutput, 'Agent compilation returns result object with outputPath');
+
+ // Read the output
+ const compiled = await fs.readFile(tempOutput, 'utf8');
+
+ assert(compiled.includes(' tag');
+
+ assert(compiled.includes(''), 'Compiled agent contains tag');
+
+ assert(compiled.includes('