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

refactor(bmm,cis,core): Align diagram workflows with agile roles and distribute capabilities

Browse Source 
## The Tale of the Frame Expert

Once upon a time, BMad Method had a specialized agent called Frame Expert.
This agent was the master of all visual artifacts - flowcharts, diagrams,
wireframes, data flows. Whenever anyone needed a diagram, they called upon
Frame Expert. The agent lived in its own isolated domain with four dedicated
workflows and a library of shared templates.

## The Awakening

But something felt wrong. Teams using BMad Method were meant to mirror real
agile teams - Product Managers, Architects, UX Designers, Tech Writers,
Developers. Each agent represented an authentic role you'd find in any
software team.

Except Frame Expert.

No real agile team has a "Frame Expert" or "Diagram Specialist" who creates
all visual artifacts. In real teams, Architects diagram system architecture.
PMs flowchart processes. UX Designers wireframe interfaces. Tech Writers
create documentation diagrams. The visuals emerge from the domain experts
who need them, not from a centralized diagram factory.

Frame Expert was an abstraction that made technical sense but violated the
very soul of BMad Method - authentic agile role modeling.

## The Transformation

And so Frame Expert was dissolved, its knowledge distributed to those who
truly needed it:

**The Architect** inherited system architecture diagrams and data flows -
the blueprints of technical systems they design.

**The Product Manager** received process flowcharts - the visual maps of
features and workflows they orchestrate.

**The UX Designer** claimed wireframes - the interface sketches that bring
their vision to life.

**The Tech Writer** gained all diagram types - the visual aids that clarify
their documentation.

Each agent now creates diagrams in their domain, using their expertise,
serving their purpose.

## The Shared Knowledge

But the wisdom of diagram creation itself - the Excalidraw templates, the
component libraries, the validation patterns - this knowledge was too
valuable to scatter. It was elevated to core resources, where both BMM
agents AND the new CIS presentation-master agent could draw upon it.

Shared infrastructure for common needs. Distributed execution for domain
expertise.

## The Ripple Effects

With diagrams now properly distributed, other misalignments became visible:

Epic creation was happening in Phase 2 (Planning), before Architecture
existed. But epics need architectural context - API contracts, data models,
technical decisions. So epic creation migrated to Phase 3 (Solutioning),
after Architecture provides that foundation.

Workflow paths were updated. Documentation gained visual flowcharts showing
the complete journey. Agent naming standards were clarified - filenames are
stable roles, persona names are user dreams.

## What Changed

**Removed:**
- frame-expert.agent.yaml (the centralized specialist)
- All frame-expert workflows and shared resources
- Phase 2 epic creation workflow (wrong timing)
- game-design workflow path (consolidated to method track)
- v6-open-items.md (planning doc, now complete)

**Distributed Diagram Capabilities:**
- Architect: create-excalidraw-diagram, create-excalidraw-dataflow
- PM: create-excalidraw-flowchart
- Tech Writer: create-excalidraw-{diagram,dataflow,flowchart}, generate-mermaid
- UX Designer: create-excalidraw-wireframe

**Created:**
- src/core/resources/ (shared diagram context for all modules)
- src/modules/cis/agents/presentation-master.agent.yaml (visual comms specialist)
- src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/ (epic creation's new home)
- src/modules/bmm/workflows/diagrams/ (distributed diagram implementations)
- src/modules/bmm/docs/images/ (workflow visualization assets)

**Enhanced:**
- All agent definitions with domain-appropriate diagram workflows
- Documentation with embedded workflow diagrams and visual guides
- Agent compilation docs with critical naming convention rules
- All 4 workflow paths (enterprise/method × brownfield/greenfield)

**Fixed:**
- Epic creation now in Phase 3 after Architecture
- Story context path variables in BMGD module
- PRD workflow descriptions (epics moved to Phase 3)

## For Users

The Frame Expert commands are gone. In their place:

- Need architecture diagrams? Ask `/architect`
- Need process flows? Ask `/pm`
- Need wireframes? Ask `/ux-designer`
- Need documentation visuals? Ask `/tech-writer`

Each expert creates diagrams in their domain, with their context, using
their judgment.

This is how real teams work.
This commit is contained in:
Brian Madison
2025-11-18 21:54:48 -06:00
parent 224af173ef
commit f17e4ef0b7
48 changed files with 6455 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
src/core/resources/excalidraw/README.md Normal file
View File

@@ -0,0 +1,160 @@
# Core Excalidraw Resources
Universal knowledge for creating Excalidraw diagrams. All agents that create Excalidraw files should reference these resources.
## Purpose
Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (domain-specific application).
**Core = "How to create Excalidraw elements"**
- How to group shapes with text labels
- How to calculate text width
- How to create arrows with proper bindings
- How to validate JSON syntax
- Base structure and primitives
**Agents = "What diagrams to create"**
- Frame Expert (BMM): Technical flowcharts, architecture diagrams, wireframes
- Presentation Master (CIS): Pitch decks, creative visuals, Rube Goldberg machines
- Tech Writer (BMM): Documentation diagrams, concept explanations
## Files in This Directory
### excalidraw-helpers.md
**Universal element creation patterns**
- Text width calculation
- Element grouping rules (shapes + labels)
- Grid alignment
- Arrow creation (straight, elbow)
- Theme application
- Validation checklist
- Optimization rules
**Agents reference this to:**
- Create properly grouped shapes
- Calculate text dimensions
- Connect elements with arrows
- Ensure valid structure
### validate-json-instructions.md
**Universal JSON validation process**
- How to validate Excalidraw JSON
- Common errors and fixes
- Workflow integration
- Error recovery
**Agents reference this to:**
- Validate files after creation
- Fix syntax errors
- Ensure files can be opened in Excalidraw
### library-loader.md (Future)
**How to load external .excalidrawlib files**
- Programmatic library loading
- Community library integration
- Custom library management
**Status:** To be developed when implementing external library support.
## How Agents Use These Resources
### Example: Frame Expert (Technical Diagrams)
```yaml
# workflows/diagrams/create-flowchart/workflow.yaml
helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
```
**Domain-specific additions:**
```yaml
# workflows/diagrams/_shared/flowchart-templates.yaml
flowchart:
start_node:
type: ellipse
width: 120
height: 60
process_box:
type: rectangle
width: 160
height: 80
decision_diamond:
type: diamond
width: 140
height: 100
```
### Example: Presentation Master (Creative Visuals)
```yaml
# workflows/create-visual-metaphor/workflow.yaml
helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
```
**Domain-specific additions:**
```yaml
# workflows/_shared/creative-templates.yaml
rube_goldberg:
whimsical_connector:
type: arrow
strokeStyle: dashed
roughness: 2
playful_box:
type: rectangle
roundness: 12
```
## What Doesn't Belong in Core
**Domain-Specific Elements:**
- Flowchart-specific templates (belongs in Frame Expert)
- Pitch deck layouts (belongs in Presentation Master)
- Documentation-specific styles (belongs in Tech Writer)
**Agent Workflows:**
- How to create a flowchart (Frame Expert workflow)
- How to create a pitch deck (Presentation Master workflow)
- Step-by-step diagram creation (agent-specific)
**Theming:**
- Currently in agent workflows
- **Future:** Will be refactored to core as user-configurable themes
## Architecture Principle
**Single Source of Truth:**
- Core holds universal knowledge
- Agents reference core, don't duplicate
- Updates to core benefit all agents
- Agents specialize with domain knowledge
**DRY (Don't Repeat Yourself):**
- Element creation logic: ONCE in core
- Text width calculation: ONCE in core
- Validation process: ONCE in core
- Arrow binding patterns: ONCE in core
## Future Enhancements
1. **External Library Loader** - Load .excalidrawlib files from libraries.excalidraw.com
2. **Theme Management** - User-configurable color themes saved in core
3. **Component Library** - Shared reusable components across agents
4. **Layout Algorithms** - Auto-layout helpers for positioning elements

127
src/core/resources/excalidraw/excalidraw-helpers.md Normal file
View File

@@ -0,0 +1,127 @@
# Excalidraw Element Creation Guidelines
## Text Width Calculation
For text elements inside shapes (labels):
```
text_width = (text.length × fontSize × 0.6) + 20
```
Round to nearest 10 for grid alignment.
## Element Grouping Rules
**CRITICAL:** When creating shapes with labels:
1. Generate unique IDs:
- `shape-id` for the shape
- `text-id` for the text
- `group-id` for the group
2. Shape element must have:
- `groupIds: [group-id]`
- `boundElements: [{type: "text", id: text-id}]`
3. Text element must have:
- `containerId: shape-id`
- `groupIds: [group-id]` (SAME as shape)
- `textAlign: "center"`
- `verticalAlign: "middle"`
- `width: calculated_width`
## Grid Alignment
- Snap all `x`, `y` coordinates to 20px grid
- Formula: `Math.round(value / 20) * 20`
- Spacing between elements: 60px minimum
## Arrow Creation
### Straight Arrows
Use for forward flow (left-to-right, top-to-bottom):
```json
{
"type": "arrow",
"startBinding": {
"elementId": "source-shape-id",
"focus": 0,
"gap": 10
},
"endBinding": {
"elementId": "target-shape-id",
"focus": 0,
"gap": 10
},
"points": [[0, 0], [distance_x, distance_y]]
}
```
### Elbow Arrows
Use for upward flow, backward flow, or complex routing:
```json
{
"type": "arrow",
"startBinding": {...},
"endBinding": {...},
"points": [
[0, 0],
[intermediate_x, 0],
[intermediate_x, intermediate_y],
[final_x, final_y]
],
"elbowed": true
}
```
### Update Connected Shapes
After creating arrow, update `boundElements` on both connected shapes:
```json
{
"id": "shape-id",
"boundElements": [
{ "type": "text", "id": "text-id" },
{ "type": "arrow", "id": "arrow-id" }
]
}
```
## Theme Application
Theme colors should be applied consistently:
- **Shapes**: `backgroundColor` from theme primary fill
- **Borders**: `strokeColor` from theme accent
- **Text**: `strokeColor` = "#1e1e1e" (dark text)
- **Arrows**: `strokeColor` from theme accent
## Validation Checklist
Before saving, verify:
- [ ] All shapes with labels have matching `groupIds`
- [ ] All text elements have `containerId` pointing to parent shape
- [ ] Text width calculated properly (no cutoff)
- [ ] Text alignment set (`textAlign` + `verticalAlign`)
- [ ] All elements snapped to 20px grid
- [ ] All arrows have `startBinding` and `endBinding`
- [ ] `boundElements` array updated on connected shapes
- [ ] Theme colors applied consistently
- [ ] No metadata or history in final output
- [ ] All IDs are unique
## Optimization
Remove from final output:
- `appState` object
- `files` object (unless images used)
- All elements with `isDeleted: true`
- Unused library items
- Version history

50
src/core/resources/excalidraw/library-loader.md Normal file
View File

@@ -0,0 +1,50 @@
# External Library Loader
**Status:** Placeholder for future implementation
## Purpose
Load external .excalidrawlib files from https://libraries.excalidraw.com or custom sources.
## Planned Capabilities
- Load libraries by URL
- Load libraries from local files
- Merge multiple libraries
- Filter library components
- Cache loaded libraries
## API Reference
Will document how to use:
- `importLibrary(url)` - Load library from URL
- `loadSceneOrLibraryFromBlob()` - Load from file
- `mergeLibraryItems()` - Combine libraries
## Usage Example
```yaml
# Future workflow.yaml structure
libraries:
- url: 'https://libraries.excalidraw.com/libraries/...'
filter: ['aws', 'cloud']
- path: '{project-root}/_data/custom-library.excalidrawlib'
```
## Implementation Notes
This will be developed when agents need to leverage the extensive library ecosystem available at https://libraries.excalidraw.com.
Hundreds of pre-built component libraries exist for:
- AWS/Cloud icons
- UI/UX components
- Business diagrams
- Mind map shapes
- Floor plans
- And much more...
## User Configuration
Future: Users will be able to configure favorite libraries in their BMAD config for automatic loading.

79
src/core/resources/excalidraw/validate-json-instructions.md Normal file
View File

@@ -0,0 +1,79 @@
# JSON Validation Instructions
## Purpose
Validate Excalidraw JSON files after saving to catch syntax errors (missing commas, brackets, quotes).
## How to Validate
Use Node.js built-in JSON parsing to validate the file:
```bash
node -e "JSON.parse(require('fs').readFileSync('FILE_PATH', 'utf8')); console.log('✓ Valid JSON')"
```
Replace `FILE_PATH` with the actual file path.
## Exit Codes
- Exit code 0 = Valid JSON
- Exit code 1 = Invalid JSON (syntax error)
## Error Output
If invalid, Node.js will output:
- Error message with description
- Position in file where error occurred
- Line and column information (if available)
## Common Errors and Fixes
### Missing Comma
```
SyntaxError: Expected ',' or '}' after property value
```
**Fix:** Add comma after the property value
### Missing Bracket/Brace
```
SyntaxError: Unexpected end of JSON input
```
**Fix:** Add missing closing bracket `]` or brace `}`
### Extra Comma (Trailing)
```
SyntaxError: Unexpected token ,
```
**Fix:** Remove the trailing comma before `]` or `}`
### Missing Quote
```
SyntaxError: Unexpected token
```
**Fix:** Add missing quote around string value
## Workflow Integration
After saving an Excalidraw file, run validation:
1. Save the file
2. Run: `node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')"`
3. If validation fails:
- Read the error message for line/position
- Open the file at that location
- Fix the syntax error
- Save and re-validate
4. Repeat until validation passes
## Critical Rule
**NEVER delete the file due to validation errors - always fix the syntax error at the reported location.**