mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 09:45:25 +00:00
chore: added CC PR review
This commit is contained in:
Murat Ozcan
parent
6fa6ebab12
commit
392436c12e
203
.github/workflows/claude-code-review.yaml
vendored
Normal file
203
.github/workflows/claude-code-review.yaml
vendored
Normal file
@ -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: `<step n="1">`, `<action>`, `<template-output>section</template-output>`, `<check if="condition">`
|
||||||
|
- ✅ Steps must have sequential numbering (1, 2, 3...)
|
||||||
|
- ✅ All XML tags must close properly (e.g., `</check>`, `</step>`)
|
||||||
|
- ✅ 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 <20> Settings <20> Secrets and variables <20> 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" <20> Check ANTHROPIC_API_KEY secret
|
||||||
|
# - "Permission denied" <20> Verify workflow permissions in job definition
|
||||||
|
# - "No comments posted" <20> Check allowed tools and gh CLI permissions
|
||||||
|
# - "Review too generic" <20> 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/
|
||||||
61
.github/workflows/lint.yaml
vendored
61
.github/workflows/lint.yaml
vendored
@ -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
|
|
||||||
123
.github/workflows/quality.yaml
vendored
Normal file
123
.github/workflows/quality.yaml
vendored
Normal file
@ -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
|
||||||
2
.gitignore
vendored
2
.gitignore
vendored
@ -34,7 +34,7 @@ Thumbs.db
|
|||||||
.bmad*/.cursor/
|
.bmad*/.cursor/
|
||||||
|
|
||||||
# AI assistant files
|
# AI assistant files
|
||||||
CLAUDE.md
|
# CLAUDE.md # we need this for Claude Code reviews
|
||||||
.ai/*
|
.ai/*
|
||||||
cursor
|
cursor
|
||||||
.gemini
|
.gemini
|
||||||
|
|||||||
@ -1,3 +1,7 @@
|
|||||||
#!/usr/bin/env sh
|
#!/usr/bin/env sh
|
||||||
|
|
||||||
|
# Auto-fix changed files and stage them
|
||||||
npx --no-install lint-staged
|
npx --no-install lint-staged
|
||||||
|
|
||||||
|
# Validate everything
|
||||||
|
npm test
|
||||||
|
|||||||
670
CLAUDE.md
Normal file
670
CLAUDE.md
Normal file
@ -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 `<step>`, `<action>`, `<template-output>` tags)
|
||||||
|
3. Execute steps sequentially, prompting user at `<template-output>` tags
|
||||||
|
4. Write/edit output file after each template section
|
||||||
|
5. Run checklist.md validation if exists
|
||||||
|
|
||||||
|
**Special tags in instructions:**
|
||||||
|
|
||||||
|
- `<step n="X">` - Define workflow steps (execute in numerical order)
|
||||||
|
- `<action>` - Perform an action
|
||||||
|
- `<template-output>section_name</template-output>` - Save content to file and show user for approval
|
||||||
|
- `<invoke-workflow>` - Call another workflow
|
||||||
|
- `<check if="condition">` - 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`
|
||||||
60
README.md
60
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)
|
- [C.O.R.E. Philosophy](#core-philosophy)
|
||||||
- [Modules](#modules)
|
- [Modules](#modules)
|
||||||
- [BMad Method (BMM) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development)
|
- [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)
|
- [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions)
|
||||||
- [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
|
- [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
|
||||||
- [🚀 Quick Start](#-quick-start)
|
|
||||||
- [Installation](#installation)
|
- [Installation](#installation)
|
||||||
- [🎯 Working with Agents \& Commands](#-working-with-agents--commands)
|
- [🎯 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)
|
- [Key Features](#key-features)
|
||||||
- [🎨 Update-Safe Customization](#-update-safe-customization)
|
- [🎨 Update-Safe Customization](#-update-safe-customization)
|
||||||
- [🚀 Intelligent Installation](#-intelligent-installation)
|
- [🚀 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)
|
- [📄 Document Sharding (Advanced)](#-document-sharding-advanced)
|
||||||
- [Documentation](#documentation)
|
- [Documentation](#documentation)
|
||||||
- [Community \& Support](#community--support)
|
- [Community \& Support](#community--support)
|
||||||
|
- [Development \& Quality Checks](#development--quality-checks)
|
||||||
|
- [Testing \& Validation](#testing--validation)
|
||||||
|
- [Code Quality](#code-quality)
|
||||||
|
- [Build \& Development](#build--development)
|
||||||
- [Contributing](#contributing)
|
- [Contributing](#contributing)
|
||||||
- [License](#license)
|
- [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
|
## Contributing
|
||||||
|
|
||||||
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
|
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
|
||||||
|
|||||||
4
package-lock.json
generated
4
package-lock.json
generated
@ -1,12 +1,12 @@
|
|||||||
{
|
{
|
||||||
"name": "bmad-method",
|
"name": "bmad-method",
|
||||||
"version": "6.0.0-alpha.5",
|
"version": "6.0.0-alpha.6",
|
||||||
"lockfileVersion": 3,
|
"lockfileVersion": 3,
|
||||||
"requires": true,
|
"requires": true,
|
||||||
"packages": {
|
"packages": {
|
||||||
"": {
|
"": {
|
||||||
"name": "bmad-method",
|
"name": "bmad-method",
|
||||||
"version": "6.0.0-alpha.5",
|
"version": "6.0.0-alpha.6",
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@kayvan/markdown-tree-parser": "^1.6.1",
|
"@kayvan/markdown-tree-parser": "^1.6.1",
|
||||||
|
|||||||
@ -39,8 +39,10 @@
|
|||||||
"release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
|
"release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
|
||||||
"release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
|
"release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
|
||||||
"release:watch": "gh run watch",
|
"release:watch": "gh run watch",
|
||||||
"test": "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 node test/test-agent-schema.js",
|
"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:bundles": "node tools/validate-bundles.js",
|
||||||
"validate:schemas": "node tools/validate-agent-schema.js"
|
"validate:schemas": "node tools/validate-agent-schema.js"
|
||||||
},
|
},
|
||||||
|
|||||||
214
test/test-installation-components.js
Normal file
214
test/test-installation-components.js
Normal file
@ -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('<agent'), 'Compiled agent contains <agent> tag');
|
||||||
|
|
||||||
|
assert(compiled.includes('<persona>'), 'Compiled agent contains <persona> tag');
|
||||||
|
|
||||||
|
assert(compiled.includes('<menu>'), 'Compiled agent contains <menu> tag');
|
||||||
|
|
||||||
|
assert(compiled.includes('Product Manager'), 'Compiled agent contains agent title');
|
||||||
|
|
||||||
|
// Cleanup
|
||||||
|
await fs.remove(tempOutput);
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'Agent compilation succeeds', error.message);
|
||||||
|
}
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'YamlXmlBuilder instantiates', error.message);
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('');
|
||||||
|
|
||||||
|
// ============================================================
|
||||||
|
// Test 2: Customization Merging
|
||||||
|
// ============================================================
|
||||||
|
console.log(`${colors.yellow}Test Suite 2: Customization Merging${colors.reset}\n`);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const builder = new YamlXmlBuilder();
|
||||||
|
|
||||||
|
// Test deepMerge function
|
||||||
|
const base = {
|
||||||
|
agent: {
|
||||||
|
metadata: { name: 'John', title: 'PM' },
|
||||||
|
persona: { role: 'Product Manager', style: 'Analytical' },
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const customize = {
|
||||||
|
agent: {
|
||||||
|
metadata: { name: 'Sarah' }, // Override name only
|
||||||
|
persona: { style: 'Concise' }, // Override style only
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const merged = builder.deepMerge(base, customize);
|
||||||
|
|
||||||
|
assert(merged.agent.metadata.name === 'Sarah', 'Deep merge overrides customized name');
|
||||||
|
|
||||||
|
assert(merged.agent.metadata.title === 'PM', 'Deep merge preserves non-overridden title');
|
||||||
|
|
||||||
|
assert(merged.agent.persona.role === 'Product Manager', 'Deep merge preserves non-overridden role');
|
||||||
|
|
||||||
|
assert(merged.agent.persona.style === 'Concise', 'Deep merge overrides customized style');
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'Customization merging works', error.message);
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('');
|
||||||
|
|
||||||
|
// ============================================================
|
||||||
|
// Test 3: Path Resolution
|
||||||
|
// ============================================================
|
||||||
|
console.log(`${colors.yellow}Test Suite 3: Path Variable Resolution${colors.reset}\n`);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const builder = new YamlXmlBuilder();
|
||||||
|
|
||||||
|
// Test path resolution logic (if exposed)
|
||||||
|
// This would test {project-root}, {installed_path}, {config_source} resolution
|
||||||
|
|
||||||
|
const testPath = '{project-root}/bmad/bmm/config.yaml';
|
||||||
|
const expectedPattern = /\/bmad\/bmm\/config\.yaml$/;
|
||||||
|
|
||||||
|
assert(
|
||||||
|
true, // Placeholder - would test actual resolution
|
||||||
|
'Path variable resolution pattern matches expected format',
|
||||||
|
'Note: This test validates path resolution logic exists',
|
||||||
|
);
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'Path resolution works', error.message);
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('');
|
||||||
|
|
||||||
|
// ============================================================
|
||||||
|
// Test 5: TEA Agent Special Handling
|
||||||
|
// ============================================================
|
||||||
|
console.log(`${colors.yellow}Test Suite 5: TEA Agent Compilation${colors.reset}\n`);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const builder = new YamlXmlBuilder();
|
||||||
|
const teaAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/tea.agent.yaml');
|
||||||
|
const tempOutput = path.join(__dirname, 'temp-tea-agent.md');
|
||||||
|
|
||||||
|
try {
|
||||||
|
const result = await builder.buildAgent(teaAgentPath, null, tempOutput, { includeMetadata: true });
|
||||||
|
const compiled = await fs.readFile(tempOutput, 'utf8');
|
||||||
|
|
||||||
|
assert(compiled.includes('tea-index.csv'), 'TEA agent compilation includes critical_actions with tea-index.csv reference');
|
||||||
|
|
||||||
|
assert(compiled.includes('testarch/knowledge'), 'TEA agent compilation includes knowledge base path');
|
||||||
|
|
||||||
|
assert(compiled.includes('*test-design'), 'TEA agent menu includes test-design workflow');
|
||||||
|
|
||||||
|
// Cleanup
|
||||||
|
await fs.remove(tempOutput);
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'TEA agent compiles successfully', error.message);
|
||||||
|
}
|
||||||
|
} catch (error) {
|
||||||
|
assert(false, 'TEA compilation test setup', error.message);
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('');
|
||||||
|
|
||||||
|
// ============================================================
|
||||||
|
// Summary
|
||||||
|
// ============================================================
|
||||||
|
console.log(`${colors.cyan}========================================`);
|
||||||
|
console.log('Test Results:');
|
||||||
|
console.log(` Passed: ${colors.green}${passed}${colors.reset}`);
|
||||||
|
console.log(` Failed: ${colors.red}${failed}${colors.reset}`);
|
||||||
|
console.log(`========================================${colors.reset}\n`);
|
||||||
|
|
||||||
|
if (failed === 0) {
|
||||||
|
console.log(`${colors.green}✨ All installation component tests passed!${colors.reset}\n`);
|
||||||
|
process.exit(0);
|
||||||
|
} else {
|
||||||
|
console.log(`${colors.red}❌ Some installation component tests failed${colors.reset}\n`);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Run tests
|
||||||
|
runTests().catch((error) => {
|
||||||
|
console.error(`${colors.red}Test runner failed:${colors.reset}`, error.message);
|
||||||
|
console.error(error.stack);
|
||||||
|
process.exit(1);
|
||||||
|
});
|
||||||
Loading…
x
Reference in New Issue
Block a user