From 05ccd1904ce5748f44d5ebef117c651bf19fba2c Mon Sep 17 00:00:00 2001 From: mrsaifullah52 <60331864+mrsaifullah52@users.noreply.github.com> Date: Sat, 15 Nov 2025 20:39:46 +0500 Subject: [PATCH] Feature/frame expert agent #890 (#905) * feat: add frame-expert agent definition - Add frame-expert.agent.yaml with persona and workflow menu - Agent specializes in Excalidraw visual representations - Supports flowcharts, diagrams, dataflows, and wireframes Closes #890 * feat: add frame-expert workflows and shared resources - Add 4 workflows: create-flowchart, create-diagram, create-dataflow, create-wireframe - Include shared Excalidraw helpers, library, templates, and validation - Each workflow has instructions, checklist, and workflow.yaml Related to #890 * feat: register frame-expert workflows in manifest - Add create-flowchart workflow entry - Add create-diagram workflow entry - Add create-dataflow workflow entry - Add create-wireframe workflow entry Related to #890 * feat: integrate frame-expert into team configurations - Add frame-expert to default-party.csv with full agent details - Add frame-expert to team-fullstack.yaml agent list - Frame-expert now available in fullstack team workflows Related to #890 --- .../bmm/agents/frame-expert.agent.yaml | 32 +++ src/modules/bmm/teams/default-party.csv | 1 + src/modules/bmm/teams/team-fullstack.yaml | 1 + .../_shared/excalidraw-helpers.md | 127 +++++++++ .../_shared/excalidraw-library.json | 90 +++++++ .../_shared/excalidraw-templates.yaml | 127 +++++++++ .../_shared/validate-json-instructions.md | 79 ++++++ .../frame-expert/create-dataflow/checklist.md | 39 +++ .../create-dataflow/instructions.md | 131 ++++++++++ .../create-dataflow/workflow.yaml | 24 ++ .../frame-expert/create-diagram/checklist.md | 43 ++++ .../create-diagram/instructions.md | 142 ++++++++++ .../frame-expert/create-diagram/workflow.yaml | 25 ++ .../create-flowchart/checklist.md | 49 ++++ .../create-flowchart/instructions.md | 242 ++++++++++++++++++ .../create-flowchart/workflow.yaml | 28 ++ .../create-wireframe/checklist.md | 38 +++ .../create-wireframe/instructions.md | 133 ++++++++++ .../create-wireframe/workflow.yaml | 24 ++ 19 files changed, 1375 insertions(+) create mode 100644 src/modules/bmm/agents/frame-expert.agent.yaml create mode 100644 src/modules/bmm/workflows/frame-expert/_shared/excalidraw-helpers.md create mode 100644 src/modules/bmm/workflows/frame-expert/_shared/excalidraw-library.json create mode 100644 src/modules/bmm/workflows/frame-expert/_shared/excalidraw-templates.yaml create mode 100644 src/modules/bmm/workflows/frame-expert/_shared/validate-json-instructions.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-dataflow/checklist.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-dataflow/instructions.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-dataflow/workflow.yaml create mode 100644 src/modules/bmm/workflows/frame-expert/create-diagram/checklist.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-diagram/instructions.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-diagram/workflow.yaml create mode 100644 src/modules/bmm/workflows/frame-expert/create-flowchart/checklist.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-flowchart/instructions.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-flowchart/workflow.yaml create mode 100644 src/modules/bmm/workflows/frame-expert/create-wireframe/checklist.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-wireframe/instructions.md create mode 100644 src/modules/bmm/workflows/frame-expert/create-wireframe/workflow.yaml diff --git a/src/modules/bmm/agents/frame-expert.agent.yaml b/src/modules/bmm/agents/frame-expert.agent.yaml new file mode 100644 index 00000000..1af4e61a --- /dev/null +++ b/src/modules/bmm/agents/frame-expert.agent.yaml @@ -0,0 +1,32 @@ +# Frame Expert Agent Definition + +agent: + metadata: + id: "{bmad_folder}/bmm/agents/frame-expert.md" + name: Saif Ullah + title: Visual Design & Diagramming Expert + icon: 🎨 + module: bmm + + persona: + role: Expert Visual Designer & Diagramming Specialist + identity: Expert who creates visual representations using Excalidraw with optimized, reusable components. Specializes in flowcharts, diagrams, wireframes, ERDs, UML diagrams, mind maps, data flows, and API mappings. + communication_style: Visual-first, structured, detail-oriented, composition-focused. Presents options as numbered lists for easy selection. + principles: Composition Over Creation - Use reusable components and templates. Minimal Payload - Strip unnecessary metadata, optimize serialization. Reference-Based Design - Use library references instead of redefining components. Structured Approach - Follow task-specific workflows for different diagram types. Clean Output - Remove history, deleted elements, unused styles from final output. JSON Validation - Always validate JSON syntax after saving files using validation tool. Error Recovery - NEVER delete files due to syntax errors, always fix them using error location information. + + menu: + - trigger: flowchart + workflow: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-flowchart/workflow.yaml" + description: Create flowchart for processes, pipelines, or logic flows + + - trigger: diagram + workflow: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-diagram/workflow.yaml" + description: Create system architecture or general technical diagram + + - trigger: dataflow + workflow: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-dataflow/workflow.yaml" + description: Create data flow diagram + + - trigger: wireframe + workflow: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-wireframe/workflow.yaml" + description: Create website or app wireframe diff --git a/src/modules/bmm/teams/default-party.csv b/src/modules/bmm/teams/default-party.csv index a670317b..9adc7dc2 100644 --- a/src/modules/bmm/teams/default-party.csv +++ b/src/modules/bmm/teams/default-party.csv @@ -17,3 +17,4 @@ name,displayName,title,icon,role,identity,communicationStyle,principles,module,p "lateral-thinker","Edward de Bono","Lateral Thinking Pioneer","🧩","Creator of Creative Thinking Tools","Inventor of lateral thinking and Six Thinking Hats methodology. Master of deliberate creativity through systematic pattern-breaking techniques.","Talks in structured thinking frameworks - uses colored hat metaphors, proposes deliberate provocations, breaks patterns methodically","Logic gets you from A to B. Creativity gets you everywhere else. Use tools to escape habitual thinking patterns.","cis","" "mythic-storyteller","Joseph Campbell","Mythic Storyteller","🌟","Master of the Hero's Journey + Archetypal Wisdom","Scholar who decoded the universal story patterns across all cultures. Expert in mythology, comparative religion, and archetypal narratives.","Speaks in mythological metaphors and archetypal patterns - EVERY story is a hero's journey, references ancient wisdom","Follow your bliss. All stories share the monomyth. Myths reveal universal human truths. The call to adventure is irresistible.","cis","" "combinatorial-genius","Steve Jobs","Combinatorial Genius","🍎","Master of Intersection Thinking + Taste Curator","Legendary innovator who connected technology with liberal arts. Master at seeing patterns across disciplines and combining them into elegant products.","Talks in reality distortion field mode - insanely great, magical, revolutionary, makes impossible seem inevitable","Innovation happens at intersections. Taste is about saying NO to 1000 things. Stay hungry stay foolish. Simplicity is sophistication.","cis","" +"frame-expert","Saif Ullah","Visual Design & Diagramming Expert","🎨","Expert Visual Designer & Diagramming Specialist","Expert who creates visual representations using Excalidraw with optimized, reusable components. Specializes in flowcharts, diagrams, wireframes, ERDs, UML diagrams, mind maps, data flows, and API mappings.","Visual-first, structured, detail-oriented, composition-focused. Presents options as numbered lists for easy selection.","Composition Over Creation - Use reusable components and templates. Minimal Payload - Strip unnecessary metadata. Reference-Based Design - Use library references. Structured Approach - Follow task-specific workflows. Clean Output - Remove history and unused styles.","bmm","bmad/bmm/agents/frame-expert.md" diff --git a/src/modules/bmm/teams/team-fullstack.yaml b/src/modules/bmm/teams/team-fullstack.yaml index 94e1ea95..b705669a 100644 --- a/src/modules/bmm/teams/team-fullstack.yaml +++ b/src/modules/bmm/teams/team-fullstack.yaml @@ -9,4 +9,5 @@ agents: - pm - sm - ux-designer + - frame-expert party: "./default-party.csv" diff --git a/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-helpers.md b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-helpers.md new file mode 100644 index 00000000..36264680 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-helpers.md @@ -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 diff --git a/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-library.json b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-library.json new file mode 100644 index 00000000..d18f94af --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-library.json @@ -0,0 +1,90 @@ +{ + "type": "excalidrawlib", + "version": 2, + "library": [ + { + "id": "start-end-circle", + "status": "published", + "elements": [ + { + "type": "ellipse", + "width": 120, + "height": 60, + "strokeColor": "#1976d2", + "backgroundColor": "#e3f2fd", + "fillStyle": "solid", + "strokeWidth": 2, + "roughness": 0 + } + ] + }, + { + "id": "process-rectangle", + "status": "published", + "elements": [ + { + "type": "rectangle", + "width": 160, + "height": 80, + "strokeColor": "#1976d2", + "backgroundColor": "#e3f2fd", + "fillStyle": "solid", + "strokeWidth": 2, + "roughness": 0, + "roundness": { + "type": 3, + "value": 8 + } + } + ] + }, + { + "id": "decision-diamond", + "status": "published", + "elements": [ + { + "type": "diamond", + "width": 140, + "height": 100, + "strokeColor": "#f57c00", + "backgroundColor": "#fff3e0", + "fillStyle": "solid", + "strokeWidth": 2, + "roughness": 0 + } + ] + }, + { + "id": "data-store", + "status": "published", + "elements": [ + { + "type": "rectangle", + "width": 140, + "height": 80, + "strokeColor": "#388e3c", + "backgroundColor": "#e8f5e9", + "fillStyle": "solid", + "strokeWidth": 2, + "roughness": 0 + } + ] + }, + { + "id": "external-entity", + "status": "published", + "elements": [ + { + "type": "rectangle", + "width": 120, + "height": 80, + "strokeColor": "#7b1fa2", + "backgroundColor": "#f3e5f5", + "fillStyle": "solid", + "strokeWidth": 3, + "roughness": 0 + } + ] + } + ] +} diff --git a/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-templates.yaml b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-templates.yaml new file mode 100644 index 00000000..6fab2a3d --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/_shared/excalidraw-templates.yaml @@ -0,0 +1,127 @@ +flowchart: + viewport: + x: 0 + y: 0 + zoom: 1 + grid: + size: 20 + spacing: + vertical: 100 + horizontal: 180 + elements: + start: + type: ellipse + width: 120 + height: 60 + label: "Start" + process: + type: rectangle + width: 160 + height: 80 + roundness: 8 + decision: + type: diamond + width: 140 + height: 100 + end: + type: ellipse + width: 120 + height: 60 + label: "End" + +diagram: + viewport: + x: 0 + y: 0 + zoom: 1 + grid: + size: 20 + spacing: + vertical: 120 + horizontal: 200 + elements: + component: + type: rectangle + width: 180 + height: 100 + roundness: 8 + database: + type: rectangle + width: 140 + height: 80 + service: + type: rectangle + width: 160 + height: 90 + roundness: 12 + external: + type: rectangle + width: 140 + height: 80 + +wireframe: + viewport: + x: 0 + y: 0 + zoom: 0.8 + grid: + size: 20 + spacing: + vertical: 40 + horizontal: 40 + elements: + container: + type: rectangle + width: 800 + height: 600 + strokeStyle: solid + strokeWidth: 2 + header: + type: rectangle + width: 800 + height: 80 + button: + type: rectangle + width: 120 + height: 40 + roundness: 4 + input: + type: rectangle + width: 300 + height: 40 + roundness: 4 + text: + type: text + fontSize: 16 + +dataflow: + viewport: + x: 0 + y: 0 + zoom: 1 + grid: + size: 20 + spacing: + vertical: 120 + horizontal: 200 + elements: + process: + type: ellipse + width: 140 + height: 80 + label: "Process" + datastore: + type: rectangle + width: 140 + height: 80 + label: "Data Store" + external: + type: rectangle + width: 120 + height: 80 + strokeWidth: 3 + label: "External Entity" + dataflow: + type: arrow + strokeWidth: 2 + label: "Data Flow" diff --git a/src/modules/bmm/workflows/frame-expert/_shared/validate-json-instructions.md b/src/modules/bmm/workflows/frame-expert/_shared/validate-json-instructions.md new file mode 100644 index 00000000..3abf3fc3 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/_shared/validate-json-instructions.md @@ -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.** diff --git a/src/modules/bmm/workflows/frame-expert/create-dataflow/checklist.md b/src/modules/bmm/workflows/frame-expert/create-dataflow/checklist.md new file mode 100644 index 00000000..3c9463d5 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-dataflow/checklist.md @@ -0,0 +1,39 @@ +# Create Data Flow Diagram - Validation Checklist + +## DFD Notation + +- [ ] Processes shown as circles/ellipses +- [ ] Data stores shown as parallel lines or rectangles +- [ ] External entities shown as rectangles +- [ ] Data flows shown as labeled arrows +- [ ] Follows standard DFD notation + +## Structure + +- [ ] All processes numbered correctly +- [ ] All data flows labeled with data names +- [ ] All data stores named appropriately +- [ ] External entities clearly identified + +## Completeness + +- [ ] All inputs and outputs accounted for +- [ ] No orphaned processes (unconnected) +- [ ] Data conservation maintained +- [ ] Level appropriate (context/level 0/level 1) + +## Layout + +- [ ] Logical flow direction (left to right, top to bottom) +- [ ] No crossing data flows where avoidable +- [ ] Balanced layout +- [ ] Grid alignment maintained + +## Technical Quality + +- [ ] All elements properly grouped +- [ ] Arrows have proper bindings +- [ ] Text readable and properly sized +- [ ] No elements with `isDeleted: true` +- [ ] JSON is valid +- [ ] File saved to correct location diff --git a/src/modules/bmm/workflows/frame-expert/create-dataflow/instructions.md b/src/modules/bmm/workflows/frame-expert/create-dataflow/instructions.md new file mode 100644 index 00000000..98e044ac --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-dataflow/instructions.md @@ -0,0 +1,131 @@ +# Create Data Flow Diagram - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow creates data flow diagrams (DFD) in Excalidraw format. + + + + + Review user's request and extract: DFD level, processes, data stores, external entities, save location + Skip to Step 4 + + + + Ask: "What level of DFD do you need?" + Present options: + 1. Context Diagram (Level 0) - Single process showing system boundaries + 2. Level 1 DFD - Major processes and data flows + 3. Level 2 DFD - Detailed sub-processes + 4. Custom - Specify your requirements + + WAIT for selection, store in {{dfd_level}} + + + + Ask process count + Ask data store count + Ask external entity count + Ask save location + + + + Check for existing theme.json, ask to use if exists + + Ask: "Choose a DFD color scheme:" + Present numbered options: + 1. Standard DFD + - Process: #e3f2fd (light blue) + - Data Store: #e8f5e9 (light green) + - External Entity: #f3e5f5 (light purple) + - Border: #1976d2 (blue) + + 2. Colorful DFD + - Process: #fff9c4 (light yellow) + - Data Store: #c5e1a5 (light lime) + - External Entity: #ffccbc (light coral) + - Border: #f57c00 (orange) + + 3. Minimal DFD + - Process: #f5f5f5 (light gray) + - Data Store: #eeeeee (gray) + - External Entity: #e0e0e0 (medium gray) + - Border: #616161 (dark gray) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + + + + + List all processes with numbers (1.0, 2.0, etc.) + List all data stores (D1, D2, etc.) + List all external entities + Map all data flows with labels + Show planned structure, confirm with user + + + + Load {{templates}} and extract `dataflow` section + Load {{library}} + Load theme.json + Load {{helpers}} + + + + Follow standard DFD notation from {{helpers}} + + Build Order: + 1. External entities (rectangles, bold border) + 2. Processes (circles/ellipses with numbers) + 3. Data stores (parallel lines or rectangles) + 4. Data flows (labeled arrows) + + + DFD Rules: + - Processes: Numbered (1.0, 2.0), verb phrases + - Data stores: Named (D1, D2), noun phrases + - External entities: Named, noun phrases + - Data flows: Labeled with data names, arrows show direction + - No direct flow between external entities + - No direct flow between data stores + + + Layout: + - External entities at edges + - Processes in center + - Data stores between processes + - Minimize crossing flows + - Left-to-right or top-to-bottom flow + + + + + Verify DFD rules compliance + Strip unused elements and elements with isDeleted: true + Save to {{save_location}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user + + + + Validate against {{validation}} + + + +``` diff --git a/src/modules/bmm/workflows/frame-expert/create-dataflow/workflow.yaml b/src/modules/bmm/workflows/frame-expert/create-dataflow/workflow.yaml new file mode 100644 index 00000000..929e2df7 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-dataflow/workflow.yaml @@ -0,0 +1,24 @@ +name: create-dataflow +description: "Create data flow diagrams (DFD) in Excalidraw format" +author: "BMad" + +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-dataflow" +shared_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/_shared" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +helpers: "{shared_path}/excalidraw-helpers.md" +templates: "{shared_path}/excalidraw-templates.yaml" +library: "{shared_path}/excalidraw-library.json" + +variables: + dfd_level: "" + process_count: "" + datastore_count: "" + external_entities: "" + save_location: "" + +default_output_file: "{project-root}/docs/dataflow/dfd-{timestamp}.excalidraw" + +standalone: true +web_bundle: false diff --git a/src/modules/bmm/workflows/frame-expert/create-diagram/checklist.md b/src/modules/bmm/workflows/frame-expert/create-diagram/checklist.md new file mode 100644 index 00000000..61d216ae --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-diagram/checklist.md @@ -0,0 +1,43 @@ +# Create Diagram - Validation Checklist + +## Element Structure + +- [ ] All components with labels have matching `groupIds` +- [ ] All text elements have `containerId` pointing to parent component +- [ ] Text width calculated properly (no cutoff) +- [ ] Text alignment appropriate for diagram type + +## Layout and Alignment + +- [ ] All elements snapped to 20px grid +- [ ] Component spacing consistent (40px/60px) +- [ ] Hierarchical alignment maintained +- [ ] No overlapping elements + +## Connections + +- [ ] All arrows have `startBinding` and `endBinding` +- [ ] `boundElements` array updated on connected components +- [ ] Arrow routing avoids overlaps +- [ ] Relationship types clearly indicated + +## Notation and Standards + +- [ ] Follows specified notation standard (UML/ERD/etc) +- [ ] Symbols used correctly +- [ ] Cardinality/multiplicity shown where needed +- [ ] Labels and annotations clear + +## Theme and Styling + +- [ ] Theme colors applied consistently +- [ ] Component types visually distinguishable +- [ ] Text is readable +- [ ] Professional appearance + +## Output Quality + +- [ ] Element count under 80 +- [ ] No elements with `isDeleted: true` +- [ ] JSON is valid +- [ ] File saved to correct location diff --git a/src/modules/bmm/workflows/frame-expert/create-diagram/instructions.md b/src/modules/bmm/workflows/frame-expert/create-diagram/instructions.md new file mode 100644 index 00000000..754831e4 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-diagram/instructions.md @@ -0,0 +1,142 @@ +# Create Diagram - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow creates system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format. + + + + + Review user's request and extract: diagram type, components/entities, relationships, notation preferences, save location + Skip to Step 5 + Only ask about missing info in Steps 1-2 + + + + Ask: "What type of technical diagram do you need?" + Present options: + 1. System Architecture + 2. Entity-Relationship Diagram (ERD) + 3. UML Class Diagram + 4. UML Sequence Diagram + 5. UML Use Case Diagram + 6. Network Diagram + 7. Other + + WAIT for selection, store in {{diagram_type}} + + + + Ask component count (Small/Medium/Large/Very Large) + Ask relationship types (Simple/Hierarchical/Many-to-many/Mixed) + Ask notation standard (Standard/Simplified/Strict UML-ERD/Company specific) + Ask save location (Default/Custom/Architecture folder/Specific folder) + Store all responses in variables + + + + Check if theme.json exists at output location + Ask to use it, load if yes, else proceed to Step 4 + Proceed to Step 4 + + + + Ask: "Choose a color scheme for your diagram:" + Present numbered options: + 1. Professional + - Component: #e3f2fd (light blue) + - Database: #e8f5e9 (light green) + - Service: #fff3e0 (light orange) + - Border: #1976d2 (blue) + + 2. Colorful + - Component: #e1bee7 (light purple) + - Database: #c5e1a5 (light lime) + - Service: #ffccbc (light coral) + - Border: #7b1fa2 (purple) + + 3. Minimal + - Component: #f5f5f5 (light gray) + - Database: #eeeeee (gray) + - Service: #e0e0e0 (medium gray) + - Border: #616161 (dark gray) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + Show preview and confirm + + + + List all components/entities + Map all relationships + Show planned layout + Ask: "Structure looks correct? (yes/no)" + Adjust and repeat + + + + Load {{templates}} and extract `diagram` section + Load {{library}} + Load theme.json and merge with template + Load {{helpers}} for guidelines + + + + Follow {{helpers}} for proper element creation + + For Each Component: + - Generate unique IDs (component-id, text-id, group-id) + - Create shape with groupIds + - Calculate text width + - Create text with containerId and matching groupIds + - Add boundElements + + + For Each Connection: + - Determine arrow type (straight/elbow) + - Create with startBinding and endBinding + - Update boundElements on both components + + + Build Order by Type: + - Architecture: Services → Databases → Connections → Labels + - ERD: Entities → Attributes → Relationships → Cardinality + - UML Class: Classes → Attributes → Methods → Relationships + - UML Sequence: Actors → Lifelines → Messages → Returns + - UML Use Case: Actors → Use Cases → Relationships + + + Alignment: + - Snap to 20px grid + - Space: 40px between components, 60px between sections + + + + + Strip unused elements and elements with isDeleted: true + Save to {{save_location}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm: "Diagram created at {{save_location}}. Open to view?" + + + + Validate against {{validation}} using {{bmad_folder}}/core/tasks/validate-workflow.xml + + + +``` diff --git a/src/modules/bmm/workflows/frame-expert/create-diagram/workflow.yaml b/src/modules/bmm/workflows/frame-expert/create-diagram/workflow.yaml new file mode 100644 index 00000000..31b1c49f --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-diagram/workflow.yaml @@ -0,0 +1,25 @@ +name: create-diagram +description: "Create system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format" +author: "BMad" + +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-diagram" +shared_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/_shared" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +helpers: "{shared_path}/excalidraw-helpers.md" +templates: "{shared_path}/excalidraw-templates.yaml" +library: "{shared_path}/excalidraw-library.json" + +variables: + diagram_type: "" + component_count: "" + relationship_type: "" + notation_standard: "" + save_location: "" + theme_choice: "" + +default_output_file: "{project-root}/docs/diagrams/diagram-{timestamp}.excalidraw" + +standalone: true +web_bundle: false diff --git a/src/modules/bmm/workflows/frame-expert/create-flowchart/checklist.md b/src/modules/bmm/workflows/frame-expert/create-flowchart/checklist.md new file mode 100644 index 00000000..7da7fb78 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-flowchart/checklist.md @@ -0,0 +1,49 @@ +# Create Flowchart - Validation Checklist + +## Element Structure + +- [ ] 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`) + +## Layout and Alignment + +- [ ] All elements snapped to 20px grid +- [ ] Consistent spacing between elements (60px minimum) +- [ ] Vertical alignment maintained for flow direction +- [ ] No overlapping elements + +## Connections + +- [ ] All arrows have `startBinding` and `endBinding` +- [ ] `boundElements` array updated on connected shapes +- [ ] Arrow types appropriate (straight for forward, elbow for backward/upward) +- [ ] Gap set to 10 for all bindings + +## Theme and Styling + +- [ ] Theme colors applied consistently +- [ ] All shapes use theme primary fill color +- [ ] All borders use theme accent color +- [ ] Text color is readable (#1e1e1e) + +## Composition + +- [ ] Element count under 50 +- [ ] Library components referenced where possible +- [ ] No duplicate element definitions + +## Output Quality + +- [ ] No elements with `isDeleted: true` +- [ ] JSON is valid +- [ ] File saved to correct location + +## Functional Requirements + +- [ ] Start point clearly marked +- [ ] End point clearly marked +- [ ] All process steps labeled +- [ ] Decision points use diamond shapes +- [ ] Flow direction is clear and logical diff --git a/src/modules/bmm/workflows/frame-expert/create-flowchart/instructions.md b/src/modules/bmm/workflows/frame-expert/create-flowchart/instructions.md new file mode 100644 index 00000000..440bced3 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-flowchart/instructions.md @@ -0,0 +1,242 @@ +# Create Flowchart - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow creates a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows. + + + + + Before asking any questions, analyze what the user has already told you + + Review the user's initial request and conversation history + Extract any mentioned: flowchart type, complexity, decision points, save location + + + Summarize your understanding + Skip directly to Step 4 (Plan Flowchart Layout) + + + + Note what you already know + Only ask about missing information in Step 1 + + + + Proceed with full elicitation in Step 1 + + + + + Ask Question 1: "What type of process flow do you need to visualize?" + Present numbered options: + 1. Business Process Flow - Document business workflows, approval processes, or operational procedures + 2. Algorithm/Logic Flow - Visualize code logic, decision trees, or computational processes + 3. User Journey Flow - Map user interactions, navigation paths, or experience flows + 4. Data Processing Pipeline - Show data transformation, ETL processes, or processing stages + 5. Other - Describe your specific flowchart needs + + WAIT for user selection (1-5) + Store selection in {{flowchart_type}} + + Ask Question 2: "How many main steps are in this flow?" + Present numbered options: + 1. Simple (3-5 steps) - Quick process with few decision points + 2. Medium (6-10 steps) - Standard workflow with some branching + 3. Complex (11-20 steps) - Detailed process with multiple decision points + 4. Very Complex (20+ steps) - Comprehensive workflow requiring careful layout + + WAIT for user selection (1-4) + Store selection in {{complexity}} + + Ask Question 3: "Does your flow include decision points (yes/no branches)?" + Present numbered options: + 1. No decisions - Linear flow from start to end + 2. Few decisions (1-2) - Simple branching with yes/no paths + 3. Multiple decisions (3-5) - Several conditional branches + 4. Complex decisions (6+) - Extensive branching logic + + WAIT for user selection (1-4) + Store selection in {{decision_points}} + + Ask Question 4: "Where should the flowchart be saved?" + Present numbered options: + 1. Default location - docs/flowcharts/[auto-generated-name].excalidraw + 2. Custom path - Specify your own file path + 3. Project root - Save in main project directory + 4. Specific folder - Choose from existing folders + + WAIT for user selection (1-4) + + Ask for specific path + WAIT for user input + + Store final path in {{save_location}} + + + + Check if theme.json exists at output location + + Ask: "Found existing theme. Use it? (yes/no)" + WAIT for user response + + Load and use existing theme + Skip to Step 4 + + + Proceed to Step 3 + + + + Proceed to Step 3 + + + + + Ask: "Let's create a theme for your flowchart. Choose a color scheme:" + Present numbered options: + 1. Professional Blue + - Primary Fill: #e3f2fd (light blue) + - Accent/Border: #1976d2 (blue) + - Decision: #fff3e0 (light orange) + - Text: #1e1e1e (dark gray) + + 2. Success Green + - Primary Fill: #e8f5e9 (light green) + - Accent/Border: #388e3c (green) + - Decision: #fff9c4 (light yellow) + - Text: #1e1e1e (dark gray) + + 3. Neutral Gray + - Primary Fill: #f5f5f5 (light gray) + - Accent/Border: #616161 (gray) + - Decision: #e0e0e0 (medium gray) + - Text: #1e1e1e (dark gray) + + 4. Warm Orange + - Primary Fill: #fff3e0 (light orange) + - Accent/Border: #f57c00 (orange) + - Decision: #ffe0b2 (peach) + - Text: #1e1e1e (dark gray) + + 5. Custom Colors - Define your own color palette + + WAIT for user selection (1-5) + Store selection in {{theme_choice}} + + + Ask: "Primary fill color (hex code)?" + WAIT for user input + Store in {{custom_colors.primary_fill}} + Ask: "Accent/border color (hex code)?" + WAIT for user input + Store in {{custom_colors.accent}} + Ask: "Decision color (hex code)?" + WAIT for user input + Store in {{custom_colors.decision}} + + + Create theme.json with selected colors + Show theme preview with all colors + Ask: "Theme looks good?" + Present numbered options: + 1. Yes, use this theme - Proceed with theme + 2. No, adjust colors - Modify color selections + 3. Start over - Choose different preset + + WAIT for selection (1-3) + + Repeat Step 3 + + + + + List all steps and decision points based on gathered requirements + Show user the planned structure + Ask: "Structure looks correct? (yes/no)" + WAIT for user response + + Adjust structure based on feedback + Repeat this step + + + + + Load {{templates}} file + Extract `flowchart` section from YAML + Load {{library}} file + Load theme.json and merge colors with template + Load {{helpers}} for element creation guidelines + + + + Follow guidelines from {{helpers}} for proper element creation + + Build ONE section at a time following these rules: + + For Each Shape with Label: + 1. Generate unique IDs (shape-id, text-id, group-id) + 2. Create shape with groupIds: [group-id] + 3. Calculate text width: (text.length × fontSize × 0.6) + 20, round to nearest 10 + 4. Create text element with: + - containerId: shape-id + - groupIds: [group-id] (SAME as shape) + - textAlign: "center" + - verticalAlign: "middle" + - width: calculated width + 5. Add boundElements to shape referencing text + + + For Each Arrow: + 1. Determine arrow type needed: + - Straight: For forward flow (left-to-right, top-to-bottom) + - Elbow: For upward flow, backward flow, or complex routing + 2. Create arrow with startBinding and endBinding + 3. Set startBinding.elementId to source shape ID + 4. Set endBinding.elementId to target shape ID + 5. Set gap: 10 for both bindings + 6. If elbow arrow, add intermediate points for direction changes + 7. Update boundElements on both connected shapes + + + Alignment: + - Snap all x, y to 20px grid + - Align shapes vertically (same x for vertical flow) + - Space elements: 60px between shapes + + + Build Order: + 1. Start point (circle) with label + 2. Each process step (rectangle) with label + 3. Each decision point (diamond) with label + 4. End point (circle) with label + 5. Connect all with bound arrows + + + + + Strip unused elements and elements with isDeleted: true + Save to {{save_location}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user: "Flowchart created at {{save_location}}. Open to view?" + + + + Validate against checklist at {{validation}} using {{bmad_folder}}/core/tasks/validate-workflow.xml + + + +``` diff --git a/src/modules/bmm/workflows/frame-expert/create-flowchart/workflow.yaml b/src/modules/bmm/workflows/frame-expert/create-flowchart/workflow.yaml new file mode 100644 index 00000000..cbee129a --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-flowchart/workflow.yaml @@ -0,0 +1,28 @@ +name: create-flowchart +description: "Create a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows" +author: "BMad" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-flowchart" +shared_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/_shared" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Shared resources +helpers: "{shared_path}/excalidraw-helpers.md" +templates: "{shared_path}/excalidraw-templates.yaml" +library: "{shared_path}/excalidraw-library.json" + +# Variables +variables: + flowchart_type: "" # Will be elicited + complexity: "" # Will be elicited + decision_points: "" # Will be elicited + save_location: "" # Will be elicited + theme_choice: "" # Will be elicited + custom_colors: {} # For custom theme + +default_output_file: "{project-root}/docs/flowcharts/flowchart-{timestamp}.excalidraw" + +standalone: true +web_bundle: false diff --git a/src/modules/bmm/workflows/frame-expert/create-wireframe/checklist.md b/src/modules/bmm/workflows/frame-expert/create-wireframe/checklist.md new file mode 100644 index 00000000..3e2b26f4 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-wireframe/checklist.md @@ -0,0 +1,38 @@ +# Create Wireframe - Validation Checklist + +## Layout Structure + +- [ ] Screen dimensions appropriate for device type +- [ ] Grid alignment (20px) maintained +- [ ] Consistent spacing between UI elements +- [ ] Proper hierarchy (header, content, footer) + +## UI Elements + +- [ ] All interactive elements clearly marked +- [ ] Buttons, inputs, and controls properly sized +- [ ] Text labels readable and appropriately sized +- [ ] Navigation elements clearly indicated + +## Fidelity + +- [ ] Matches requested fidelity level (low/medium/high) +- [ ] Appropriate level of detail +- [ ] Placeholder content used where needed +- [ ] No unnecessary decoration for low-fidelity + +## Annotations + +- [ ] Key interactions annotated +- [ ] Flow indicators present if multi-screen +- [ ] Important notes included +- [ ] Element purposes clear + +## Technical Quality + +- [ ] All elements properly grouped +- [ ] Text elements have containerId +- [ ] Snapped to grid +- [ ] No elements with `isDeleted: true` +- [ ] JSON is valid +- [ ] File saved to correct location diff --git a/src/modules/bmm/workflows/frame-expert/create-wireframe/instructions.md b/src/modules/bmm/workflows/frame-expert/create-wireframe/instructions.md new file mode 100644 index 00000000..4be8f3d7 --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-wireframe/instructions.md @@ -0,0 +1,133 @@ +# Create Wireframe - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow creates website or app wireframes in Excalidraw format. + + + + + Review user's request and extract: wireframe type, fidelity level, screen count, device type, save location + Skip to Step 5 + + + + Ask: "What type of wireframe do you need?" + Present options: + 1. Website (Desktop) + 2. Mobile App (iOS/Android) + 3. Web App (Responsive) + 4. Tablet App + 5. Multi-platform + + WAIT for selection, store in {{wireframe_type}} + + + + Ask fidelity level (Low/Medium/High) + Ask screen count (Single/Few 2-3/Multiple 4-6/Many 7+) + Ask device dimensions or use standard + Ask save location + + + + Check for existing theme.json, ask to use if exists + + + + Ask: "Choose a wireframe style:" + Present numbered options: + 1. Classic Wireframe + - Background: #ffffff (white) + - Container: #f5f5f5 (light gray) + - Border: #9e9e9e (gray) + - Text: #424242 (dark gray) + + 2. High Contrast + - Background: #ffffff (white) + - Container: #eeeeee (light gray) + - Border: #212121 (black) + - Text: #000000 (black) + + 3. Blueprint Style + - Background: #1a237e (dark blue) + - Container: #3949ab (blue) + - Border: #7986cb (light blue) + - Text: #ffffff (white) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + Confirm with user + + + + List all screens and their purposes + Map navigation flow between screens + Identify key UI elements for each screen + Show planned structure, confirm with user + + + + Load {{templates}} and extract `wireframe` section + Load {{library}} + Load theme.json + Load {{helpers}} + + + + Follow {{helpers}} for proper element creation + + For Each Screen: + - Create container/frame + - Add header section + - Add content areas + - Add navigation elements + - Add interactive elements (buttons, inputs) + - Add labels and annotations + + + Build Order: + 1. Screen containers + 2. Layout sections (header, content, footer) + 3. Navigation elements + 4. Content blocks + 5. Interactive elements + 6. Labels and annotations + 7. Flow indicators (if multi-screen) + + + Fidelity Guidelines: + - Low: Basic shapes, minimal detail, placeholder text + - Medium: More defined elements, some styling, representative content + - High: Detailed elements, realistic sizing, actual content examples + + + + + Strip unused elements and elements with isDeleted: true + Save to {{save_location}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user + + + + Validate against {{validation}} + + + +``` diff --git a/src/modules/bmm/workflows/frame-expert/create-wireframe/workflow.yaml b/src/modules/bmm/workflows/frame-expert/create-wireframe/workflow.yaml new file mode 100644 index 00000000..d8a9928c --- /dev/null +++ b/src/modules/bmm/workflows/frame-expert/create-wireframe/workflow.yaml @@ -0,0 +1,24 @@ +name: create-wireframe +description: "Create website or app wireframes in Excalidraw format" +author: "BMad" + +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/create-wireframe" +shared_path: "{project-root}/{bmad_folder}/bmm/workflows/frame-expert/_shared" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +helpers: "{shared_path}/excalidraw-helpers.md" +templates: "{shared_path}/excalidraw-templates.yaml" +library: "{shared_path}/excalidraw-library.json" + +variables: + wireframe_type: "" + fidelity_level: "" + screen_count: "" + device_type: "" + save_location: "" + +default_output_file: "{project-root}/docs/wireframes/wireframe-{timestamp}.excalidraw" + +standalone: true +web_bundle: false