External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

path fixes, documentation updates, md-xplodr added to core tools

Browse Source
This commit is contained in:
Brian Madison
2025-10-26 15:03:54 -05:00
parent 8220c819e6
commit 0067fb4880
20 changed files with 650 additions and 1086 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
docs/antipattern-audit-2025-10-22.md
View File

@@ -1,328 +0,0 @@
# BMAD Workflow Conditional Execution Antipattern Audit
**Date:** 2025-10-22
**Auditor:** Claude Code (BMad Builder Agent)
**Scope:** All markdown files under `src/`
---
## Executive Summary
**Critical Issue Identified:** Invalid self-closing `<check>` tag pattern found throughout BMAD workflow codebase.
**Impact:**
- **98 instances** across **14 workflow files**
- Affects core workflows, builder workflows, and method workflows
- Creates XML parsing ambiguity and unpredictable LLM behavior
- Violates BMAD workflow specification (workflow.xml)
**Severity:** CRITICAL - Invalid XML structure, ambiguous conditional scope
---
## The Antipattern
### Invalid Pattern (Self-Closing Check)
```xml
<!-- ❌ WRONG - Invalid XML structure -->
<check>If condition met:</check>
<action>Do something</action>
<action>Do something else</action>
```
**Problems:**
1. Check tag doesn't wrap anything (invalid XML)
2. Ambiguous scope - unclear which actions are conditional
3. Breaks formatters and parsers
4. Not part of BMAD workflow spec
5. Unpredictable LLM interpretation
### Correct Patterns
**Single conditional action:**
```xml
<!-- ✅ CORRECT - Inline conditional -->
<action if="condition met">Do something</action>
```
**Multiple conditional actions:**
```xml
<!-- ✅ CORRECT - Proper wrapper block -->
<check if="condition met">
<action>Do something</action>
<action>Do something else</action>
</check>
```
---
## Audit Results
### Total Count
- **Total Instances:** 98
- **Affected Files:** 14
- **Modules Affected:** 4 (BMB, BMM, CIS, Core)
### Breakdown by File
| File | Count | Priority |
| -------------------------------------------------------------------- | ----- | ----------- |
| `modules/bmb/workflows/edit-workflow/instructions.md` | 21 | 🔴 CRITICAL |
| `modules/bmm/workflows/4-implementation/dev-story/instructions.md` | 13 | 🔴 CRITICAL |
| `modules/bmb/workflows/convert-legacy/instructions.md` | 13 | 🔴 CRITICAL |
| `modules/bmb/workflows/create-module/instructions.md` | 12 | 🔴 CRITICAL |
| `modules/bmb/workflows/create-agent/instructions.md` | 11 | 🔴 CRITICAL |
| `core/workflows/party-mode/instructions.md` | 7 | 🟡 HIGH |
| `modules/bmm/workflows/4-implementation/correct-course/checklist.md` | 5 | 🟡 HIGH |
| `core/workflows/brainstorming/instructions.md` | 5 | 🟡 HIGH |
| `modules/cis/workflows/storytelling/instructions.md` | 3 | 🟢 MEDIUM |
| `modules/bmb/workflows/audit-workflow/instructions.md` | 3 | 🟢 MEDIUM |
| `modules/bmb/workflows/create-workflow/workflow-creation-guide.md` | 2 | 🟢 MEDIUM |
| `modules/bmm/workflows/1-analysis/product-brief/instructions.md` | 1 | 🟢 LOW |
| `modules/bmm/workflows/1-analysis/game-brief/instructions.md` | 1 | 🟢 LOW |
| `modules/bmb/workflows/redoc/instructions.md` | 1 | 🟢 LOW |
### Breakdown by Module
**BMB (Builder) Module: 63 instances (64%)**
- edit-workflow: 21
- convert-legacy: 13
- create-module: 12
- create-agent: 11
- audit-workflow: 3
- create-workflow: 2
- redoc: 1
**BMM (Method) Module: 20 instances (20%)**
- dev-story: 13
- correct-course: 5
- product-brief: 1
- game-brief: 1
**Core Workflows: 12 instances (12%)**
- party-mode: 7
- brainstorming: 5
**CIS (Creative) Module: 3 instances (3%)**
- storytelling: 3
---
## Example Instances
### Example 1: create-agent/instructions.md (Line 13-20)
**BEFORE (Invalid):**
```xml
<check>If yes:</check>
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
<action>Wait for brainstorming session completion</action>
<check>If no:</check>
<action>Proceed directly to Step 0</action>
```
**AFTER (Correct):**
```xml
<check if="user answered yes">
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
<action>Wait for brainstorming session completion</action>
</check>
<check if="user answered no">
<action>Proceed directly to Step 0</action>
</check>
```
### Example 2: dev-story/instructions.md (Line 54-55)
**BEFORE (Invalid):**
```xml
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
<check>If task requirements ambiguous → ASK user to clarify or HALT</check>
```
**AFTER (Correct):**
```xml
<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
<action if="task requirements ambiguous">ASK user to clarify or HALT</action>
```
---
## Impact Assessment
### Technical Impact
1. **XML Validity:** Invalid structure violates XML parsing rules
2. **Formatter Confusion:** Custom formatters incorrectly indent following content
3. **Scope Ambiguity:** Unclear which actions are inside vs outside conditional
4. **Maintainability:** Future developers confused by ambiguous structure
### LLM Adherence Impact
**Potential Issues:**
- LLM may interpret check as unconditional statement
- Actions may execute when they shouldn't (or vice versa)
- Inconsistent behavior across different LLMs
- Unpredictable results in complex nested conditionals
**Observed Behavior:**
- LLMs often "figure it out" through context and proximity
- Colon (`:`) pattern signals "here's what to do"
- Works in simple cases but risky in complex logic
**Risk Level:** MEDIUM-HIGH
- May work "most of the time" but unreliable
- Fails in edge cases and complex nested logic
- Future LLMs may interpret differently
---
## Root Cause Analysis
### Why This Happened
1. **Implicit convention evolved** - Self-closing check pattern emerged organically
2. **No enforcement** - No linter or validator caught the pattern
3. **Copy-paste propagation** - Pattern copied across workflows
4. **Formatting hid the issue** - Manual indentation made it "look right"
5. **LLM tolerance** - Current LLMs often figured it out despite ambiguity
### Meta-Problem
**The workflows that CREATE workflows have the antipattern:**
- create-workflow: 2 instances
- create-agent: 11 instances
- create-module: 12 instances
- edit-workflow: 21 instances
- convert-legacy: 13 instances
This means NEW workflows were being created WITH the antipattern built-in!
---
## Remediation Plan
### Phase 1: Immediate (High Priority Files)
Fix top 5 offenders (63% of problem):
1. edit-workflow (21 instances)
2. dev-story (13 instances)
3. convert-legacy (13 instances)
4. create-module (12 instances)
5. create-agent (11 instances)
**Total:** 70 instances (71% of problem)
### Phase 2: Core Workflows
Fix core workflows (critical for all modules):
1. party-mode (7 instances)
2. brainstorming (5 instances)
**Total:** 12 instances
### Phase 3: Remaining
Fix remaining 16 instances across 7 files
### Phase 4: Prevention
1. **Update audit-workflow** ✅ DONE
- Added antipattern detection to Step 4
- Flags with CRITICAL severity
- Suggests correct patterns
2. **Update creation guide** ✅ DONE
- Documented antipattern in workflow-creation-guide.md
- Clear examples of correct vs incorrect patterns
- Added to best practices
3. **Update checklist** ✅ DONE
- Added validation criteria to checklist.md
- 3 new checks for conditional execution patterns
4. **Create automated fixer** (TODO)
- Bulk conversion script for remaining instances
- Pattern matching and replacement logic
---
## Specification Reference
From `bmad/core/tasks/workflow.xml`:
```xml
<tag>action if="condition" - Single conditional action (inline, no closing tag needed)</tag>
<tag>check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required)</tag>
```
**Key Point:** Check tags MUST have `if=""` attribute and MUST wrap content with closing tag.
The self-closing pattern `<check>text</check>` is **NOT in the spec** and is **invalid**.
---
## Detection Command
To find all instances:
```bash
grep -r "<check>[^<]*</check>" src --include="*.md" -n
```
To count by file:
```bash
grep -r "<check>[^<]*</check>" src --include="*.md" -c | grep -v ":0$"
```
---
## Next Actions
- [ ] Create bulk-fix script for automated conversion
- [ ] Fix Phase 1 files (70 instances)
- [ ] Fix Phase 2 files (12 instances)
- [ ] Fix Phase 3 files (16 instances)
- [ ] Run audit-workflow on all fixed files to verify
- [ ] Update formatter to detect and warn on antipattern
- [ ] Add pre-commit hook to prevent future instances
---
## References
- **Workflow Spec:** `bmad/core/tasks/workflow.xml`
- **Creation Guide:** `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md`
- **Audit Workflow:** `src/modules/bmb/workflows/audit-workflow/`
- **This Report:** `docs/antipattern-audit-2025-10-22.md`
---
**Report Status:** Complete
**Action Required:** Yes - 98 instances need remediation
**Priority:** CRITICAL - Affects core functionality and workflow creation

19
docs/codebase-flattener.md
View File

@@ -1,19 +0,0 @@
# Codebase Flattener Tool
BMad-Core includes a powerful codebase flattener for preparing existing projects to the web for AI Analysis
```bash
# Basic usage - creates flattened-codebase.xml
npx bmad-method flatten
# Custom input/output
npx bmad-method flatten --input /path/to/source --output project.xml
```
Features:
- AI-optimized XML output format
- Smart filtering with .gitignore respect
- Binary file detection and exclusion
- Real-time progress tracking
- Comprehensive completion statistics

188
docs/conversion-report-shard-doc-2025-10-26.md Normal file
View File

@@ -0,0 +1,188 @@
# Legacy Task Conversion Report
**Generated**: 2025-10-26
**Converted By**: BMad Builder Agent
**Conversion Type**: Legacy Task → v6 XML Task
---
## Source Information
- **Original Location**: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md
- **Original Format**: Markdown task (v4/legacy format)
- **Original Type**: Document sharding utility task
---
## Target Information
- **New Location**: `/Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml`
- **New Format**: v6 XML task format
- **Task ID**: `bmad/core/tasks/shard-doc`
- **Task Name**: Shard Document
---
## Conversion Summary
### Components Converted
✅ **Task Structure**: Converted from markdown to XML format
✅ **Execution Flow**: 6 steps properly structured in `<flow>` section (simplified to tool-only)
✅ **Critical Instructions**: Moved to `<llm critical="true">` section
✅ **Validation Rules**: Extracted to `<validation>` section
✅ **Halt Conditions**: Extracted to `<halt-conditions>` section
✅ **Special Guidelines**: Moved to `<critical-context>` section
✅ **Output Format**: Documented in `<output-format>` section
✅ **Tool Information**: Preserved in `<tool-info>` section
### Key Features Preserved
- **Automated Tool**: Uses @kayvan/markdown-tree-parser exclusively
- **Simplified Flow**: Removed all manual steps, tool handles everything
- **Code Block Awareness**: Tool automatically handles ## inside code blocks
- **Content Preservation**: Tool preserves all markdown formatting and special content
- **Heading Adjustment**: Tool automatically reduces heading levels by one
- **Index Generation**: Tool automatically creates index.md
- **Validation Steps**: Verification of tool installation and output
- **Error Handling**: Halt conditions for tool and file system issues
### v6 Conventions Applied
- ✅ Proper `<task>` wrapper with id and name attributes
- ✅ `<llm critical="true">` section with mandatory instructions
- ✅ `<flow>` section with numbered `<step>` elements
- ✅ Used `<action>` tags for required actions
- ✅ Used `<i>` tags for instruction lists and context
- ✅ Conditional logic with `if` attributes on actions
- ✅ Optional steps marked with `optional="true"`
- ✅ Supporting sections for validation, halt conditions, output format
- ✅ Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml)
---
## Structural Comparison
### Legacy Format (Markdown)
```
# Document Sharding Task
## Primary Method: Automated Approach
## Manual Method (Fallback)
1. Identify target location
2. Parse sections
...
## Critical Guidelines
```
### v6 Format (XML)
```xml
<task id="bmad/core/tasks/shard-doc" name="Shard Document">
<objective>...</objective>
<llm critical="true">...</llm>
<critical-context>...</critical-context>
<flow>
<step n="1" title="...">
<action>...</action>
</step>
</flow>
<halt-conditions>...</halt-conditions>
<validation>...</validation>
</task>
```
---
## Validation Results
### XML Structure
- ✅ Valid XML syntax
- ✅ Properly nested elements
- ✅ All tags closed correctly
- ✅ Attributes properly formatted
### v6 Compliance
- ✅ Matches v6 task conventions
- ✅ Follows existing core task patterns
- ✅ Uses standard v6 tag set
- ✅ Proper section organization
### Content Integrity
- ✅ All original instructions preserved
- ✅ No functionality lost in conversion
- ✅ Critical warnings maintained
- ✅ Tool information preserved
- ✅ Validation logic intact
### File System
- ✅ Saved to correct location: `src/core/tasks/`
- ✅ Proper filename: `shard-doc.xml`
- ✅ Follows core task naming convention
---
## Usage Notes
### How to Invoke This Task
From an agent or workflow, reference:
```xml
<invoke-task>{project-root}/bmad/core/tasks/shard-doc.xml</invoke-task>
```
Or from agent menu:
```yaml
menu:
- trigger: shard
description: 'Split large document into organized files'
exec: '{project-root}/bmad/core/tasks/shard-doc.xml'
```
### Task Capabilities
1. **Automated Mode**: Uses @kayvan/markdown-tree-parser for fast sharding
2. **Manual Mode**: Step-by-step guided process for controlled sharding
3. **Safety Checks**: Validates code blocks aren't treated as headers
4. **Content Preservation**: Maintains all formatting, code, tables, diagrams
5. **Index Generation**: Creates navigable index.md automatically
6. **Validation**: Verifies completeness and integrity
---
## Post-Conversion Actions
### Recommended Next Steps
1. ✅ **Task Created**: File saved to core tasks directory
2. **Test Task**: Invoke from an agent or workflow to verify functionality
3. **Update Documentation**: Reference in core task documentation if needed
4. **Integration**: Add to relevant agent menus if appropriate
### No Manual Adjustments Required
The conversion is complete and ready for use. All legacy functionality has been successfully migrated to v6 XML format.
---
## Notes
- Original legacy file can be archived or left as-is (located on GitHub)
- This task is now a core BMAD task available to all modules
- The task follows v6 conventions and is fully compatible with BMAD-CORE v6 alpha
- **UPDATED 2025-10-26**: Manual fallback steps removed - task now exclusively uses @kayvan/markdown-tree-parser
- Flow simplified from 8 steps to 6 steps (tool installation → execution → verification)
- All manual parsing, file creation, and index generation logic removed (tool handles automatically)
---
**Conversion Status**: ✅ COMPLETE (Updated)
**Ready for Use**: YES
**Manual Adjustments Needed**: NONE
**Approach**: Automated tool only (no manual fallback)

10
docs/installers-bundlers/ide-injections.md
View File

@@ -184,13 +184,3 @@ injections:
<cmds>...</cmds>
</agent>
```
## Testing Checklist
- [ ] Injection points are properly named and unique
- [ ] injections.yaml is valid YAML with correct structure
- [ ] Content formatting is preserved after injection
- [ ] Installation works without the IDE (injection points removed)
- [ ] Installation works with the IDE (content properly injected)
- [ ] Subagents/files are copied to correct locations
- [ ] No IDE-specific content remains when different IDE selected

64
docs/installers-bundlers/installers-modules-platforms-reference.md
View File

@@ -1,4 +1,4 @@
# BMAD v6 Installation & Module System Reference
# BMAD Installation & Module System Reference
## Table of Contents
@@ -13,63 +13,36 @@
## Overview
BMAD v6 is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
BMad Core is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
### Key Features
- **Modular Design**: Core + optional modules (BMM, CIS)
- **Modular Design**: Core + optional modules (BMB, BMM, CIS)
- **Smart Installation**: Interactive configuration with dependency resolution
- **Multi-Platform**: Supports 15+ AI coding platforms
- **Clean Architecture**: Centralized `bmad/` directory, no source pollution
## Quick Start
```bash
# Interactive installation (recommended)
bmad install
# Install specific modules
bmad install -m bmm cis
# Full installation
bmad install -f
# Check status
bmad status
```
### Installation Options
- `-d <path>`: Target directory (default: current)
- `-m <modules...>`: Specific modules (bmm, cis)
- `-f`: Full installation
- `-c`: Core only
- `-i <ide...>`: Configure specific IDEs
- `--skip-ide`: Skip IDE configuration
- `-v`: Verbose output
- **Clean Architecture**: Centralized `bmad/` directory add to project, no source pollution with multiple folders added
## Architecture
### Directory Structure
### Directory Structure upon installation
```
project-root/
├── bmad/ # Centralized installation
│ ├── _cfg/ # Configuration
│ │ ├── agents/ # Agent configs
│ │ └── agent-party.xml # Agent manifest
│ ├── core/ # Core module
├── bmad/ # Centralized installation
│ ├── _cfg/ # Configuration
│ │ ├── agents/ # Agent configs
│ │ └── agent-manifest.csv # Agent manifest
│ ├── core/ # Core module
│ │ ├── agents/
│ │ ├── tasks/
│ │ └── config.yaml
│ ├── bmm/ # BMad Method module
│ ├── bmm/ # BMad Method module
│ │ ├── agents/
│ │ ├── tasks/
│ │ ├── templates/
│ │ ├── workflows/
│ │ └── config.yaml
│ └── cis/ # Creative Innovation Studio
│ └── cis/ # Creative Innovation Studio
│ └── ...
└── .claude/ # Platform-specific (example)
└── .claude/ # Platform-specific (example)
└── agents/
```
@@ -78,11 +51,10 @@ project-root/
1. **Detection**: Check existing installation
2. **Selection**: Choose modules interactively or via CLI
3. **Configuration**: Collect module-specific settings
4. **Platform Setup**: Configure AI coding platforms
5. **Installation**: Process and copy files
6. **Generation**: Create config files with inheritance
7. **Post-Install**: Run module installers
8. **Manifest**: Track installed components
4. **Installation**: Compile Process and copy files
5. **Generation**: Create config files with inheritance
6. **Post-Install**: Run module installers
7. **Manifest**: Track installed components
### Key Exclusions

30
docs/technical-decisions-template.md
View File

@@ -1,30 +0,0 @@
# Technical Decisions Log
_Auto-updated during discovery and planning sessions - you can also add information here yourself_
## Purpose
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
## Confirmed Decisions
<!-- Technical choices explicitly confirmed by the team/user -->
## Preferences
<!-- Non-binding preferences mentioned during discussions -->
## Constraints
<!-- Hard requirements from infrastructure, compliance, or integration needs -->
## To Investigate
<!-- Technical questions that need research or architect input -->
## Notes
- This file is automatically updated when technical information is mentioned
- Decisions here are inputs, not final architecture
- Final technical decisions belong in architecture.md
- Implementation details belong in solutions/\*.md and story context or dev notes.