ma-agents 3.13.2 → 3.14.0

package/lib/bmad-cache/bmb/skills/bmad-agent-builder/assets/wake-template.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""
+Waking — load the agent's sanctum in one pass, or route to First Breath.
+
+Run on activation. Determines the mode from the filesystem (and the --pulse
+flag) and, when the sanctum exists, prints the full identity in a single read
+(INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES) so the agent becomes itself
+in one shot instead of six. In --pulse mode it also appends PULSE.md. When no
+sanctum exists, it prints a directive to run First Breath.
+
+This loads runtime memory only. It never reads or writes config or customize.toml.
+
+Usage:
+    uv run wake.py <project-root> [--pulse]
+
+    project-root: The root of the project (where _bmad/ lives)
+"""
+
+import sys
+from pathlib import Path
+
+SKILL_NAME = "{skillName}"
+
+# Load order — the "become yourself" set.
+IDENTITY_FILES = [
+    "INDEX.md",
+    "PERSONA.md",
+    "CREED.md",
+    "BOND.md",
+    "MEMORY.md",
+    "CAPABILITIES.md",
+]
+
+
+def emit(path: Path) -> None:
+    print(f"\n===== {path.name} =====")
+    try:
+        print(path.read_text(encoding="utf-8").rstrip())
+    except FileNotFoundError:
+        print(f"(missing: {path.name})")
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    pulse = "--pulse" in args
+    positional = [a for a in args if not a.startswith("--")]
+    if not positional:
+        print("Usage: wake.py <project-root> [--pulse]", file=sys.stderr)
+        return 2
+
+    project_root = Path(positional[0]).resolve()
+    sanctum = project_root / "_bmad" / "memory" / SKILL_NAME
+
+    core_ok = (
+        sanctum.is_dir()
+        and (sanctum / "CREED.md").is_file()
+        and (sanctum / "MEMORY.md").is_file()
+    )
+    if not core_ok:
+        print("MODE: FIRST_BREATH")
+        print(f"NO SANCTUM at {sanctum}")
+        print("This is your one birth. Load references/first-breath.md and follow it.")
+        return 0
+
+    print("MODE: PULSE" if pulse else "MODE: WAKING")
+    print(f"Sanctum: {sanctum}")
+    for name in IDENTITY_FILES:
+        emit(sanctum / name)
+    if pulse:
+        emit(sanctum / "PULSE.md")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/lib/bmad-cache/bmb/skills/bmad-agent-builder/customize.toml

@@ -0,0 +1,48 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Customization surface for bmad-agent-builder. This governs how the builder
+# builds: the org-wide context, standards, and gates applied to every agent it
+# produces. It is distinct from the per-built-agent customize.toml the builder
+# emits during an individual build.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-agent-builder.toml         (team)
+#   {project-root}/_bmad/custom/bmad-agent-builder.user.toml    (personal)
+
+[agent]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays: append
+
+# Steps to run before standard activation (config load, greet).
+# Use for org pre-flight loads or compliance checks.
+activation_steps_prepend = []
+
+# Steps to run after intent routing, before the build/analyze loop begins.
+activation_steps_append = []
+
+# Standards the builder keeps in mind for the whole session, loaded as context
+# into every build and analyze. Each entry is a literal sentence, a `skill:`
+# skill, or a `file:` path/glob whose contents load as facts. Use for house
+# conventions you want present but not hard-gated (for gates, see build_standards).
+#   "Every agent persona names its owner relationship explicitly."
+#   "file:{project-root}/_bmad/standards/agent-house-style.md"
+persistent_facts = ["file:{project-root}/**/project-context.md"]
+
+# Executed when a build or analyze run completes, after the user has been told
+# the artifact is ready. String scalar (one instruction) or array (in order).
+on_complete = ""
+
+# --- Builder gates ---
+
+# Hard standards every BUILT agent must satisfy. Unlike persistent_facts
+# (context), these are enforced: applied as build criteria and checked again as
+# a conformance pass during Analyze. Each entry is a `skill:`, `file:`, or
+# plain-text directive. Append-only. Empty by default (no org gates).
+build_standards = []
+
+# Eval requirement for a build to be declared done. Empty (default) keeps evals
+# opt-in, offered at the eval beat but never forced.
+#   "baseline"  -- require a passing baseline run (agent beats the bare model)
+#   "any"       -- require at least one eval case to exist and pass
+evals_required = ""

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# vendored from bmad-workflow-builder/scripts; canonical source there
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["tiktoken"]
+# ///
+"""count_tokens — the single length metric for skill authoring.
+
+Token counts replace line counts everywhere in the builder and eval-runner.
+This script reports the token length of a file or of text piped on stdin, using
+the tiktoken cl100k_base encoding. When tiktoken is not installed it falls back
+to a character-based estimate (len(text) // 4) and says so, so the script always
+runs under a bare python3 even with no third-party packages present.
+
+Usage:
+  count_tokens.py <file>     count the tokens in a file
+  count_tokens.py --stdin    count the tokens read from stdin
+
+Output (one line of JSON on stdout):
+  {"tokens": <int>, "method": "tiktoken"}   when tiktoken loaded
+  {"tokens": <int>, "method": "fallback"}   when it fell back to chars // 4
+
+Budgets this feeds: SKILL.md ~1500-2500, multi-branch reference ~4500,
+single-purpose reference ~9000.
+"""
+import argparse
+import json
+import sys
+
+ENCODING = "cl100k_base"
+
+
+def count_tokens(text: str) -> tuple[int, str]:
+    """Return (token_count, method).
+
+    Tries tiktoken's cl100k_base encoding first. If tiktoken cannot be imported
+    or initialized, estimates with len(text) // 4 and reports method "fallback".
+    """
+    try:
+        import tiktoken
+    except Exception:
+        return len(text) // 4, "fallback"
+    try:
+        enc = tiktoken.get_encoding(ENCODING)
+    except Exception:
+        return len(text) // 4, "fallback"
+    return len(enc.encode(text)), "tiktoken"
+
+
+def read_input(args) -> str:
+    if args.stdin:
+        return sys.stdin.read()
+    with open(args.file, encoding="utf-8") as f:
+        return f.read()
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("file", nargs="?", help="path to the file to count")
+    p.add_argument("--stdin", action="store_true", help="read text from stdin instead of a file")
+    args = p.parse_args(argv)
+
+    if not args.stdin and not args.file:
+        p.error("provide a file path or --stdin")
+    if args.stdin and args.file:
+        p.error("provide either a file path or --stdin, not both")
+
+    text = read_input(args)
+    tokens, method = count_tokens(text)
+    print(json.dumps({"tokens": tokens, "method": method}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["tiktoken"]
+# ///
+"""prepass — the Analyze pre-pass for the agent builder.
+
+Reads an agent skill directory and emits one compact JSON object that every
+lens and the analyze orchestrator consume. The pre-pass does the one thing the
+lenses should not each redo: it classifies the agent along the three-point
+gradient (stateless, memory, autonomous), counts tokens for SKILL.md and every
+in-tree file, and sets the gate that turns the conditional sanctum lens on.
+
+Detection rests on the sanctum, the built agent's runtime memory at
+`{project-root}/_bmad/memory/{skillName}/`. An agent that reloads a sanctum on
+waking is a memory agent; one that also carries live wake behavior (a PULSE
+file or a pulse/autonomous wake reference with named-task routing) is
+autonomous; one with no sanctum at all is stateless. This is the BUILT agent's
+memory, never the builder's process log (.memlog.md), and the two are kept
+apart here.
+
+Lengths come from tokens, never line counts. The count uses count_tokens.py
+(imported as a sibling, then shelled out, then a chars // 4 fallback) so the
+metric matches the rest of the builder and runs under a bare python3.
+
+Output contract (one line of JSON on stdout, the pinned prepass shape):
+  {
+    "agent_type": "stateless" | "memory" | "autonomous",
+    "is_memory_agent": bool,           # true for memory and autonomous
+    "skill_md_tokens": int,
+    "files": [{"path": str, "tokens": int}, ...]
+  }
+
+Read-only over the target agent directory. It opens files to count and classify
+and writes nothing inside the agent tree.
+
+Usage:
+  prepass.py <agent-dir>     classify and count the agent at this directory
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+# Directories we never descend into while counting agent files.
+SKIP_DIRS = {".git", "__pycache__", ".pytest_cache", "node_modules", ".venv", "venv"}
+
+# Extensions we treat as countable text. Binary or opaque assets are skipped.
+TEXT_SUFFIXES = {
+    ".md", ".py", ".toml", ".yaml", ".yml", ".json", ".txt",
+    ".csv", ".html", ".sh", ".cfg", ".ini",
+}
+
+
+# --- token counting ---------------------------------------------------------
+
+def _count_via_import(text: str):
+    """Count tokens by importing the sibling count_tokens module."""
+    if str(SCRIPT_DIR) not in sys.path:
+        sys.path.insert(0, str(SCRIPT_DIR))
+    try:
+        import count_tokens  # type: ignore
+    except Exception:
+        return None
+    try:
+        tokens, _method = count_tokens.count_tokens(text)
+        return int(tokens)
+    except Exception:
+        return None
+
+
+def _count_via_shell(text: str):
+    """Count tokens by shelling out to count_tokens.py with text on stdin."""
+    script = SCRIPT_DIR / "count_tokens.py"
+    if not script.exists():
+        return None
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(script), "--stdin"],
+            input=text,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        return int(json.loads(proc.stdout)["tokens"])
+    except Exception:
+        return None
+
+
+def count_tokens(text: str) -> int:
+    """Token length of text via count_tokens.py, falling back to chars // 4.
+
+    Prefers importing the vendored count_tokens module, then shelling out to it,
+    then a bare character estimate so the pre-pass always produces a number.
+    """
+    for counter in (_count_via_import, _count_via_shell):
+        result = counter(text)
+        if result is not None:
+            return result
+    return len(text) // 4
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+# --- agent classification ---------------------------------------------------
+
+def iter_files(root: Path):
+    """Yield countable text files under root, skipping noise directories."""
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        if path.suffix.lower() in TEXT_SUFFIXES:
+            yield path
+
+
+def has_sanctum(root: Path, skill_text: str) -> bool:
+    """True when the agent reloads a runtime sanctum on waking (a memory agent).
+
+    The sanctum is the built agent's memory at `_bmad/memory/{skillName}/`. We
+    treat any of these as a sanctum signal: the SKILL referencing that memory
+    path, the Sacred-Truth / waking bootloader language, a wake or init-sanctum
+    scaffolder, or the sanctum template assets (PERSONA / CREED / BOND / MEMORY
+    / INDEX / CAPABILITIES). This is the built agent's memory, distinct from the
+    builder's .memlog.md, which is never a sanctum signal.
+    """
+    if re.search(r"_bmad/memory/", skill_text):
+        return True
+    if re.search(r"\bsanctum\b", skill_text, re.IGNORECASE):
+        return True
+    if "Sacred Truth" in skill_text and re.search(r"\b(waking|wake)\b", skill_text, re.IGNORECASE):
+        return True
+
+    for pattern in ("scripts/wake*", "scripts/init-sanctum*"):
+        for script in root.glob(pattern):
+            if script.is_file():
+                return True
+
+    sanctum_seed = re.compile(
+        r"^(PERSONA|CREED|BOND|MEMORY|INDEX|CAPABILITIES)-template\.md$"
+    )
+    assets = root / "assets"
+    if assets.is_dir():
+        for asset in assets.iterdir():
+            if asset.is_file() and sanctum_seed.match(asset.name):
+                return True
+    return False
+
+
+def has_autonomous_wake(root: Path, skill_text: str) -> bool:
+    """True when a memory agent also carries live autonomous wake behavior.
+
+    Autonomous is memory plus a PULSE-driven wake: a deployed PULSE.md, a
+    pulse/autonomous-wake reference, or SKILL wake routing (named-task pulse
+    routing, a default wake behavior, quiet hours, or a wake frequency).
+
+    The standard memory bootloader already names a Pulse Mode (`--pulse`) path
+    that loads PULSE.md, and ships a PULSE template asset, in every memory
+    agent. Those are seeds, not live wake behavior, so neither the bootloader's
+    Pulse-Mode line nor a PULSE template asset counts here. The wake behavior
+    must be deployed: a real PULSE.md, a wake reference file, or SKILL routing
+    that names tasks or schedules a recurring wake.
+    """
+    if (root / "PULSE.md").is_file():
+        return True
+
+    refs = root / "references"
+    if refs.is_dir():
+        for ref in refs.iterdir():
+            name = ref.name.lower()
+            if ref.is_file() and ("pulse-wake" in name or "autonomous-wake" in name):
+                return True
+
+    wake_signals = [
+        r"--pulse:\{",                    # named-task pulse routing
+        r"-p:\{",                          # short-flag named-task routing
+        r"default pulse wake",
+        r"default wake behavior",
+        r"\bquiet hours\b",
+        r"wake frequency",
+        r"autonomous wake",
+    ]
+    for pattern in wake_signals:
+        if re.search(pattern, skill_text, re.IGNORECASE):
+            return True
+    return False
+
+
+def classify(root: Path, skill_text: str) -> str:
+    """Return the agent_type along the gradient."""
+    if not has_sanctum(root, skill_text):
+        return "stateless"
+    if has_autonomous_wake(root, skill_text):
+        return "autonomous"
+    return "memory"
+
+
+# --- main -------------------------------------------------------------------
+
+def build_payload(root: Path) -> dict:
+    skill_path = root / "SKILL.md"
+    skill_text = read_text(skill_path) if skill_path.is_file() else ""
+
+    agent_type = classify(root, skill_text)
+    is_memory_agent = agent_type in ("memory", "autonomous")
+
+    files = []
+    skill_md_tokens = 0
+    for path in iter_files(root):
+        tokens = count_tokens(read_text(path))
+        rel = path.relative_to(root).as_posix()
+        files.append({"path": rel, "tokens": tokens})
+        if path == skill_path:
+            skill_md_tokens = tokens
+
+    return {
+        "agent_type": agent_type,
+        "is_memory_agent": is_memory_agent,
+        "skill_md_tokens": skill_md_tokens,
+        "files": files,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("agent_dir", help="path to the agent skill directory to analyze")
+    args = p.parse_args(argv)
+
+    root = Path(args.agent_dir).expanduser().resolve()
+    if not root.is_dir():
+        p.error(f"not a directory: {root}")
+
+    print(json.dumps(build_payload(root)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -5,6 +5,13 @@ 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.
+
+Any {if-X} or {/if-X} marker still present after processing is a defect (a
+malformed or mismatched block the emitted agent would ship verbatim): the
+script exits 3 and names the markers. Remaining {token} placeholders are
+reported in the --json metadata as tokens_remaining, not failed, because they
+may be runtime-resolution tokens such as {project-root} or {agent.<name>} —
+the builder judges that list against the build-time token set.
 """
 
 # /// script
@@ -160,6 +167,18 @@ def main() -> int:
     content, conds_true, conds_false = process_conditionals(content, true_conditions)
     content, vars_substituted = process_variables(content, variables)
 
+    # Leftover conditional markers mean a malformed/mismatched block that
+    # would ship verbatim in the emitted agent.
+    leftover_markers = sorted(set(re.findall(r'\{/?if-[a-zA-Z0-9_-]+\}', content)))
+    if leftover_markers:
+        print(
+            f"Error: leftover conditional markers after processing: {', '.join(leftover_markers)}",
+            file=sys.stderr,
+        )
+        return 3
+
+    tokens_remaining = sorted(set(re.findall(r'\{[a-zA-Z][a-zA-Z0-9_.-]*\}', content)))
+
     # Write output
     output_file = args.output
     try:
@@ -180,6 +199,7 @@ def main() -> int:
             'vars_substituted': vars_substituted,
             'conditions_true': conds_true,
             'conditions_false': conds_false,
+            'tokens_remaining': tokens_remaining,
         }
         print(json.dumps(metadata, indent=2), file=sys.stderr)