bmad-method 6.10.1-next.2 → 6.10.1-next.21

package/src/bmm-skills/4-implementation/bmad-quick-dev/render.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""render.py — bmad-quick-dev template renderer.
+
+Resolves compile-time {{.variable}} placeholders from BMad's central config,
+bakes absolute paths for {project-root} into derived values, resolves and
+inlines the skill's [workflow] customization block, and writes rendered .md
+files to {project-root}/_bmad/render/bmad-quick-dev/.
+
+Config: four-layer merge of _bmad/config.toml + config.user.toml +
+custom/config.toml + custom/config.user.toml (post-#2285 installs).
+Keys surface from [core] and [modules.bmm]. Missing or unparseable
+config.toml → HALT. A {{.var}} referenced by this skill's .md sources but
+absent from the merged config → HALT (never a silent empty substitution).
+Optional layers may be missing, but one that exists and cannot be parsed
+or read → HALT.
+
+Customization: three-layer merge of {skill}/customize.toml +
+_bmad/custom/bmad-quick-dev.toml + .user.toml (same structural rules as
+resolve_customization.py). The resolved [workflow] values fill {workflow.*}
+placeholders, so this skill needs no runtime resolve_customization.py call.
+Other single-curly placeholders ({project-root}, {spec_file}, {skill-root},
+...) pass through untouched for the LLM to resolve during workflow execution.
+
+Every invocation rebuilds from scratch — no hash, no cache.
+Python 3.11+ stdlib only. UTF-8 I/O.
+"""
+
+import os
+import posixpath
+import re
+import sys
+import tomllib
+
+
+def find_project_root():
+    """Walk up from cwd until a _bmad/ directory is found. On failure, print a
+    HALT instruction to stdout and exit non-zero."""
+    current = os.path.abspath(os.getcwd())
+    while True:
+        candidate = os.path.join(current, "_bmad")
+        if os.path.isdir(candidate):
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            print(
+                f"HALT and report to the user: no _bmad/ directory found walking up from {os.getcwd()}"
+            )
+            sys.exit(1)
+        current = parent
+
+
+def load_toml(path, required=False):
+    """Load a TOML file. Only absence is negotiable: a missing optional file
+    returns {} (customization layers are optional), a missing required file
+    HALTs. A file that exists but cannot be parsed or read always HALTs —
+    stdout is how this script signals workflow halts to its LLM caller — the
+    user wrote it to be honored, and silently continuing with {} would discard
+    their customizations with no failure signal."""
+    if not os.path.isfile(path):
+        if required:
+            print(
+                f"HALT and report to the user: required config file not found: {path} — "
+                "ensure this is a post-#2285 BMAD install"
+            )
+            sys.exit(1)
+        return {}
+    try:
+        with open(path, "rb") as fh:
+            parsed = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as error:
+        print(f"HALT and report to the user: failed to parse {path}: {error}")
+        sys.exit(1)
+    except OSError as error:
+        print(f"HALT and report to the user: failed to read {path}: {error}")
+        sys.exit(1)
+    if not isinstance(parsed, dict):
+        return {}
+    return parsed
+
+
+def _deep_merge(base, override):
+    """Dict-aware deep merge. Lists and scalars: override wins (we don't need
+    the full keyed-merge semantics of resolve_config.py — quick-dev only reads
+    flat scalars out of [core] and [modules.bmm])."""
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, value in override.items():
+            result[key] = _deep_merge(result[key], value) if key in result else value
+        return result
+    return override
+
+
+def _detect_keyed_merge_field(items):
+    """Return 'code' or 'id' if every table item carries that same field.
+    Mixed or partial arrays return None and fall through to append."""
+    if not items or not all(isinstance(item, dict) for item in items):
+        return None
+    for candidate in ("code", "id"):
+        if all(item.get(candidate) is not None for item in items):
+            return candidate
+    return None
+
+
+def _merge_by_key(base, override, key_name):
+    result = []
+    index_by_key = {}
+    for item in base:
+        if not isinstance(item, dict):
+            continue
+        if item.get(key_name) is not None:
+            index_by_key[item[key_name]] = len(result)
+        result.append(dict(item))
+    for item in override:
+        if not isinstance(item, dict):
+            result.append(item)
+            continue
+        key = item.get(key_name)
+        if key is not None and key in index_by_key:
+            result[index_by_key[key]] = dict(item)
+        else:
+            if key is not None:
+                index_by_key[key] = len(result)
+            result.append(dict(item))
+    return result
+
+
+def _merge_arrays(base, override):
+    """Shape-aware array merge: keyed merge if every item has code/id, else append."""
+    base_arr = base if isinstance(base, list) else []
+    override_arr = override if isinstance(override, list) else []
+    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
+    if keyed_field:
+        return _merge_by_key(base_arr, override_arr, keyed_field)
+    return base_arr + override_arr
+
+
+def _structural_merge(base, override):
+    """Faithful port of resolve_customization.py's deep_merge: tables deep-merge,
+    arrays-of-tables keyed by code/id replace-then-append (other arrays append),
+    scalars override. Used only for the [workflow] customization layers — the
+    central-config path keeps its own simpler _deep_merge. Duplicated rather than
+    imported to keep this skill self-contained."""
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, over_val in override.items():
+            result[key] = (
+                _structural_merge(result[key], over_val) if key in result else over_val
+            )
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
+
+
+def resolve_workflow(root, skill_dir, skill_name):
+    """Resolve the [workflow] customization block via the three-layer merge
+    (skill defaults -> team -> user), highest priority last. Same structural
+    rules as resolve_customization.py. All three layers are optional: a missing
+    file is skipped, but an unparseable one HALTs (via load_toml)."""
+    defaults = load_toml(posixpath.join(skill_dir, "customize.toml"))
+    custom_dir = posixpath.join(root, "_bmad", "custom")
+    team = load_toml(posixpath.join(custom_dir, f"{skill_name}.toml"))
+    user = load_toml(posixpath.join(custom_dir, f"{skill_name}.user.toml"))
+    merged = _structural_merge(defaults, team)
+    merged = _structural_merge(merged, user)
+    workflow = merged.get("workflow")
+    return workflow if isinstance(workflow, dict) else {}
+
+
+def load_central_config(root):
+    """Four-layer merge of _bmad/config.toml and its peers (highest priority
+    last). HALTs if the base _bmad/config.toml is missing or unparseable."""
+    bmad_dir = posixpath.join(root, "_bmad")
+    base_team = load_toml(posixpath.join(bmad_dir, "config.toml"), required=True)
+    base_user = load_toml(posixpath.join(bmad_dir, "config.user.toml"))
+    custom_team = load_toml(posixpath.join(bmad_dir, "custom", "config.toml"))
+    custom_user = load_toml(posixpath.join(bmad_dir, "custom", "config.user.toml"))
+
+    merged = _deep_merge(base_team, base_user)
+    merged = _deep_merge(merged, custom_team)
+    merged = _deep_merge(merged, custom_user)
+    return merged
+
+
+def flatten_central_config(merged):
+    """Lift scalar keys from [core] and [modules.bmm] into a single namespace.
+    Module keys take precedence on collision (installer strips core keys from
+    module buckets, so collisions shouldn't happen in practice)."""
+    flat = {}
+    modules = merged.get("modules")
+    modules = modules if isinstance(modules, dict) else {}
+    for section in (merged.get("core"), modules.get("bmm")):
+        if not isinstance(section, dict):
+            continue
+        for key, value in section.items():
+            if isinstance(value, bool):
+                flat[key] = "true" if value else "false"
+            elif isinstance(value, (str, int, float)):
+                flat[key] = str(value)
+    return flat
+
+
+def render_template(content, vars_):
+    """Resolve {{.var}} substitutions. Unresolved references emit an empty string,
+    but main() HALTs on any missing reference before rendering starts, so this
+    fallback never fires in practice."""
+    return re.sub(r"\{\{\.(\w+)\}\}", lambda m: vars_.get(m.group(1), ""), content)
+
+
+def collect_missing_vars(sources, vars_):
+    """Map each {{.var}} name referenced by the source .md files but absent from
+    the merged config to the files that reference it. A missing key must HALT:
+    missingkey=zero rendering would bake a corrupted workflow (empty paths,
+    blank language lines) with no failure signal."""
+    missing = {}
+    for fname, content in sources:
+        for name in re.findall(r"\{\{\.(\w+)\}\}", content):
+            if name not in vars_:
+                files = missing.setdefault(name, [])
+                if fname not in files:
+                    files.append(fname)
+    return missing
+
+
+def _scalar_str(value):
+    """Stringify a scalar for inline rendering: booleans lowercase (matching
+    BMad config conventions), None as empty, everything else via str()."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+# [workflow] keys holding review layers ([[workflow.review_layers]] tables with
+# id/name/instruction/when fields). This renderer knows this skill's
+# customization schema outright — layer semantics are materialized here, not
+# interpreted by the LLM at run time.
+_REVIEW_LAYER_KEYS = ("review_layers", "oneshot_review_layers")
+
+
+def _render_review_layers(layers):
+    """Materialize review layers into direct invocation blocks. A layer with an
+    empty or missing instruction is disabled (that is how an override turns off
+    a default layer) and drops out entirely. A `when` condition is the one part
+    that stays with the LLM: it renders as a run-time guard line. No active
+    layers renders as the HALT instruction the workflow would otherwise have to
+    derive from an empty list."""
+    active = [
+        layer
+        for layer in layers
+        if isinstance(layer, dict) and _scalar_str(layer.get("instruction")).strip()
+    ]
+    if not active:
+        return (
+            "No review layers are active. HALT with status `blocked` and "
+            "blocking condition `no active review layers`."
+        )
+    blocks = []
+    for layer in active:
+        title = (
+            _scalar_str(layer.get("name")).strip()
+            or _scalar_str(layer.get("id")).strip()
+            or "Review layer"
+        )
+        lines = [f"#### {title}", ""]
+        when = _scalar_str(layer.get("when")).strip()
+        if when:
+            lines.append(
+                "Run this layer only if the following holds in the "
+                f"current context: `{when}`"
+            )
+            lines.append("")
+        lines.append(_scalar_str(layer.get("instruction")).strip("\n"))
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _render_workflow_value(key, value):
+    """Format a resolved [workflow] value for inline substitution. Review-layer
+    keys materialize as invocation blocks; other lists render as markdown
+    bullets (empty -> '_None._'); scalars render verbatim. Each list item uses
+    the same scalar formatting so booleans stay consistent. Entries are emitted
+    as-is so runtime placeholders like {project-root} or {diff_output} survive
+    for the LLM to resolve."""
+    if key in _REVIEW_LAYER_KEYS and isinstance(value, list):
+        return _render_review_layers(value)
+    if isinstance(value, list):
+        if not value:
+            return "_None._"
+        return "\n".join(f"- {_scalar_str(item)}" for item in value)
+    return _scalar_str(value)
+
+
+def render_workflow(content, workflow):
+    """Resolve {workflow.<key>} placeholders from the resolved [workflow] block.
+    Unknown keys emit an empty string (missingkey=zero, matching render_template).
+    Distinct regex from render_template so single-curly runtime placeholders
+    elsewhere are untouched."""
+    return re.sub(
+        r"\{workflow\.(\w+)\}",
+        lambda m: _render_workflow_value(m.group(1), workflow.get(m.group(1))),
+        content,
+    )
+
+
+def main():
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    skill_name = os.path.basename(script_dir)
+    root = find_project_root()
+    root = root.replace(os.sep, "/")
+
+    vars_ = flatten_central_config(load_central_config(root))
+
+    for key in list(vars_.keys()):
+        vars_[key] = vars_[key].replace("{project-root}", root)
+
+    vars_["project_root"] = root
+
+    # Guarded ahead of the general missing-vars scan: sprint_status and
+    # deferred_work_file derive from it below, and unlike the scan (absent
+    # keys only) this also HALTs on a present-but-empty value.
+    implementation_artifacts = vars_.get("implementation_artifacts", "").strip()
+    if not implementation_artifacts:
+        print(
+            "HALT and report to the user: config is missing `implementation_artifacts` "
+            "(expected under [core] or [modules.bmm] in _bmad/config.toml)"
+        )
+        sys.exit(1)
+
+    vars_["sprint_status"] = posixpath.join(
+        implementation_artifacts, "sprint-status.yaml"
+    )
+    vars_["deferred_work_file"] = posixpath.join(
+        implementation_artifacts, "deferred-work.md"
+    )
+
+    sources = []
+    for fname in sorted(os.listdir(script_dir)):
+        if not fname.endswith(".md") or fname == "SKILL.md":
+            continue
+        with open(
+            posixpath.join(script_dir, fname), "r", encoding="utf-8", newline=""
+        ) as fh:
+            sources.append((fname, fh.read()))
+
+    missing = collect_missing_vars(sources, vars_)
+    if missing:
+        details = "; ".join(
+            f"`{name}` (referenced by {', '.join(files)})"
+            for name, files in sorted(missing.items())
+        )
+        print(
+            f"HALT and report to the user: config is missing {details} "
+            "(expected under [core] or [modules.bmm] in _bmad/config.toml)"
+        )
+        sys.exit(1)
+
+    workflow = resolve_workflow(root, script_dir.replace(os.sep, "/"), skill_name)
+
+    out_dir = posixpath.join(root, "_bmad", "render", skill_name)
+    os.makedirs(out_dir, exist_ok=True)
+
+    for fname in os.listdir(out_dir):
+        if fname.endswith(".md"):
+            os.remove(posixpath.join(out_dir, fname))
+
+    for fname, content in sources:
+        dst = posixpath.join(out_dir, fname)
+        with open(dst, "w", encoding="utf-8", newline="") as fh:
+            fh.write(render_workflow(render_template(content, vars_), workflow))
+
+    workflow_md = posixpath.join(out_dir, "workflow.md")
+    print(f"read and follow {workflow_md}")
+
+
+if __name__ == "__main__":
+    main()

package/src/bmm-skills/4-implementation/bmad-quick-dev/spec-template.md

@@ -46,10 +46,10 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 
 ## Code Map
 
-<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+<!-- Agent-populated during planning: the distilled investigation map, so the spec carries what exploration found and the implementation handoff need only point here. Annotated paths prevent blind codebase searching. Entries may drill to symbol/line and carry reuse pointers ("mirror X at FILE:LINE") or read-only evidence, where they save the implementer a search. -->
 
 - `FILE` -- ROLE_OR_RELEVANCE
-- `FILE` -- ROLE_OR_RELEVANCE
+- `FILE:LINE` -- ROLE_OR_RELEVANCE; reuse pointer or READ-ONLY evidence when relevant
 
 ## Tasks & Acceptance
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -1,5 +1,4 @@
 ---
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for both routes before leaving this step
 story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
 ---
@@ -8,7 +7,7 @@ story_key: '' # set at runtime to the current story's full sprint-status key (e.
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - The prompt that triggered this workflow IS the intent — not a hint.
 - Do NOT assume you start from zero.
 - The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
@@ -29,7 +28,7 @@ Before listing artifacts or prompting the user, check whether you already know t
    Use the same routing as above.
 
 3. Otherwise — scan artifacts and ask
-   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{{.implementation_artifacts}}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
      - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
      - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
      - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
@@ -39,14 +38,14 @@ Never ask extra questions if you already understand what the user intends.
 
 ### Story-key resolution
 
-This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset.
+This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `epic_num` and `story_num`. If the spec is not an epic story, skip silently and leave `story_key` unset.
 
-If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
+If the spec is an epic story and `{{.sprint_status}}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `story_key` to that full key. Zero or multiple matches → leave `story_key` unset (warn on multiple).
 
 ## INSTRUCTIONS
 
 1. Load context.
-   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
+   - List files in `{{.planning_artifacts}}` and `{{.implementation_artifacts}}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
    - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
 
@@ -54,17 +53,17 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
 
      1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
 
-     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+     2. **Check for a valid cached epic context.** Look for `{{.implementation_artifacts}}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{{.planning_artifacts}}` is newer.
         - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
         - **If missing, empty, or invalid:** continue to step 3.
 
-     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-        - **Preferred — subagent:** spawn a subagent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+     3. **Compile epic context.** Produce `{{.implementation_artifacts}}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+        - **Preferred — subagent:** spawn a subagent synchronously (wait for it to return in this turn) with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{{.planning_artifacts}}` directory, and the output path `{{.implementation_artifacts}}/epic-<N>-context.md`.
         - **Fallback — inline** (for runtimes without subagent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn subagents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
 
      4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
 
-     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{{.implementation_artifacts}}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
 
      6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
 
@@ -82,7 +81,7 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
    - Present detected distinct goals as a bullet list.
    - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
    - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: For each deferred goal, append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **S**: For each deferred goal, append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
      ```markdown
      - source_spec: none
        summary: <one sentence naming the deferred goal>
@@ -91,7 +90,7 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 
-   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
 
    **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
 
@@ -99,7 +98,6 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
 
    **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
 
-
 ## NEXT
 
 Read fully and follow `./step-02-plan.md`

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -1,25 +1,21 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step 2: Plan
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - No intermediate approvals.
 
 ## INSTRUCTIONS
 
 1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
-2. Investigate codebase. _Isolate deep exploration in subagents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
-3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+2. Investigate codebase. _Isolate deep exploration in synchronous subagents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ Decide which findings actually matter for execution — the specific files, symbols/lines, reuse points, and read-only constraints — and carry those forward for the Code Map. This is where the investigation lands: the spec preserves it so it is never re-narrated to the implementer at dispatch time.
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. Drain the investigation into the `## Code Map` section — annotated paths, symbol/line anchors, reuse pointers, and read-only evidence — so the spec is the implementer's investigation map and the step-03 handoff need only point at it. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`, before writing. Write the result to `{spec_file}`.
 4. Self-review against READY FOR DEVELOPMENT standard.
 5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
 6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
    - Show user the token count.
    - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
-   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence naming the deferred goal>
@@ -46,7 +42,6 @@ HALT and ask human: `[A] Approve` | `[E] Edit`
   - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
 - **E**: Apply changes, then return to CHECKPOINT 1.
 
-
 ## NEXT
 
 Read fully and follow `./step-03-implement.md`

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - No push. No remote ops.
 - Sequential execution only.
 - Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
@@ -24,11 +24,15 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
 
 Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
 
-Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
+Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
 
-If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a subagent, include them in the subagent prompt so it has access to the referenced context.
+Execute the implementation handoff below: substitute the runtime placeholders (e.g. `{spec_file}`) into it, then follow it verbatim.
 
-Hand `{spec_file}` to a subagent/task and let it implement. If no subagents are available, implement directly.
+{workflow.implementation_handoff}
+
+Do not add goal restatements, file lists, ownership boundaries, investigation detail, acceptance criteria, or CLAUDE.md/house-style rules to the dispatch — the spec is the subagent's sole source of truth, and that material already lives in it (investigation findings in its Code Map, the rest in the spec body). One line of sanctioned hedging belongs in the spec at planning time, not in the dispatch. If no subagents are available, implement directly from the spec. If the platform allows, keep the subagent available for re-engagement after it returns — step-04 may send it review fixes.
+
+The handoff directs the subagent to load the spec's `context:` files itself, so never pre-load and paste those files into the dispatch. Only when you implement directly (no subagent available) do you load a non-empty `context:` list yourself before starting.
 
 **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
 
@@ -36,6 +40,10 @@ Hand `{spec_file}` to a subagent/task and let it implement. If no subagents are
 
 Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete and every acceptance criterion is satisfied. Mark each finished task `[x]`. If any task is not done or any acceptance criterion is not satisfied, finish the missing work before proceeding.
 
+### Matrix Test Audit
+
+If `{spec_file}`'s `<frozen-after-approval>` block contains an I/O & Edge-Case Matrix, verify every matrix row is covered by at least one test that verifies its expected behavior, and that each covering test ran and passed in the verification output. A covering test that exists but did not run — unregistered, filtered out, skipped, or disabled — counts as missing. If a test disagrees with the matrix, never edit the expectation to match the code: fix the code, or if the matrix row itself is ambiguous, HALT and ask the human. Fix any other audit failure before proceeding.
+
 ## NEXT
 
 Read fully and follow `./step-04-review.md`

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -1,13 +1,10 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step 4: Review
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - All review subagents must run at the same model capability as the current session.
+- Run subagents synchronously: launch them together, then wait for all results before continuing.
 
 ## INSTRUCTIONS
 
@@ -21,20 +18,11 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch Blind Hunter, Edge Case Hunter, and Verification Gap Reviewer in parallel without prior conversation context. If no subagents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Execute these review layers in parallel wherever their execution methods allow: substitute the runtime placeholders (e.g. `{diff_output}`) into each layer's instruction, then follow it verbatim. Parallel means several blocking calls awaited together in this turn — never backgrounded or detached, never ending the turn to await results. When running layers as subagents, spawn every reviewer before reading or reacting to any of their output; begin collection and triage only once all are launched.
+
+{workflow.review_layers}
 
-- **Blind Hunter** — prompt:
-  > Invoke the `bmad-review-adversarial-general` skill on this diff:
-  >
-  > {diff_output}
-- **Edge Case Hunter** — prompt:
-  > Invoke the `bmad-review-edge-case-hunter` skill on this diff:
-  >
-  > {diff_output}
-- **Verification Gap Reviewer** — prompt:
-  > Invoke the `bmad-review-verification-gap` skill on this diff:
-  >
-  > {diff_output}
+If a layer's instruction requires subagents and none are available, generate one review prompt file per such layer in `{{.implementation_artifacts}}` and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
 ### Classify
 
@@ -53,8 +41,8 @@ Launch Blind Hunter, Edge Case Hunter, and Verification Gap Reviewer in parallel
 4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
    - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
    - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
-   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
-   - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks. If the step-03 implementation subagent can be re-engaged with its context intact, send it all patch findings in one synchronous message — for each: the file, what is wrong, and what the fix must do. If it cannot be re-engaged, apply the patches yourself. Then re-run the checks in `{spec_file}`'s `## Verification` section, if present; if verification fails and the failure cannot be fixed, HALT and escalate to the human.
+   - **defer** — Append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence>

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - NEVER auto-push.
 
 ## INSTRUCTIONS
@@ -52,7 +52,7 @@ When there is only one concern, omit the bold label — just list the stops dire
 
 Change `{spec_file}` status to `done` in the frontmatter.
 
-Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+Follow `./sync-sprint-status.md` with `target_status` = `review`.
 
 ### Commit and Open
 
@@ -73,6 +73,6 @@ Workflow complete.
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
 
-If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
+{workflow.on_complete}