ma-agents 3.5.0 → 3.5.2

package/lib/bmad-cache/bmb/skills/bmad-agent-builder/scripts/process-template.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Process BMad agent template files.
+
+Performs deterministic variable substitution and conditional block processing
+on template files from assets/. Replaces {varName} placeholders with provided
+values and evaluates {if-X}...{/if-X} conditional blocks, keeping content
+when the condition is in the --true list and removing the entire block otherwise.
+"""
+
+# /// script
+# requires-python = ">=3.9"
+# ///
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+
+def process_conditionals(text: str, true_conditions: set[str]) -> tuple[str, list[str], list[str]]:
+    """Process {if-X}...{/if-X} conditional blocks, innermost first.
+
+    Returns (processed_text, conditions_true, conditions_false).
+    """
+    conditions_true: list[str] = []
+    conditions_false: list[str] = []
+
+    # Process innermost blocks first to handle nesting
+    pattern = re.compile(
+        r'\{if-([a-zA-Z0-9_-]+)\}(.*?)\{/if-\1\}',
+        re.DOTALL,
+    )
+
+    changed = True
+    while changed:
+        changed = False
+        match = pattern.search(text)
+        if match:
+            changed = True
+            condition = match.group(1)
+            inner = match.group(2)
+
+            if condition in true_conditions:
+                # Keep the inner content, strip the markers
+                # Remove a leading newline if the opening tag was on its own line
+                replacement = inner
+                if condition not in conditions_true:
+                    conditions_true.append(condition)
+            else:
+                # Remove the entire block
+                replacement = ''
+                if condition not in conditions_false:
+                    conditions_false.append(condition)
+
+            text = text[:match.start()] + replacement + text[match.end():]
+
+    # Clean up blank lines left by removed blocks: collapse 3+ consecutive
+    # newlines down to 2 (one blank line)
+    text = re.sub(r'\n{3,}', '\n\n', text)
+
+    return text, conditions_true, conditions_false
+
+
+def process_variables(text: str, variables: dict[str, str]) -> tuple[str, list[str]]:
+    """Replace {varName} placeholders with provided values.
+
+    Only replaces variables that are in the provided mapping.
+    Leaves unmatched {variables} untouched (they may be runtime config).
+
+    Returns (processed_text, list_of_substituted_var_names).
+    """
+    substituted: list[str] = []
+
+    for name, value in variables.items():
+        placeholder = '{' + name + '}'
+        if placeholder in text:
+            text = text.replace(placeholder, value)
+            if name not in substituted:
+                substituted.append(name)
+
+    return text, substituted
+
+
+def parse_var(s: str) -> tuple[str, str]:
+    """Parse a key=value string. Raises argparse error on bad format."""
+    if '=' not in s:
+        raise argparse.ArgumentTypeError(
+            f"Invalid variable format: '{s}' (expected key=value)"
+        )
+    key, _, value = s.partition('=')
+    if not key:
+        raise argparse.ArgumentTypeError(
+            f"Invalid variable format: '{s}' (empty key)"
+        )
+    return key, value
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description='Process BMad agent template files with variable substitution and conditional blocks.',
+    )
+    parser.add_argument(
+        'template',
+        help='Path to the template file to process',
+    )
+    parser.add_argument(
+        '-o', '--output',
+        help='Write processed output to file (default: stdout)',
+    )
+    parser.add_argument(
+        '--var',
+        action='append',
+        default=[],
+        metavar='key=value',
+        help='Variable substitution (repeatable). Example: --var skillName=my-agent',
+    )
+    parser.add_argument(
+        '--true',
+        action='append',
+        default=[],
+        dest='true_conditions',
+        metavar='CONDITION',
+        help='Condition name to treat as true (repeatable). Example: --true pulse --true evolvable',
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        dest='json_output',
+        help='Output processing metadata as JSON to stderr',
+    )
+
+    args = parser.parse_args()
+
+    # Parse variables
+    variables: dict[str, str] = {}
+    for v in args.var:
+        try:
+            key, value = parse_var(v)
+        except argparse.ArgumentTypeError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 2
+        variables[key] = value
+
+    true_conditions = set(args.true_conditions)
+
+    # Read template
+    try:
+        with open(args.template, encoding='utf-8') as f:
+            content = f.read()
+    except FileNotFoundError:
+        print(f"Error: Template file not found: {args.template}", file=sys.stderr)
+        return 2
+    except OSError as e:
+        print(f"Error reading template: {e}", file=sys.stderr)
+        return 1
+
+    # Process: conditionals first, then variables
+    content, conds_true, conds_false = process_conditionals(content, true_conditions)
+    content, vars_substituted = process_variables(content, variables)
+
+    # Write output
+    output_file = args.output
+    try:
+        if output_file:
+            with open(output_file, 'w', encoding='utf-8') as f:
+                f.write(content)
+        else:
+            sys.stdout.write(content)
+    except OSError as e:
+        print(f"Error writing output: {e}", file=sys.stderr)
+        return 1
+
+    # JSON metadata to stderr
+    if args.json_output:
+        metadata = {
+            'processed': True,
+            'output_file': output_file or '<stdout>',
+            'vars_substituted': vars_substituted,
+            'conditions_true': conds_true,
+            'conditions_false': conds_false,
+        }
+        print(json.dumps(metadata, indent=2), file=sys.stderr)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/lib/bmad-cache/bmb/skills/bmad-agent-builder/scripts/scan-path-standards.py

@@ -2,13 +2,13 @@
 """Deterministic path standards scanner for BMad skills.
 
 Validates all .md and .json files against BMad path conventions:
-1. {project-root} only valid before /_bmad
+1. {project-root} for any project-scope path (not just _bmad)
 2. Bare _bmad references must have {project-root} prefix
-3. Config variables used directly (no double-prefix)
-4. Skill-internal paths must use ./ prefix (references/, scripts/, assets/)
+3. Config variables used directly — no double-prefix with {project-root}
+4. ./ only for same-folder references — never ./subdir/ cross-directory
 5. No ../ parent directory references
 6. No absolute paths
-7. Memory paths must use {project-root}/_bmad/memory/{skillName}-sidecar/
+7. Memory paths must use {project-root}/_bmad/memory/{skillName}/
 8. Frontmatter allows only name and description
 9. No .md files at skill root except SKILL.md
 """
@@ -28,8 +28,8 @@ from pathlib import Path
 
 
 # Patterns to detect
-# {project-root} NOT followed by /_bmad
-PROJECT_ROOT_NOT_BMAD_RE = re.compile(r'\{project-root\}/(?!_bmad)')
+# Double-prefix: {project-root}/{config-variable} — config vars already contain project-root
+DOUBLE_PREFIX_RE = re.compile(r'\{project-root\}/\{[^}]+\}')
 # Bare _bmad without {project-root} prefix — match _bmad at word boundary
 # but not when preceded by {project-root}/
 BARE_BMAD_RE = re.compile(r'(?<!\{project-root\}/)_bmad[/\s]')
@@ -38,13 +38,12 @@ ABSOLUTE_PATH_RE = re.compile(r'(?:^|[\s"`\'(])(/(?:Users|home|opt|var|tmp|etc|u
 HOME_PATH_RE = re.compile(r'(?:^|[\s"`\'(])(~/\S+)', re.MULTILINE)
 # Parent directory reference (still invalid)
 RELATIVE_DOT_RE = re.compile(r'(?:^|[\s"`\'(])(\.\./\S+)', re.MULTILINE)
-# Bare skill-internal paths without ./ prefix
-# Match references/, scripts/, assets/ when NOT preceded by ./
-BARE_INTERNAL_RE = re.compile(r'(?:^|[\s"`\'(])(?<!\./)((?:references|scripts|assets)/\S+)', re.MULTILINE)
+# Cross-directory ./ — ./subdir/ is wrong because ./ means same folder only
+CROSS_DIR_DOT_SLASH_RE = re.compile(r'(?:^|[\s"`\'(])\./(?:references|scripts|assets)/\S+', re.MULTILINE)
 
 # Memory path pattern: should use {project-root}/_bmad/memory/
 MEMORY_PATH_RE = re.compile(r'_bmad/memory/\S+')
-VALID_MEMORY_PATH_RE = re.compile(r'\{project-root\}/_bmad/memory/\S+-sidecar/')
+VALID_MEMORY_PATH_RE = re.compile(r'\{project-root\}/_bmad/memory/[\w-]+/')
 
 # Fenced code block detection (to skip examples showing wrong patterns)
 FENCE_RE = re.compile(r'^```', re.MULTILINE)
@@ -142,16 +141,16 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
     rel_path = filepath.name
 
     checks = [
-        (PROJECT_ROOT_NOT_BMAD_RE, 'project-root-not-bmad', 'critical',
-         '{project-root} used for non-_bmad path — only valid use is {project-root}/_bmad/...'),
+        (DOUBLE_PREFIX_RE, 'double-prefix', 'critical',
+         'Double-prefix: {project-root}/{variable} — config variables already contain {project-root} at runtime'),
         (ABSOLUTE_PATH_RE, 'absolute-path', 'high',
          'Absolute path found — not portable across machines'),
         (HOME_PATH_RE, 'absolute-path', 'high',
          'Home directory path (~/) found — environment-specific'),
         (RELATIVE_DOT_RE, 'relative-prefix', 'high',
          'Parent directory reference (../) found — fragile, breaks with reorganization'),
-        (BARE_INTERNAL_RE, 'bare-internal-path', 'high',
-         'Bare skill-internal path without ./ prefix — use ./references/, ./scripts/, ./assets/ to distinguish from {project-root} paths'),
+        (CROSS_DIR_DOT_SLASH_RE, 'cross-dir-dot-slash', 'high',
+         'Cross-directory ./ reference — ./ means same folder only; use bare skill-root relative path (e.g., references/foo.md not ./references/foo.md)'),
     ]
 
     for pattern, category, severity, message in checks:
@@ -193,14 +192,13 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
             'action': '',
         })
 
-    # Memory path check — memory paths should use {project-root}/_bmad/memory/{skillName}-sidecar/
+    # Memory path check — memory paths should use {project-root}/_bmad/memory/{skillName}/
     for match in MEMORY_PATH_RE.finditer(content):
         pos = match.start()
         if skip_fenced and is_in_fenced_block(content, pos):
             continue
         start = max(0, pos - 20)
         before = content[start:pos]
-        matched_text = match.group()
         if '{project-root}/' not in before:
             line_num = get_line_number(content, pos)
             line_content = content.split('\n')[line_num - 1].strip()
@@ -213,18 +211,6 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
                 'detail': line_content[:120],
                 'action': '',
             })
-        elif '-sidecar/' not in matched_text:
-            line_num = get_line_number(content, pos)
-            line_content = content.split('\n')[line_num - 1].strip()
-            findings.append({
-                'file': rel_path,
-                'line': line_num,
-                'severity': 'high',
-                'category': 'memory-path',
-                'title': 'Memory path not using {skillName}-sidecar/ convention',
-                'detail': line_content[:120],
-                'action': '',
-            })
 
     return findings
 
@@ -259,12 +245,11 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     # Build summary
     by_severity = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0}
     by_category = {
-        'project_root_not_bmad': 0,
-        'bare_bmad': 0,
         'double_prefix': 0,
+        'bare_bmad': 0,
         'absolute_path': 0,
         'relative_prefix': 0,
-        'bare_internal_path': 0,
+        'cross_dir_dot_slash': 0,
         'memory_path': 0,
         'frontmatter': 0,
         'structure': 0,
@@ -281,7 +266,7 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     return {
         'scanner': 'path-standards',
         'script': 'scan-path-standards.py',
-        'version': '2.0.0',
+        'version': '3.0.0',
         'skill_path': str(skill_path),
         'timestamp': datetime.now(timezone.utc).isoformat(),
         'files_scanned': files_scanned,

package/lib/bmad-cache/bmb/skills/bmad-agent-builder/scripts/scan-scripts.py

@@ -281,12 +281,14 @@ def scan_python_script(filepath: Path, rel_path: str) -> list[dict]:
                 'action': 'Add requires-python = ">=3.9" or appropriate version',
             })
 
-    # requirements.txt reference
-    if 'requirements.txt' in content or 'pip install' in content:
+    # Legacy dep-management reference (use concatenation to avoid self-detection)
+    req_marker = 'requirements' + '.txt'
+    pip_marker = 'pip ' + 'install'
+    if req_marker in content or pip_marker in content:
         findings.append({
             'file': rel_path, 'line': 1,
             'severity': 'high', 'category': 'dependencies',
-            'title': 'References requirements.txt or pip install — use PEP 723 inline deps',
+            'title': f'References {req_marker} or {pip_marker} — use PEP 723 inline deps',
             'detail': '',
             'action': 'Replace with PEP 723 inline dependency block',
         })

package/lib/bmad-cache/bmb/skills/bmad-bmb-setup/assets/module-help.csv

@@ -0,0 +1,10 @@
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+BMad Builder,bmad-bmb-setup,Setup Builder Module,SB,"Install or update BMad Builder module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml
+BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,bmad_builder_output_folder,agent skill
+BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report
+BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, or rebuild a workflow or utility skill.",build-process,"{-H: headless mode}|{description: initial skill concept}|{path: existing skill to edit or rebuild}",anytime,,bmad-workflow-builder:quality-analysis,false,bmad_builder_output_folder,workflow skill
+BMad Builder,bmad-workflow-builder,Analyze a Workflow,AW,"Run quality analysis on an existing workflow/skill — structure, efficiency, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: skill to analyze}",anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report
+BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"{--convert: path or URL to source skill}|{-H: headless mode}",anytime,,,false,bmad_builder_reports,converted skill + comparison report
+BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,"{description: initial module idea}",anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan
+BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold module infrastructure into built skills, making them an installable BMad module.",create-module,"{-H: headless mode}|{path: skills folder or single SKILL.md}",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill
+BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's structure is complete, accurate, and all capabilities are properly registered.",validate-module,"{-H: headless mode}|{path: module or skill to validate}",anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report

package/lib/bmad-cache/bmb/skills/bmad-bmb-setup/scripts/cleanup-legacy.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Remove legacy module directories from _bmad/ after config migration.
+
+After merge-config.py and merge-help-csv.py have migrated config data and
+deleted individual legacy files, this script removes the now-redundant
+directory trees. These directories contain skill files that are already
+installed at .claude/skills/ (or equivalent) — only the config files at
+_bmad/ root need to persist.
+
+When --skills-dir is provided, the script verifies that every skill found
+in the legacy directories exists at the installed location before removing
+anything. Directories without skills (like _config/) are removed directly.
+
+Exit codes: 0=success (including nothing to remove), 1=validation error, 2=runtime error
+"""
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Remove legacy module directories from _bmad/ after config migration."
+    )
+    parser.add_argument(
+        "--bmad-dir",
+        required=True,
+        help="Path to the _bmad/ directory",
+    )
+    parser.add_argument(
+        "--module-code",
+        required=True,
+        help="Module code being cleaned up (e.g. 'bmb')",
+    )
+    parser.add_argument(
+        "--also-remove",
+        action="append",
+        default=[],
+        help="Additional directory names under _bmad/ to remove (repeatable)",
+    )
+    parser.add_argument(
+        "--skills-dir",
+        help="Path to .claude/skills/ — enables safety verification that skills "
+        "are installed before removing legacy copies",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed progress to stderr",
+    )
+    return parser.parse_args()
+
+
+def find_skill_dirs(base_path: str) -> list:
+    """Find directories that contain a SKILL.md file.
+
+    Walks the directory tree and returns the leaf directory name for each
+    directory containing a SKILL.md. These are considered skill directories.
+
+    Returns:
+        List of skill directory names (e.g. ['bmad-agent-builder', 'bmad-builder-setup'])
+    """
+    skills = []
+    root = Path(base_path)
+    if not root.exists():
+        return skills
+    for skill_md in root.rglob("SKILL.md"):
+        skills.append(skill_md.parent.name)
+    return sorted(set(skills))
+
+
+def verify_skills_installed(
+    bmad_dir: str, dirs_to_check: list, skills_dir: str, verbose: bool = False
+) -> list:
+    """Verify that skills in legacy directories exist at the installed location.
+
+    Scans each directory in dirs_to_check for skill folders (containing SKILL.md),
+    then checks that a matching directory exists under skills_dir. Directories
+    that contain no skills (like _config/) are silently skipped.
+
+    Returns:
+        List of verified skill names.
+
+    Raises SystemExit(1) if any skills are missing from skills_dir.
+    """
+    all_verified = []
+    missing = []
+
+    for dirname in dirs_to_check:
+        legacy_path = Path(bmad_dir) / dirname
+        if not legacy_path.exists():
+            continue
+
+        skill_names = find_skill_dirs(str(legacy_path))
+        if not skill_names:
+            if verbose:
+                print(
+                    f"No skills found in {dirname}/ — skipping verification",
+                    file=sys.stderr,
+                )
+            continue
+
+        for skill_name in skill_names:
+            installed_path = Path(skills_dir) / skill_name
+            if installed_path.is_dir():
+                all_verified.append(skill_name)
+                if verbose:
+                    print(
+                        f"Verified: {skill_name} exists at {installed_path}",
+                        file=sys.stderr,
+                    )
+            else:
+                missing.append(skill_name)
+                if verbose:
+                    print(
+                        f"MISSING: {skill_name} not found at {installed_path}",
+                        file=sys.stderr,
+                    )
+
+    if missing:
+        error_result = {
+            "status": "error",
+            "error": "Skills not found at installed location",
+            "missing_skills": missing,
+            "skills_dir": str(Path(skills_dir).resolve()),
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+    return sorted(set(all_verified))
+
+
+def count_files(path: Path) -> int:
+    """Count all files recursively in a directory."""
+    count = 0
+    for item in path.rglob("*"):
+        if item.is_file():
+            count += 1
+    return count
+
+
+def cleanup_directories(
+    bmad_dir: str, dirs_to_remove: list, verbose: bool = False
+) -> tuple:
+    """Remove specified directories under bmad_dir.
+
+    Returns:
+        (removed, not_found, total_files_removed) tuple
+    """
+    removed = []
+    not_found = []
+    total_files = 0
+
+    for dirname in dirs_to_remove:
+        target = Path(bmad_dir) / dirname
+        if not target.exists():
+            not_found.append(dirname)
+            if verbose:
+                print(f"Not found (skipping): {target}", file=sys.stderr)
+            continue
+
+        if not target.is_dir():
+            if verbose:
+                print(f"Not a directory (skipping): {target}", file=sys.stderr)
+            not_found.append(dirname)
+            continue
+
+        file_count = count_files(target)
+        if verbose:
+            print(
+                f"Removing {target} ({file_count} files)",
+                file=sys.stderr,
+            )
+
+        try:
+            shutil.rmtree(target)
+        except OSError as e:
+            error_result = {
+                "status": "error",
+                "error": f"Failed to remove {target}: {e}",
+                "directories_removed": removed,
+                "directories_failed": dirname,
+            }
+            print(json.dumps(error_result, indent=2))
+            sys.exit(2)
+
+        removed.append(dirname)
+        total_files += file_count
+
+    return removed, not_found, total_files
+
+
+def main():
+    args = parse_args()
+
+    bmad_dir = args.bmad_dir
+    module_code = args.module_code
+
+    # Build the list of directories to remove
+    dirs_to_remove = [module_code, "core"] + args.also_remove
+    # Deduplicate while preserving order
+    seen = set()
+    unique_dirs = []
+    for d in dirs_to_remove:
+        if d not in seen:
+            seen.add(d)
+            unique_dirs.append(d)
+    dirs_to_remove = unique_dirs
+
+    if args.verbose:
+        print(f"Directories to remove: {dirs_to_remove}", file=sys.stderr)
+
+    # Safety check: verify skills are installed before removing
+    verified_skills = None
+    if args.skills_dir:
+        if args.verbose:
+            print(
+                f"Verifying skills installed at {args.skills_dir}",
+                file=sys.stderr,
+            )
+        verified_skills = verify_skills_installed(
+            bmad_dir, dirs_to_remove, args.skills_dir, args.verbose
+        )
+
+    # Remove directories
+    removed, not_found, total_files = cleanup_directories(
+        bmad_dir, dirs_to_remove, args.verbose
+    )
+
+    # Build result
+    result = {
+        "status": "success",
+        "bmad_dir": str(Path(bmad_dir).resolve()),
+        "directories_removed": removed,
+        "directories_not_found": not_found,
+        "files_removed_count": total_files,
+    }
+
+    if args.skills_dir:
+        result["safety_checks"] = {
+            "skills_verified": True,
+            "skills_dir": str(Path(args.skills_dir).resolve()),
+            "verified_skills": verified_skills,
+        }
+    else:
+        result["safety_checks"] = None
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()