siesa-agents 2.1.36 → 2.1.37

package/_bmad/core/resources/excalidraw/README.md

@@ -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

package/_bmad/core/resources/excalidraw/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

package/_bmad/core/resources/excalidraw/library-loader.md

@@ -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.

package/_bmad/core/resources/excalidraw/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.**

package/_bmad/core/tasks/index-docs.xml

@@ -0,0 +1,65 @@
+<task id="_bmad/core/tasks/index-docs" name="Index Docs"
+  description="Generates or updates an index.md of all documents in the specified directory" webskip="true" standalone="true">
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Scan Directory">
+      <i>List all files and subdirectories in the target location</i>
+    </step>
+
+    <step n="2" title="Group Content">
+      <i>Organize files by type, purpose, or subdirectory</i>
+    </step>
+
+    <step n="3" title="Generate Descriptions">
+      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the
+        filename</i>
+    </step>
+
+    <step n="4" title="Create/Update Index">
+      <i>Write or update index.md with organized file listings</i>
+    </step>
+  </flow>
+
+  <output-format>
+    <example>
+      # Directory Index
+
+      ## Files
+
+      - **[filename.ext](./filename.ext)** - Brief description
+      - **[another-file.ext](./another-file.ext)** - Brief description
+
+      ## Subdirectories
+
+      ### subfolder/
+
+      - **[file1.ext](./subfolder/file1.ext)** - Brief description
+      - **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+      ### another-folder/
+
+      - **[file3.ext](./another-folder/file3.ext)** - Brief description
+    </example>
+  </output-format>
+
+  <halt-conditions critical="true">
+    <i>HALT if target directory does not exist or is inaccessible</i>
+    <i>HALT if user does not have write permissions to create index.md</i>
+  </halt-conditions>
+
+  <validation>
+    <i>Use relative paths starting with ./</i>
+    <i>Group similar files together</i>
+    <i>Read file contents to generate accurate descriptions - don't guess from filenames</i>
+    <i>Keep descriptions concise but informative (3-10 words)</i>
+    <i>Sort alphabetically within groups</i>
+    <i>Skip hidden files (starting with .) unless specified</i>
+  </validation>
+</task>

package/_bmad/core/tasks/review-adversarial-general.xml

@@ -0,0 +1,41 @@
+<!-- if possible, run this in a separate subagent or process with read access to the project, 
+  but no context except the content to review -->
+
+<task id="_bmad/core/tasks/review-adversarial-general.xml" name="Adversarial Review (General)">
+  <objective>Cynically review content and produce findings</objective>
+
+  <inputs>
+    <input name="content" desc="Content to review - diff, spec, story, doc, or any artifact" />
+  </inputs>
+
+  <llm critical="true">
+    <i>You are a cynical, jaded reviewer with zero patience for sloppy work</i>
+    <i>The content was submitted by a clueless weasel and you expect to find problems</i>
+    <i>Be skeptical of everything</i>
+    <i>Look for what's missing, not just what's wrong</i>
+    <i>Use a precise, professional tone - no profanity or personal attacks</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Receive Content">
+      <action>Load the content to review from provided input or context</action>
+      <action>If content to review is empty, ask for clarification and abort task</action>
+      <action>Identify content type (diff, branch, uncommitted changes, document, etc.)</action>
+    </step>
+
+    <step n="2" title="Adversarial Analysis" critical="true">
+      <mandate>Review with extreme skepticism - assume problems exist</mandate>
+      <action>Find at least ten issues to fix or improve in the provided content</action>
+    </step>
+
+    <step n="3" title="Present Findings">
+      <action>Output findings as a Markdown list (descriptions only)</action>
+    </step>
+  </flow>
+
+  <halt-conditions>
+    <condition>HALT if zero findings - this is suspicious, re-analyze or ask for guidance</condition>
+    <condition>HALT if content is empty or unreadable</condition>
+  </halt-conditions>
+
+</task>

package/_bmad/core/tasks/shard-doc.xml

@@ -0,0 +1,109 @@
+<tool id="_bmad/core/tasks/shard-doc" name="Shard Document"
+  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections" webskip="true"
+  standalone="true">
+  <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
+
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <critical-context>
+    <i>Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index</i>
+  </critical-context>
+
+  <flow>
+    <step n="1" title="Get Source Document">
+      <action>Ask user for the source document path if not provided already</action>
+      <action>Verify file exists and is accessible</action>
+      <action>Verify file is markdown format (.md extension)</action>
+      <action if="file not found or not markdown">HALT with error message</action>
+    </step>
+
+    <step n="2" title="Get Destination Folder">
+      <action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
+      <action>Example: /path/to/architecture.md → /path/to/architecture/</action>
+      <action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
+      <action if="user accepts default">Use the suggested destination path</action>
+      <action if="user provides custom path">Use the custom destination path</action>
+      <action>Verify destination folder exists or can be created</action>
+      <action>Check write permissions for destination</action>
+      <action if="permission denied">HALT with error message</action>
+    </step>
+
+    <step n="3" title="Execute Sharding">
+      <action>Inform user that sharding is beginning</action>
+      <action>Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`</action>
+      <action>Capture command output and any errors</action>
+      <action if="command fails">HALT and display error to user</action>
+    </step>
+
+    <step n="4" title="Verify Output">
+      <action>Check that destination folder contains sharded files</action>
+      <action>Verify index.md was created in destination folder</action>
+      <action>Count the number of files created</action>
+      <action if="no files created">HALT with error message</action>
+    </step>
+
+    <step n="5" title="Report Completion">
+      <action>Display completion report to user including:</action>
+      <i>- Source document path and name</i>
+      <i>- Destination folder path</i>
+      <i>- Number of section files created</i>
+      <i>- Confirmation that index.md was created</i>
+      <i>- Any tool output or warnings</i>
+      <action>Inform user that sharding completed successfully</action>
+    </step>
+
+    <step n="6" title="Handle Original Document">
+      <critical>Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion</critical>
+      <action>Present user with options for the original document:</action>
+
+      <ask>What would you like to do with the original document `[source-document-name]`?
+
+        Options:
+        [d] Delete - Remove the original (recommended - shards can always be recombined)
+        [m] Move to archive - Move original to a backup/archive location
+        [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+
+        Your choice (d/m/k):</ask>
+
+      <check if="user selects 'd' (delete)">
+        <action>Delete the original source document file</action>
+        <action>Confirm deletion to user: "✓ Original document deleted: [source-document-path]"</action>
+        <note>The document can be reconstructed from shards by concatenating all section files in order</note>
+      </check>
+
+      <check if="user selects 'm' (move)">
+        <action>Determine default archive location: same directory as source, in an "archive" subfolder</action>
+        <action>Example: /path/to/architecture.md → /path/to/archive/architecture.md</action>
+        <ask>Archive location ([y] to use default: [default-archive-path], or provide custom path):</ask>
+        <action if="user accepts default">Use default archive path</action>
+        <action if="user provides custom path">Use custom archive path</action>
+        <action>Create archive directory if it doesn't exist</action>
+        <action>Move original document to archive location</action>
+        <action>Confirm move to user: "✓ Original document moved to: [archive-path]"</action>
+      </check>
+
+      <check if="user selects 'k' (keep)">
+        <action>Display warning to user:</action>
+        <output>⚠️ WARNING: Keeping both original and sharded versions is NOT recommended.
+
+          This creates confusion because:
+          - The discover_inputs protocol may load the wrong version
+          - Updates to one won't reflect in the other
+          - You'll have duplicate content taking up space
+
+          Consider deleting or archiving the original document.</output>
+        <action>Confirm user choice: "Original document kept at: [source-document-path]"</action>
+      </check>
+    </step>
+  </flow>
+
+  <halt-conditions critical="true">
+    <i>HALT if npx command fails or produces no output files</i>
+  </halt-conditions>
+</tool>