ma-agents 3.5.0 → 3.5.2

package/lib/bmad-cache/bmb/README.md

@@ -2,61 +2,73 @@
 
 [![Version](https://img.shields.io/npm/v/bmad-builder?color=blue&label=version)](https://www.npmjs.com/package/bmad-builder)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org)
+[![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
 **Build More, Architect Dreams... With the BMad Builder!**
 
-BMad Builder is so much more than a skill builder. BMad Method modules support:
+## Create, Share, and Discover Modules
 
-- **Agents** that transform your AI tool into exactly who you need to talk to — with memory that persists across sessions
-- **Workflows** that go far beyond simple tasks into truly guided, facilitated processes that can produce near-infinite steps and turns as needed
-- **Modules** that are entire ecosystems, not just skill packs — like the BMad Method module for agile AI-driven development. You can create simpler or vastly more complex modules for any entertainment or work purpose.
+BMad Builder gives you the complete pipeline to create your own AI modules and share them with the world. Build agents with persistent memory, guided workflows, or full module ecosystems, then distribute them through the [BMad Marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace) or any compliant public marketplace.
+
+The [Agent Skills open standard](https://agentskills.io/home) means your creations work across 40+ AI tools, not just one platform - but with the BMad Ecosystem they will also gain full integration.
+
+| Guide | What It Covers |
+| ----- | -------------- |
+| **[Quick Start](https://bmad-builder-docs.bmad-method.org)** | Set up BMad Builder and build your first skill |
+| **[Build Your First Module](https://bmad-builder-docs.bmad-method.org/tutorials/build-your-first-module/)** | Plan, build, scaffold, and validate a complete module |
+| **[Distribute Your Module](https://bmad-builder-docs.bmad-method.org/how-to/distribute-your-module/)** | Package and share your module for anyone to install |
 
 ## The Dream
 
-Imagine AI that truly knows you — a fitness coach that remembers every PR, a writing partner that knows your characters better than you do, a research assistant that learns your preferences.
+Imagine AI that truly knows you. A fitness coach that remembers every PR. A writing partner that knows your characters better than you do. A research assistant that learns your preferences.
 
 BMad Builder lets you create:
 
-- **Personal AI Companions** — Agents with memory that evolve with you over time
-- **Domain Experts** — Specialists for any field: legal, medical, creative, technical
-- **Workflow Automations** — Structured processes that guide you through complex tasks
-- **Custom Modules** — Bundle agents and workflows into shareable packages that can empower any type of business or domain
+- **Personal AI Companions**: Agents with memory that evolve with you over time
+- **Domain Experts**: Specialists for any field: legal, medical, creative, technical
+- **Workflow Automations**: Structured processes that guide you through complex tasks
+- **Custom Modules**: Bundle agents and workflows into shareable packages that can empower any type of business or domain
 
 ## What Makes It Different
 
-| Feature | Why It Matters |
-|---------|----------------|
-| **Persistent Memory** | Agents remember across sessions — they learn and grow |
-| **Composable** | Your creations work alongside the entire BMad ecosystem |
-| **Skill-Compliant** | Built on open standards that work with any AI tool |
-| **Shareable** | Package your modules for the BMad Marketplace (coming soon) |
+| Feature               | Why It Matters                                              |
+| --------------------- | ----------------------------------------------------------- |
+| **Persistent Memory** | Agents remember across sessions and keep improving          |
+| **Composable**        | Your creations work alongside the entire BMad ecosystem     |
+| **Skill-Compliant**   | Built on the open Agent Skills standard, works with 40+ AI tools |
+| **Shareable**         | Distribute through the BMad Marketplace or any compliant marketplace |
 
 ## What You Can Build
 
-| Domain | Example |
-|--------|---------|
-| **Personal** | Journal companion, habit coach, learning tutor |
+| Domain           | Example                                                     |
+| ---------------- | ----------------------------------------------------------- |
+| **Personal**     | Journal companion, habit coach, learning tutor              |
 | **Professional** | Code reviewer, documentation specialist, workflow automator |
-| **Creative** | Story architect, character developer, campaign designer |
-| **Any Domain** | If you can describe it, you can build it |
+| **Creative**     | Story architect, character developer, campaign designer     |
+| **Any Domain**   | If you can describe it, you can build it                    |
 
 ## Learn More
 
-**[Documentation and Quick Start](https://bmad-builder-docs.bmad-method.org)**
-
-Complete guides for building agents, workflows, and modules.
+**[Full Documentation](https://bmad-builder-docs.bmad-method.org)**: Concepts, design patterns, and reference for the complete builder toolkit.
 
 ## Community
 
-- **[Discord](https://discord.gg/gk8jAdXWmj)** — Get help and share what you've built
-- **[BMad Method](https://docs.bmad-method.org)** — Core framework documentation
+- [Discord](https://discord.gg/gk8jAdXWmj) — Get help and share what you've built
+- [YouTube](https://youtube.com/@BMadCode) — Tutorials, master class, and more
+- [X / Twitter](https://x.com/BMadCode)
+- [Website](https://bmadcode.com)
+
+## Support BMad
+
+BMad is free for everyone and always will be. Star this repo, [buy me a coffee](https://buymeacoffee.com/bmad), or email contact@bmadcode.com for corporate sponsorship.
 
 ## License
 
-MIT — see [LICENSE](LICENSE) for details.
+MIT. See [LICENSE](LICENSE) for details.
 
-**BMad Builder** — Part of the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) ecosystem.
+**BMad Builder**: Part of the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) ecosystem.
 
 [![Contributors](https://contrib.rocks/image?repo=bmad-code-org/bmad-builder)](https://github.com/bmad-code-org/bmad-builder/graphs/contributors)
 

package/lib/bmad-cache/bmb/_git_preserved/logs/HEAD

@@ -1 +1 @@
-0000000000000000000000000000000000000000 9a4ae856c2370fbee3d7e6e1b856725d809f7b53 Alon Mayaffit <alon.mayafit@gmail.com> 1774702732 +0300	clone: from https://github.com/bmad-code-org/bmad-builder
+0000000000000000000000000000000000000000 605e07656f9f633b5e429297388e1db9687d1996 Alon Mayaffit <alon.mayafit@gmail.com> 1775729260 +0300	clone: from https://github.com/bmad-code-org/bmad-builder

package/lib/bmad-cache/bmb/_git_preserved/logs/refs/heads/main

@@ -1 +1 @@
-0000000000000000000000000000000000000000 9a4ae856c2370fbee3d7e6e1b856725d809f7b53 Alon Mayaffit <alon.mayafit@gmail.com> 1774702732 +0300	clone: from https://github.com/bmad-code-org/bmad-builder
+0000000000000000000000000000000000000000 605e07656f9f633b5e429297388e1db9687d1996 Alon Mayaffit <alon.mayafit@gmail.com> 1775729260 +0300	clone: from https://github.com/bmad-code-org/bmad-builder

package/lib/bmad-cache/bmb/_git_preserved/logs/refs/remotes/origin/HEAD

@@ -1 +1 @@
-0000000000000000000000000000000000000000 9a4ae856c2370fbee3d7e6e1b856725d809f7b53 Alon Mayaffit <alon.mayafit@gmail.com> 1774702732 +0300	clone: from https://github.com/bmad-code-org/bmad-builder
+0000000000000000000000000000000000000000 605e07656f9f633b5e429297388e1db9687d1996 Alon Mayaffit <alon.mayafit@gmail.com> 1775729260 +0300	clone: from https://github.com/bmad-code-org/bmad-builder

package/lib/bmad-cache/bmb/_git_preserved/packed-refs

@@ -1,2 +1,2 @@
 # pack-refs with: peeled fully-peeled sorted 
-9a4ae856c2370fbee3d7e6e1b856725d809f7b53 refs/remotes/origin/main
+605e07656f9f633b5e429297388e1db9687d1996 refs/remotes/origin/main

package/lib/bmad-cache/bmb/_git_preserved/refs/heads/main

@@ -1 +1 @@
-9a4ae856c2370fbee3d7e6e1b856725d809f7b53
+605e07656f9f633b5e429297388e1db9687d1996

package/lib/bmad-cache/bmb/_git_preserved/shallow

@@ -1 +1 @@
-9a4ae856c2370fbee3d7e6e1b856725d809f7b53
+605e07656f9f633b5e429297388e1db9687d1996

package/lib/bmad-cache/bmb/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-builder",
-  "version": "1.1.0",
+  "version": "1.5.0",
   "private": true,
   "description": "A BMad Core expansion module that guides users through the creation of Modules Workflow and Agents",
   "keywords": [
@@ -31,11 +31,6 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky || exit 0",
-    "release": "npm run release:patch",
-    "release:major": "npm version major && git push --follow-tags",
-    "release:minor": "npm version minor && git push --follow-tags",
-    "release:patch": "npm version patch && git push --follow-tags",
-    "release:prerelease": "npm version prerelease && git push --follow-tags",
     "test": "npm run test:schemas && npm run test:refs && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:refs": "node test/test-validate-file-refs.cjs",
     "test:schemas": "node test/test-agent-schema.js",
@@ -92,8 +87,5 @@
   },
   "engines": {
     "node": ">=22.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/lib/bmad-cache/bmb/samples/bmad-agent-code-coach/scripts/init-sanctum.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+First Breath — Deterministic sanctum scaffolding for the Code Coach.
+
+This script runs BEFORE the conversational awakening. It creates the sanctum
+folder structure, copies template files with config values substituted,
+copies all capability files and their supporting references into the sanctum,
+and auto-generates CAPABILITIES.md from capability prompt frontmatter.
+
+After this script runs, the sanctum is fully self-contained — the agent does
+not depend on the skill bundle location for normal operation.
+
+Usage:
+    python3 init-sanctum.py <project-root> <skill-path>
+
+    project-root: The root of the project (where _bmad/ lives)
+    skill-path:   Path to the skill directory (where SKILL.md, references/, assets/ live)
+
+Example:
+    python3 scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-code-coach
+"""
+
+import sys
+import re
+import shutil
+from datetime import date
+from pathlib import Path
+
+SKILL_NAME = "bmad-agent-code-coach"
+SANCTUM_DIR = SKILL_NAME
+
+# Files that stay in the skill bundle (only used during First Breath)
+SKILL_ONLY_FILES = {"first-breath.md"}
+
+TEMPLATE_FILES = [
+    "INDEX-template.md",
+    "PERSONA-template.md",
+    "CREED-template.md",
+    "BOND-template.md",
+    "MEMORY-template.md",
+    "CAPABILITIES-template.md",
+    "PULSE-template.md",
+]
+
+EVOLVABLE = True
+
+
+def parse_yaml_config(config_path: Path) -> dict:
+    """Simple YAML key-value parser. Handles top-level scalar values only."""
+    config = {}
+    if not config_path.exists():
+        return config
+    with open(config_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if ":" in line:
+                key, _, value = line.partition(":")
+                value = value.strip().strip("'\"")
+                if value:
+                    config[key.strip()] = value
+    return config
+
+
+def parse_frontmatter(file_path: Path) -> dict:
+    """Extract YAML frontmatter from a markdown file."""
+    meta = {}
+    with open(file_path) as f:
+        content = f.read()
+
+    match = re.match(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return meta
+
+    for line in match.group(1).strip().split("\n"):
+        if ":" in line:
+            key, _, value = line.partition(":")
+            meta[key.strip()] = value.strip().strip("'\"")
+    return meta
+
+
+def copy_references(source_dir: Path, dest_dir: Path) -> list[str]:
+    """Copy all reference files (except skill-only files) into the sanctum."""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    copied = []
+
+    for source_file in sorted(source_dir.iterdir()):
+        if source_file.name in SKILL_ONLY_FILES:
+            continue
+        if source_file.is_file():
+            shutil.copy2(source_file, dest_dir / source_file.name)
+            copied.append(source_file.name)
+
+    return copied
+
+
+def copy_scripts(source_dir: Path, dest_dir: Path) -> list[str]:
+    """Copy any scripts the capabilities might use into the sanctum."""
+    if not source_dir.exists():
+        return []
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    copied = []
+
+    for source_file in sorted(source_dir.iterdir()):
+        if source_file.is_file() and source_file.name != "init-sanctum.py":
+            shutil.copy2(source_file, dest_dir / source_file.name)
+            copied.append(source_file.name)
+
+    return copied
+
+
+def discover_capabilities(references_dir: Path, sanctum_refs_path: str) -> list[dict]:
+    """Scan references/ for capability prompt files with frontmatter."""
+    capabilities = []
+
+    for md_file in sorted(references_dir.glob("*.md")):
+        if md_file.name in SKILL_ONLY_FILES:
+            continue
+        meta = parse_frontmatter(md_file)
+        if meta.get("name") and meta.get("code"):
+            capabilities.append({
+                "name": meta["name"],
+                "description": meta.get("description", ""),
+                "code": meta["code"],
+                "source": f"{sanctum_refs_path}/{md_file.name}",
+            })
+    return capabilities
+
+
+def generate_capabilities_md(capabilities: list[dict], evolvable: bool = False) -> str:
+    """Generate CAPABILITIES.md content from discovered capabilities."""
+    lines = [
+        "# Capabilities",
+        "",
+        "## Built-in",
+        "",
+        "| Code | Name | Description | Source |",
+        "|------|------|-------------|--------|",
+    ]
+    for cap in capabilities:
+        lines.append(
+            f"| [{cap['code']}] | {cap['name']} | {cap['description']} | `{cap['source']}` |"
+        )
+
+    lines.extend([
+        "",
+        "## Learned",
+        "",
+        "_Capabilities added by the owner over time. Prompts live in `capabilities/`._",
+        "",
+        "| Code | Name | Description | Source | Added |",
+        "|------|------|-------------|--------|-------|",
+        "",
+        "## How to Add a Capability",
+        "",
+        'Tell me "I want you to be able to do X" and we\'ll create it together.',
+        "I'll write the prompt, save it to `capabilities/`, and register it here.",
+        "Next session, I'll know how.",
+        "Load `./references/capability-authoring.md` for the full creation framework.",
+    ])
+
+    if evolvable:
+        lines.extend([
+            "",
+            "This agent is **evolvable** — you can teach it new skills, modify existing "
+            "ones, and retire capabilities that aren't useful. The built-in capabilities "
+            "above are starting points, not limits.",
+        ])
+
+    lines.extend([
+        "",
+        "## Tools",
+        "",
+        "Prefer crafting your own tools over depending on external ones. A script you wrote "
+        "and saved is more reliable than an external API. Use the file system creatively.",
+        "",
+        "### User-Provided Tools",
+        "",
+        "_MCP servers, APIs, or services the owner has made available. Document them here._",
+    ])
+
+    return "\n".join(lines) + "\n"
+
+
+def substitute_vars(content: str, variables: dict) -> str:
+    """Replace {var_name} placeholders with values from the variables dict."""
+    for key, value in variables.items():
+        content = content.replace(f"{{{key}}}", value)
+    return content
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python3 init-sanctum.py <project-root> <skill-path>")
+        sys.exit(1)
+
+    project_root = Path(sys.argv[1]).resolve()
+    skill_path = Path(sys.argv[2]).resolve()
+
+    # Paths
+    bmad_dir = project_root / "_bmad"
+    memory_dir = bmad_dir / "memory"
+    sanctum_path = memory_dir / SANCTUM_DIR
+    assets_dir = skill_path / "assets"
+    references_dir = skill_path / "references"
+    scripts_dir = skill_path / "scripts"
+
+    # Sanctum subdirectories
+    sanctum_refs = sanctum_path / "references"
+    sanctum_scripts = sanctum_path / "scripts"
+
+    # Fully qualified path for CAPABILITIES.md references
+    sanctum_refs_path = "./references"
+
+    # Check if sanctum already exists
+    if sanctum_path.exists():
+        print(f"Sanctum already exists at {sanctum_path}")
+        print("This agent has already been born. Skipping First Breath scaffolding.")
+        sys.exit(0)
+
+    # Load config
+    config = {}
+    for config_file in ["config.yaml", "config.user.yaml"]:
+        config.update(parse_yaml_config(bmad_dir / config_file))
+
+    # Build variable substitution map
+    today = date.today().isoformat()
+    variables = {
+        "user_name": config.get("user_name", "friend"),
+        "communication_language": config.get("communication_language", "English"),
+        "birth_date": today,
+        "project_root": str(project_root),
+        "sanctum_path": str(sanctum_path),
+    }
+
+    # Create sanctum structure
+    sanctum_path.mkdir(parents=True, exist_ok=True)
+    (sanctum_path / "capabilities").mkdir(exist_ok=True)
+    (sanctum_path / "sessions").mkdir(exist_ok=True)
+    print(f"Created sanctum at {sanctum_path}")
+
+    # Copy reference files (capabilities + guidance) into sanctum
+    copied_refs = copy_references(references_dir, sanctum_refs)
+    print(f"  Copied {len(copied_refs)} reference files to sanctum/references/")
+    for name in copied_refs:
+        print(f"    - {name}")
+
+    # Copy any supporting scripts into sanctum
+    copied_scripts = copy_scripts(scripts_dir, sanctum_scripts)
+    if copied_scripts:
+        print(f"  Copied {len(copied_scripts)} scripts to sanctum/scripts/")
+        for name in copied_scripts:
+            print(f"    - {name}")
+
+    # Copy and substitute template files
+    for template_name in TEMPLATE_FILES:
+        template_path = assets_dir / template_name
+        if not template_path.exists():
+            print(f"  Warning: template {template_name} not found, skipping")
+            continue
+
+        # Remove "-template" from the output filename and uppercase it
+        output_name = template_name.replace("-template", "").upper()
+        # Fix extension casing: .MD -> .md
+        output_name = output_name[:-3] + ".md"
+
+        content = template_path.read_text()
+        content = substitute_vars(content, variables)
+
+        output_path = sanctum_path / output_name
+        output_path.write_text(content)
+        print(f"  Created {output_name}")
+
+    # Auto-generate CAPABILITIES.md from references/ frontmatter
+    capabilities = discover_capabilities(references_dir, sanctum_refs_path)
+    capabilities_content = generate_capabilities_md(capabilities, evolvable=EVOLVABLE)
+    (sanctum_path / "CAPABILITIES.md").write_text(capabilities_content)
+    print(f"  Created CAPABILITIES.md ({len(capabilities)} built-in capabilities discovered)")
+
+    print()
+    print("First Breath scaffolding complete.")
+    print("The conversational awakening can now begin.")
+    print(f"Sanctum: {sanctum_path}")
+
+
+if __name__ == "__main__":
+    main()