ma-agents 2.19.2 → 2.20.1

package/lib/bmad-cache/bmb/samples/bmad-excalidraw/scripts/validate_excalidraw.py

@@ -0,0 +1,264 @@
+# /// script
+# requires-python = ">=3.9"
+# ///
+"""
+Excalidraw File Validator
+
+Validates .excalidraw files for structural correctness.
+
+Usage:
+    python validate_excalidraw.py path/to/diagram.excalidraw
+    python validate_excalidraw.py path/to/diagram.excalidraw -o report.json
+
+Exit codes: 0=pass, 1=fail, 2=error
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+VALID_ELEMENT_TYPES = {
+    "rectangle", "ellipse", "diamond", "arrow", "line",
+    "freedraw", "text", "image", "frame",
+}
+
+VALID_FILL_STYLES = {"solid", "hachure", "cross-hatch", "zigzag", "dots", "dashed", "zigzag-line"}
+VALID_STROKE_STYLES = {"solid", "dashed", "dotted"}
+VALID_TEXT_ALIGN = {"left", "center", "right"}
+VALID_VERTICAL_ALIGN = {"top", "middle"}
+VALID_ARROWHEADS = {None, "arrow", "bar", "dot", "triangle"}
+
+
+def validate(file_path):
+    """Validate an .excalidraw file and return findings."""
+    findings = []
+
+    try:
+        data = json.loads(Path(file_path).read_text())
+    except json.JSONDecodeError as e:
+        findings.append({
+            "severity": "critical",
+            "category": "parse",
+            "location": {"file": str(file_path)},
+            "issue": f"Invalid JSON: {e}",
+            "fix": "Fix JSON syntax errors",
+        })
+        return findings
+    except FileNotFoundError:
+        findings.append({
+            "severity": "critical",
+            "category": "file",
+            "location": {"file": str(file_path)},
+            "issue": "File not found",
+            "fix": "Check the file path",
+        })
+        return findings
+
+    # Top-level structure
+    if data.get("type") != "excalidraw":
+        findings.append({
+            "severity": "critical",
+            "category": "structure",
+            "location": {"file": str(file_path)},
+            "issue": f"Invalid type field: '{data.get('type')}', expected 'excalidraw'",
+            "fix": "Set type to 'excalidraw'",
+        })
+
+    if "elements" not in data:
+        findings.append({
+            "severity": "critical",
+            "category": "structure",
+            "location": {"file": str(file_path)},
+            "issue": "Missing 'elements' array",
+            "fix": "Add 'elements' array",
+        })
+        return _build_result(file_path, findings)
+
+    if not isinstance(data["elements"], list):
+        findings.append({
+            "severity": "critical",
+            "category": "structure",
+            "location": {"file": str(file_path)},
+            "issue": "'elements' must be an array",
+            "fix": "Change 'elements' to an array",
+        })
+        return _build_result(file_path, findings)
+
+    # Validate elements
+    seen_ids = set()
+    element_ids = {e.get("id") for e in data["elements"] if e.get("id")}
+
+    for i, elem in enumerate(data["elements"]):
+        loc = {"file": str(file_path), "element_index": i, "element_id": elem.get("id")}
+
+        # Required fields
+        if "id" not in elem:
+            findings.append({
+                "severity": "critical",
+                "category": "element",
+                "location": loc,
+                "issue": f"Element {i} missing 'id'",
+                "fix": "Add unique 'id' to element",
+            })
+        elif elem["id"] in seen_ids:
+            findings.append({
+                "severity": "critical",
+                "category": "element",
+                "location": loc,
+                "issue": f"Duplicate element ID: '{elem['id']}'",
+                "fix": "Use unique IDs for all elements",
+            })
+        else:
+            seen_ids.add(elem["id"])
+
+        if "type" not in elem:
+            findings.append({
+                "severity": "critical",
+                "category": "element",
+                "location": loc,
+                "issue": f"Element {i} missing 'type'",
+                "fix": "Add valid element type",
+            })
+        elif elem["type"] not in VALID_ELEMENT_TYPES:
+            findings.append({
+                "severity": "high",
+                "category": "element",
+                "location": loc,
+                "issue": f"Invalid element type: '{elem['type']}'",
+                "fix": f"Use one of: {', '.join(sorted(VALID_ELEMENT_TYPES))}",
+            })
+
+        # Position and size
+        for field in ("x", "y", "width", "height"):
+            if field not in elem:
+                findings.append({
+                    "severity": "high",
+                    "category": "element",
+                    "location": loc,
+                    "issue": f"Element missing '{field}'",
+                    "fix": f"Add '{field}' (number)",
+                })
+
+        # Type-specific validation
+        if elem.get("type") == "text":
+            if "text" not in elem:
+                findings.append({
+                    "severity": "high",
+                    "category": "text",
+                    "location": loc,
+                    "issue": "Text element missing 'text' field",
+                    "fix": "Add 'text' field with content",
+                })
+            if elem.get("textAlign") and elem["textAlign"] not in VALID_TEXT_ALIGN:
+                findings.append({
+                    "severity": "medium",
+                    "category": "text",
+                    "location": loc,
+                    "issue": f"Invalid textAlign: '{elem['textAlign']}'",
+                    "fix": f"Use one of: {', '.join(VALID_TEXT_ALIGN)}",
+                })
+
+        if elem.get("type") in ("arrow", "line"):
+            if "points" not in elem:
+                findings.append({
+                    "severity": "high",
+                    "category": "linear",
+                    "location": loc,
+                    "issue": "Arrow/line missing 'points' array",
+                    "fix": "Add 'points' array with at least 2 points",
+                })
+            elif len(elem.get("points", [])) < 2:
+                findings.append({
+                    "severity": "high",
+                    "category": "linear",
+                    "location": loc,
+                    "issue": "Arrow/line needs at least 2 points",
+                    "fix": "Add start and end points: [[0,0],[dx,dy]]",
+                })
+
+            # Validate bindings reference existing elements
+            for binding_key in ("startBinding", "endBinding"):
+                binding = elem.get(binding_key)
+                if binding and isinstance(binding, dict):
+                    ref_id = binding.get("elementId")
+                    if ref_id and ref_id not in element_ids:
+                        findings.append({
+                            "severity": "medium",
+                            "category": "binding",
+                            "location": loc,
+                            "issue": f"{binding_key} references non-existent element '{ref_id}'",
+                            "fix": "Fix element ID reference or remove binding",
+                        })
+
+        # Validate style properties
+        if elem.get("fillStyle") and elem["fillStyle"] not in VALID_FILL_STYLES:
+            findings.append({
+                "severity": "low",
+                "category": "style",
+                "location": loc,
+                "issue": f"Non-standard fillStyle: '{elem['fillStyle']}'",
+                "fix": f"Use one of: {', '.join(sorted(VALID_FILL_STYLES))}",
+            })
+
+        if elem.get("strokeStyle") and elem["strokeStyle"] not in VALID_STROKE_STYLES:
+            findings.append({
+                "severity": "low",
+                "category": "style",
+                "location": loc,
+                "issue": f"Non-standard strokeStyle: '{elem['strokeStyle']}'",
+                "fix": f"Use one of: {', '.join(sorted(VALID_STROKE_STYLES))}",
+            })
+
+    return _build_result(file_path, findings)
+
+
+def _build_result(file_path, findings):
+    """Build the structured validation result."""
+    severity_counts = {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0}
+    for f in findings:
+        severity_counts[f["severity"]] = severity_counts.get(f["severity"], 0) + 1
+
+    status = "pass"
+    if severity_counts["critical"] > 0 or severity_counts["high"] > 0:
+        status = "fail"
+    elif severity_counts["medium"] > 0:
+        status = "warning"
+
+    return {
+        "script": "validate-excalidraw",
+        "version": "1.0.0",
+        "skill_path": str(file_path),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "status": status,
+        "findings": findings,
+        "summary": {
+            "total": len(findings),
+            **severity_counts,
+        },
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate .excalidraw files")
+    parser.add_argument("file", help="Path to .excalidraw file")
+    parser.add_argument("-o", "--output", help="Output report to file (JSON)")
+
+    args = parser.parse_args()
+    result = validate(args.file)
+
+    output = json.dumps(result, indent=2)
+    if args.output:
+        Path(args.output).write_text(output)
+        print(f"Report written to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+    if result["status"] == "fail":
+        sys.exit(1)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/lib/bmad-cache/bmb/src/module-help.csv

@@ -0,0 +1,7 @@
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+bmb,anytime,Create Agent,CA,,skill:bmad-agent-builder,bmad-agent-builder,false,,Create Mode,"Build a new agent skill from scratch through guided conversational discovery.",output_folder,"agent skill",
+bmb,anytime,Edit Agent,EA,,skill:bmad-agent-builder,bmad-agent-builder,false,,Edit Mode,"Edit, convert or fix an existing agent skill.",output_folder,"agent skill",
+bmb,anytime,Optimize Agent,OA,,skill:bmad-agent-builder,bmad-agent-builder,false,,Validate Mode,"Quality check, validate, review or optimize an existing agent skill.",output_folder,"quality report",
+bmb,anytime,Create Workflow,CW,,skill:bmad-workflow-builder,bmad-workflow-builder,false,,Create Mode,"Build a new workflow or skill from scratch through guided conversational discovery.",output_folder,"workflow or skill",
+bmb,anytime,Edit Workflow,EW,,skill:bmad-workflow-builder,bmad-workflow-builder,false,,Edit Mode,"Edit, convert or fix an existing workflow or skill.",output_folder,"workflow or skill",
+bmb,anytime,Optimize Workflow,OW,,skill:bmad-workflow-builder,bmad-workflow-builder,false,,Validate Mode,"Quality check, validate, review or optimize an existing workflow or skill.",output_folder,"quality report",

package/lib/bmad-cache/bmb/src/module.yaml

@@ -0,0 +1,20 @@
+code: bmb
+name: "BMad Builder"
+description: "Standard Skill Compliant Factory for BMad Agents, Workflows and Modules"
+default_selected: false
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+bmad_builder_output_folder:
+  prompt: "Where should your custom skills (agents and workflows) be saved?"
+  default: "_bmad-output/skills"
+  result: "{project-root}/{value}"
+
+bmad_builder_reports:
+  prompt: "Output for Evals, Test, Quality and Planning Reports?"
+  default: "_bmad-output/reports"
+  result: "{project-root}/{value}"

package/lib/bmad-cache/bmb/src/skills/bmad-agent-builder/bmad-manifest.json

@@ -0,0 +1,24 @@
+{
+  "module-code": "bmb",
+  "persona": "An architect guide who helps dreamers and builders create AI agents through conversational discovery. Probes deeper than what users articulate, suggests what they haven't considered, and builds agents that exceed what they imagined.",
+  "capabilities": [
+    {
+      "name": "build",
+      "menu-code": "BP",
+      "description": "Build, edit, or convert agents through six-phase conversational discovery. Covers new agents, format conversion, edits, and fixes.",
+      "supports-headless": true,
+      "prompt": "build-process.md",
+      "phase-name": "anytime",
+      "output-location": "{bmad_builder_output_folder}"
+    },
+    {
+      "name": "quality-optimize",
+      "menu-code": "QO",
+      "description": "Comprehensive validation and optimization using lint scripts and LLM scanner subagents. Structure, prompt craft, efficiency, and more.",
+      "supports-headless": true,
+      "prompt": "quality-optimizer.md",
+      "phase-name": "anytime",
+      "output-location": "{bmad_builder_reports}"
+    }
+  ]
+}

package/lib/bmad-cache/bmb/src/skills/bmad-agent-builder/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/lib/bmad-cache/bmb/src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BMad Manifest Schema",
+  "description": "Unified schema for all BMad skill manifest files (agents, workflows, skills)",
+
+  "type": "object",
+
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema identifier",
+      "type": "string"
+    },
+
+    "module-code": {
+      "description": "Short code for the module this skill belongs to (e.g., bmb, cis). Omit for standalone skills.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+
+    "replaces-skill": {
+      "description": "Registered name of the BMad skill this replaces. Inherits metadata during bmad-init.",
+      "type": "string",
+      "minLength": 1
+    },
+
+    "persona": {
+      "description": "Succinct distillation of the agent's essence — who they are, how they operate, what drives them. Presence of this field indicates the skill is an agent. Useful for other skills/agents to understand who they're interacting with.",
+      "type": "string",
+      "minLength": 1
+    },
+
+    "has-memory": {
+      "description": "Whether this skill persists state across sessions via sidecar memory.",
+      "type": "boolean"
+    },
+
+    "capabilities": {
+      "description": "What this skill can do. Every skill has at least one capability.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "description": "Capability identifier (kebab-case)",
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "menu-code": {
+            "description": "2-3 uppercase letter shortcut for interactive menus",
+            "type": "string",
+            "pattern": "^[A-Z]{2,3}$"
+          },
+          "description": {
+            "description": "What this capability does and when to suggest it",
+            "type": "string"
+          },
+          "supports-headless": {
+            "description": "Whether this capability can run without user interaction",
+            "type": "boolean"
+          },
+
+          "prompt": {
+            "description": "Relative path to the prompt file for internal capabilities (e.g., build-process.md). Omit if handled by SKILL.md directly or if this is an external skill call.",
+            "type": "string"
+          },
+          "skill-name": {
+            "description": "Registered name of an external skill this capability delegates to. Omit for internal capabilities.",
+            "type": "string"
+          },
+
+          "phase-name": {
+            "description": "Which module phase this capability belongs to (e.g., planning, design, anytime). For module sequencing.",
+            "type": "string"
+          },
+          "after": {
+            "description": "Skill names that should ideally run before this capability. If is-required is true on those skills, they block this one.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "before": {
+            "description": "Skill names that this capability should ideally run before. Helps the module sequencer understand ordering.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "is-required": {
+            "description": "Whether this capability must complete before skills listed in its 'before' array can proceed.",
+            "type": "boolean"
+          },
+          "output-location": {
+            "description": "Where this capability writes its output. May contain config variables (e.g., {bmad_builder_output_folder}/agents/).",
+            "type": "string"
+          }
+        },
+        "required": ["name", "menu-code", "description"],
+        "additionalProperties": false
+      }
+    }
+  },
+
+  "required": ["capabilities"],
+  "additionalProperties": false
+}