Initial commit: Brachnha Insight project setup
- Next.js 14+ with App Router and TypeScript - Tailwind CSS and ShadCN UI styling - Zustand state management - Dexie.js for IndexedDB (local-first data) - Auth.js v5 for authentication - BMAD framework integration Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Max
160
_bmad/core/resources/excalidraw/README.md
Normal file
160
_bmad/core/resources/excalidraw/README.md
Normal 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/excalidraw-diagrams/create-flowchart/workflow.yaml
|
||||
helpers: '{project-root}/_bmad/core/resources/excalidraw/excalidraw-helpers.md'
|
||||
json_validation: '{project-root}/_bmad/core/resources/excalidraw/validate-json-instructions.md'
|
||||
```
|
||||
|
||||
**Domain-specific additions:**
|
||||
|
||||
```yaml
|
||||
# workflows/excalidraw-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/core/resources/excalidraw/excalidraw-helpers.md'
|
||||
json_validation: '{project-root}/_bmad/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
_bmad/core/resources/excalidraw/excalidraw-helpers.md
Normal file
127
_bmad/core/resources/excalidraw/excalidraw-helpers.md
Normal 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
_bmad/core/resources/excalidraw/library-loader.md
Normal file
50
_bmad/core/resources/excalidraw/library-loader.md
Normal 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.
|
||||
@@ -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.**
|
||||
Reference in New Issue
Block a user