mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 09:45:25 +00:00
remove CLAUDE.md
This commit is contained in:
Murat Ozcan
parent
e340f29807
commit
ec07fd594b
2
.gitignore
vendored
2
.gitignore
vendored
@ -34,7 +34,7 @@ Thumbs.db
|
|||||||
.bmad*/.cursor/
|
.bmad*/.cursor/
|
||||||
|
|
||||||
# AI assistant files
|
# AI assistant files
|
||||||
# CLAUDE.md # we need this for Claude Code reviews
|
CLAUDE.md
|
||||||
.ai/*
|
.ai/*
|
||||||
cursor
|
cursor
|
||||||
.gemini
|
.gemini
|
||||||
|
|||||||
670
CLAUDE.md
670
CLAUDE.md
@ -1,670 +0,0 @@
|
|||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
||||||
|
|
||||||
## Repository Overview
|
|
||||||
|
|
||||||
**BMad-CORE** is a universal human-AI collaboration framework powering multiple modules for AI-driven development, creative work, and custom solutions. The repository contains the core framework plus three official modules (BMM, BMB, CIS).
|
|
||||||
|
|
||||||
**Current version:** v6.0.0-alpha.6 (near-beta quality)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
### Testing & Validation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run ALL quality checks (comprehensive - use before pushing)
|
|
||||||
npm test
|
|
||||||
|
|
||||||
# Individual test suites
|
|
||||||
npm run test:schemas # Agent schema validation (fixture-based)
|
|
||||||
npm run test:install # Installation component tests (compilation)
|
|
||||||
npm run validate:schemas # YAML schema validation
|
|
||||||
npm run validate:bundles # Web bundle integrity
|
|
||||||
|
|
||||||
# Coverage
|
|
||||||
npm run test:coverage # Run schema tests with coverage report
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note:** Requires Node.js 22+ (see .nvmrc). Run `nvm use` to switch to correct version.
|
|
||||||
|
|
||||||
### Code Quality
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Lint check
|
|
||||||
npm run lint
|
|
||||||
|
|
||||||
# Auto-fix linting issues
|
|
||||||
npm run lint:fix
|
|
||||||
|
|
||||||
# Format check (Prettier)
|
|
||||||
npm run format:check
|
|
||||||
|
|
||||||
# Auto-format all files
|
|
||||||
npm run format:fix
|
|
||||||
```
|
|
||||||
|
|
||||||
### Building & Bundling
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Bundle all modules for web deployment
|
|
||||||
npm run bundle
|
|
||||||
|
|
||||||
# Rebundle (updates existing bundles)
|
|
||||||
npm run rebundle
|
|
||||||
|
|
||||||
# Install BMAD locally (test installer)
|
|
||||||
npm run install:bmad
|
|
||||||
```
|
|
||||||
|
|
||||||
### Releases (GitHub Actions)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Trigger manual releases (requires gh CLI)
|
|
||||||
npm run release:patch
|
|
||||||
npm run release:minor
|
|
||||||
npm run release:major
|
|
||||||
npm run release:watch # Watch release workflow status
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## High-Level Architecture
|
|
||||||
|
|
||||||
### 1. Agent Compilation System (YAML → XML/Markdown)
|
|
||||||
|
|
||||||
**Two compilation targets with different outputs:**
|
|
||||||
|
|
||||||
**IDE Installation (filesystem-aware):**
|
|
||||||
|
|
||||||
- Source: `src/modules/{module}/agents/*.agent.yaml`
|
|
||||||
- Output: `bmad/{module}/agents/{name}.md` (Markdown with XML)
|
|
||||||
- Features: File paths, customization via `bmad/_cfg/agents/`, IDE slash commands
|
|
||||||
- Compiled by: `tools/cli/bmad-cli.js install`
|
|
||||||
|
|
||||||
**Web Bundles (self-contained):**
|
|
||||||
|
|
||||||
- Source: Same YAML files
|
|
||||||
- Output: `src/modules/{module}/sub-modules/{platform}/sub-agents/{name}.md`
|
|
||||||
- Features: All dependencies embedded, no file I/O, platform-specific (claude-code, cursor, etc.)
|
|
||||||
- Compiled by: `npm run bundle`
|
|
||||||
|
|
||||||
**Key difference:** `forWebBundle: true/false` flag changes compilation behavior (paths vs inline content).
|
|
||||||
|
|
||||||
### 2. Workflow Execution Engine
|
|
||||||
|
|
||||||
**All workflows are governed by:** `src/core/tasks/workflow.xml`
|
|
||||||
|
|
||||||
**Workflow definition structure:**
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Example: src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
|
|
||||||
name: 'prd'
|
|
||||||
config_source: '{project-root}/bmad/bmm/config.yaml'
|
|
||||||
instructions: '{installed_path}/instructions.md'
|
|
||||||
template: '{installed_path}/prd-template.md'
|
|
||||||
default_output_file: '{output_folder}/PRD.md'
|
|
||||||
```
|
|
||||||
|
|
||||||
**Execution flow:**
|
|
||||||
|
|
||||||
1. Load workflow.yaml and resolve all variables (`{config_source}`, `{project-root}`, `{installed_path}`)
|
|
||||||
2. Read instructions.md (XML/Markdown with `<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`
|
|
||||||
Loading…
x
Reference in New Issue
Block a user