ma-agents 3.13.2 → 3.14.0

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

@@ -0,0 +1,59 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Customization surface for bmad-workflow-builder. This governs how the builder
+# builds: the org-wide context, standards, budgets, and gates applied to every
+# skill it produces. It is distinct from the per-built-skill customize.toml the
+# builder decides on during an individual build.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-workflow-builder.toml         (team)
+#   {project-root}/_bmad/custom/bmad-workflow-builder.user.toml    (personal)
+
+[workflow]
+
+# --- 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 greet, before the build/analyze loop begins.
+# Use for context-heavy setup once the user has been acknowledged.
+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).
+#   "Name the output consumer in every skill's overview."
+#   "file:{project-root}/_bmad/standards/skill-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 and budgets ---
+
+# Hard standards every BUILT skill 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).
+#   "Every skill must ship at least one eval case."
+#   "skill:acme-co:security-review"
+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. Set a directive to gate the
+# build on evals and to flag their absence during Analyze:
+#   "baseline"  -- require a passing baseline run (skill beats the bare model)
+#   "any"       -- require at least one eval case to exist and pass
+evals_required = ""
+
+# SKILL.md token budget, measured via scripts/count_tokens.py (cl100k_base).
+# Tiered: aim under _desired; between _desired and _budget warns the user; over
+# _budget is a hard finding the builder resolves by progressive disclosure
+# (lifting sections to references/ or assets/) until it is back under budget.
+skill_md_token_desired = 2000
+skill_md_token_budget = 3000

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# /// 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-workflow-builder/scripts/init_skill.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# ///
+"""init_skill — deterministic scaffolder for a new skill.
+
+Creates the skill directory and writes SKILL.md from the builder's template, which
+carries the embedded archetype guidance and the delete-when-done marker. The name
+is normalized to hyphen-case and capped at 64 chars. Only the resource directories
+the build flow asked for are stubbed, so the skill starts as small as it can. A
+customize.toml is emitted only when customization was accepted, never by default.
+
+This script does the mechanical scaffolding so the model spends its turns on the
+content, not on mkdir and string substitution.
+
+Usage:
+  init_skill.py --name "My New Skill" --dest /path/to/skills
+  init_skill.py --name foo --dest DIR --dirs references,scripts,assets
+  init_skill.py --name foo --dest DIR --customizable
+  init_skill.py --name foo --dest DIR \
+      --template /abs/SKILL-template.md --customize-template /abs/customize-template.toml
+
+Output: one JSON object on stdout describing what was created.
+Exit code 0 on success, 1 on failure (e.g. the target already exists).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+KNOWN_DIRS = ("references", "scripts", "assets", "agents")
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_TEMPLATE = SCRIPT_DIR.parent / "assets" / "SKILL-template.md"
+DEFAULT_CUSTOMIZE = SCRIPT_DIR.parent / "assets" / "customize-template.toml"
+
+
+def normalize_name(raw: str, max_len: int = 64) -> str:
+    """Lowercase, collapse non-alphanumerics to single hyphens, trim, cap at max_len."""
+    s = raw.strip().lower()
+    s = re.sub(r"[^a-z0-9]+", "-", s)
+    s = s.strip("-")
+    if len(s) > max_len:
+        s = s[:max_len].rstrip("-")
+    return s
+
+
+def fill_template(template: str, skill_name: str) -> str:
+    return template.replace("{skill-name}", skill_name)
+
+
+def scaffold(args) -> dict:
+    skill_name = normalize_name(args.name)
+    if not skill_name:
+        raise ValueError(f"name {args.name!r} normalized to an empty string")
+
+    skill_dir = Path(args.dest) / skill_name
+    if skill_dir.exists():
+        raise FileExistsError(f"{skill_dir} already exists")
+
+    template_path = Path(args.template) if args.template else DEFAULT_TEMPLATE
+    if not template_path.is_file():
+        raise FileNotFoundError(f"template not found: {template_path}")
+
+    requested = []
+    for d in (args.dirs or "").split(","):
+        d = d.strip()
+        if not d:
+            continue
+        if d not in KNOWN_DIRS:
+            raise ValueError(f"unknown resource dir {d!r}; known: {', '.join(KNOWN_DIRS)}")
+        requested.append(d)
+
+    skill_dir.mkdir(parents=True)
+    created = [str(skill_dir)]
+
+    skill_md = skill_dir / "SKILL.md"
+    skill_md.write_text(fill_template(template_path.read_text(encoding="utf-8"), skill_name), encoding="utf-8")
+    created.append(str(skill_md))
+
+    for d in requested:
+        sub = skill_dir / d
+        sub.mkdir()
+        created.append(str(sub))
+
+    customize_emitted = False
+    if args.customizable:
+        ct_path = Path(args.customize_template) if args.customize_template else DEFAULT_CUSTOMIZE
+        if not ct_path.is_file():
+            raise FileNotFoundError(f"customize template not found: {ct_path}")
+        target = skill_dir / "customize.toml"
+        target.write_text(
+            ct_path.read_text(encoding="utf-8").replace("{skill-name}", skill_name),
+            encoding="utf-8",
+        )
+        created.append(str(target))
+        customize_emitted = True
+
+    return {
+        "ok": True,
+        "skill_name": skill_name,
+        "skill_dir": str(skill_dir),
+        "dirs_stubbed": requested,
+        "customize_toml": customize_emitted,
+        "created": created,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Deterministic scaffolder for a new skill")
+    p.add_argument("--name", required=True, help="raw skill name; normalized to hyphen-case <=64")
+    p.add_argument("--dest", required=True, help="parent directory the skill folder is created under")
+    p.add_argument("--dirs", default="", help="comma-separated resource dirs to stub (references,scripts,assets,agents)")
+    p.add_argument("--customizable", action="store_true", help="emit customize.toml (only when customization was accepted)")
+    p.add_argument("--template", help="override path to the SKILL.md template")
+    p.add_argument("--customize-template", help="override path to the customize.toml template")
+    args = p.parse_args(argv)
+
+    try:
+        result = scaffold(args)
+    except (FileExistsError, FileNotFoundError, ValueError) as e:
+        print(json.dumps({"ok": False, "error": str(e)}))
+        return 1
+
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())