ma-agents 3.13.2 → 3.14.1

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

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Tests for scripts/render_report.py — the deterministic report renderer.
+
+Covers: valid island injection, refusal on malformed JSON, refusal on the
+placeholder subject, the --md archival rendering, and that both shipped
+shells carry a parseable placeholder island.
+Run with: python3 -m pytest test_render_report.py
+(or plain `python3 test_render_report.py` for a lightweight self-check).
+"""
+import json
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+SKILLS_DIR = Path(__file__).resolve().parents[3]
+SCRIPT = SKILLS_DIR / "bmad-workflow-builder" / "scripts" / "render_report.py"
+SHELLS = [
+    SKILLS_DIR / "bmad-workflow-builder" / "assets" / "report-shell.html",
+    SKILLS_DIR / "bmad-agent-builder" / "assets" / "report-shell.html",
+]
+ISLAND_RE = re.compile(
+    r'<script[^>]*\bid="report-data"[^>]*>(.*?)</script>', re.DOTALL
+)
+
+VALID_DATA = {
+    "schema_version": 2,
+    "subject": "skills/example-skill",
+    "generated": "2026-06-10",
+    "verdict": "One ceremony section; otherwise sound.",
+    "grade": "good",
+    "summary": "Solid structure and clean wiring. The main opportunity is one over-scripted reference.",
+    "standards": {
+        "canon": "/abs/skills/bmad-workflow-builder/references/prompt-quality-canon.md",
+        "principles": "/abs/skills/bmad-workflow-builder/references/skill-quality-principles.md",
+        "scripts": "/abs/skills/bmad-workflow-builder/references/script-standards.md",
+    },
+    "themes": [
+        {
+            "title": "Scripted sequences where goals suffice",
+            "root_cause": "Steps are numbered without true ordering dependencies.",
+            "finding_ids": ["leanness-1"],
+            "action": "Replace ordered lists with goal sentences.",
+        }
+    ],
+    "strengths": ["Frontmatter and routing map are exemplary."],
+    "recommendations": [
+        {"rank": 1, "action": "De-script the finalize section.", "resolves": ["leanness-1"]}
+    ],
+    "findings": [
+        {
+            "id": "leanness-1",
+            "lens": "leanness",
+            "severity": "high",
+            "title": "Numbered finalize steps are decoration",
+            "location": "references/build-process.md:finalize",
+            "evidence": "No step depends on a prior step's output.",
+            "recommendation": "Replace with a single goal sentence.",
+        }
+    ],
+}
+
+
+def run_render(args):
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), *[str(a) for a in args]],
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_valid_island_injection():
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        findings = tmp / "findings.json"
+        out = tmp / "report.html"
+        findings.write_text(json.dumps(VALID_DATA), encoding="utf-8")
+
+        result = run_render([findings, "--shell", SHELLS[0], "-o", out])
+        assert result.returncode == 0, result.stderr
+        html = out.read_text(encoding="utf-8")
+
+        match = ISLAND_RE.search(html)
+        assert match, "rendered HTML has no report-data island"
+        island = json.loads(match.group(1))
+        assert island["subject"] == "skills/example-skill"
+        assert island["findings"][0]["id"] == "leanness-1"
+        assert island["standards"]["canon"].endswith("prompt-quality-canon.md")
+        assert "__PLACEHOLDER__" not in match.group(1)
+
+        stdout = json.loads(result.stdout)
+        assert stdout["counts"] == {"critical": 0, "high": 1, "medium": 0, "low": 0}
+        assert stdout["grade"] == "good"
+
+
+def test_refuses_bad_json():
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        findings = tmp / "findings.json"
+        out = tmp / "report.html"
+        findings.write_text("{ this is not json", encoding="utf-8")
+
+        result = run_render([findings, "--shell", SHELLS[0], "-o", out])
+        assert result.returncode != 0
+        assert "not valid JSON" in result.stderr
+        assert not out.exists(), "refused render must not write output"
+
+
+def test_refuses_placeholder_subject():
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        findings = tmp / "findings.json"
+        out = tmp / "report.html"
+        data = dict(VALID_DATA, subject="__PLACEHOLDER__")
+        findings.write_text(json.dumps(data), encoding="utf-8")
+
+        result = run_render([findings, "--shell", SHELLS[0], "-o", out])
+        assert result.returncode != 0
+        assert "placeholder" in result.stderr.lower()
+        assert not out.exists(), "refused render must not write output"
+
+
+def test_md_output():
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+        findings = tmp / "findings.json"
+        out = tmp / "report.html"
+        md = tmp / "report.md"
+        findings.write_text(json.dumps(VALID_DATA), encoding="utf-8")
+
+        result = run_render([findings, "--shell", SHELLS[0], "-o", out, "--md", md])
+        assert result.returncode == 0, result.stderr
+        text = md.read_text(encoding="utf-8")
+        assert "# Analysis Report: skills/example-skill" in text
+        assert "**Grade: Good**" in text
+        assert "## Themes" in text
+        assert "Scripted sequences where goals suffice" in text
+        assert "## Strengths" in text
+        assert "## Recommendations" in text
+        assert "### High (1)" in text
+        assert "leanness-1" in text
+
+
+def test_shipped_shells_carry_placeholder_island():
+    for shell in SHELLS:
+        match = ISLAND_RE.search(shell.read_text(encoding="utf-8"))
+        assert match, f"{shell} has no report-data island"
+        island = json.loads(match.group(1))
+        assert island["subject"] == "__PLACEHOLDER__", (
+            f"{shell} ships a non-placeholder island; a failed injection "
+            "would show its contents as real findings"
+        )
+        assert island["findings"] == []
+
+
+def test_render_script_copies_identical():
+    other = SKILLS_DIR / "bmad-agent-builder" / "scripts" / "render_report.py"
+    assert SCRIPT.read_bytes() == other.read_bytes(), (
+        "render_report.py copies have drifted between the two builder skills"
+    )
+
+
+if __name__ == "__main__":
+    test_valid_island_injection()
+    test_refuses_bad_json()
+    test_refuses_placeholder_subject()
+    test_md_output()
+    test_shipped_shells_carry_placeholder_island()
+    test_render_script_copies_identical()
+    print("ok: render_report tests passed")

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

@@ -1,6 +1,6 @@
 {
-  "generated": "2026-06-13T15:11:45.601Z",
-  "bmadMethodVersion": "6.8.0",
+  "generated": "2026-06-27T14:28:18.113Z",
+  "bmadMethodVersion": "6.9.0",
   "registrySchema": "package-root-v68",
   "modules": {
     "tea": {
@@ -12,8 +12,8 @@
     "bmb": {
       "url": "https://github.com/bmad-code-org/bmad-builder",
       "branch": "main",
-      "commitSha": "7cfa7711778f04c5df56f7ae895fabc942fd920c",
-      "clonedAt": "2026-06-13T15:11:41.069Z"
+      "commitSha": "e6935f2776c34ffd9b18f4ef1e334584ef10a50f",
+      "clonedAt": "2026-06-27T14:28:16.693Z"
     },
     "cis": {
       "url": "https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite",

package/lib/bmad-customize/bmm-qa.customize.yaml

@@ -1,9 +1,9 @@
-# MA-AGENTS: Gad — Software Quality Assurance Expert
+# MA-AGENTS: Gadi — Software Quality Assurance Expert
 phase: planning
 on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
 agent:
   metadata:
-    name: "Gad"
+    name: "Gadi"
 
 persona:
   role: "Software Quality Assurance Engineer responsible for verifying project quality across all dimensions — code, process, documentation, and delivery."
@@ -17,7 +17,7 @@ persona:
 
 menu:
   - trigger: skill:ma-agent-sqa
-    description: "Activate Gad — Software Quality Assurance Expert"
+    description: "Activate Gadi — Software Quality Assurance Expert"
 
 critical_actions:
   - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"

package/lib/bmad-extension/.claude-plugin/marketplace.json.template

@@ -11,7 +11,7 @@
   "owner": {
     "name": "Alon Mayaffit"
   },
-  "description": "ma-agents BMAD extension — enterprise SDLC personas (Yael, Amit, Alex, Demerzel, Gad) plus MIL-STD-498, SRE, DevOps, Cyber, ML, and SQA workflow skills.",
+  "description": "ma-agents BMAD extension — enterprise SDLC personas (Yael, Amit, Alex, Demerzel, Gadi) plus MIL-STD-498, SRE, DevOps, Cyber, ML, and SQA workflow skills.",
   "license": "MIT",
   "homepage": "https://github.com/mayafit/AI_Agents",
   "repository": "https://github.com/mayafit/AI_Agents",
@@ -39,7 +39,7 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.8.0",
+  "bmad_min_version": "6.9.0",
   "plugins": [
     {
       "name": "ma-skills",
@@ -99,6 +99,7 @@
         "./skills/ml-techspec",
         "./skills/add-sprint",
         "./skills/add-to-sprint",
+        "./skills/bmad-dev-epic",
         "./skills/bmad-dev-story",
         "./skills/bmad-sprint-planning",
         "./skills/bmad-sprint-status",

package/lib/bmad-extension/skills/bmad-dev-epic/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: bmad-dev-epic
+description: 'Orchestrate a full epic end-to-end with parallel subagents — per-story create/dev/review/edge-case/fix/e2e pipeline, dependency-aware waves, configurable model tiers, an epic-level adversarial + package-integrity gate, and gated beta publish + PR. Use when the user says "run the epic", "dev epic [id]", or "orchestrate epic development".'
+---
+
+# Epic Orchestrator Workflow
+
+**Goal:** Drive an already-planned epic from stories to a review-ready epic PR, autonomously, by orchestrating BMAD skills across parallel subagents under a strict, repeatable process.
+
+**Your Role:** You are the Epic Orchestrator. You do not write story code yourself — you decompose the epic into dependency-ordered waves, spawn subagents that each run a disciplined per-story pipeline, enforce a Definition of Done before any merge, run an epic-level adversarial + package-integrity gate, and stop at the two human gates (publish, PR). You are precise about git isolation, model tiers, and failure handling. No noise, no filler.
+
+## Conventions
+
+- Bare paths (e.g. `checklist.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename (`bmad-dev-epic`).
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+- ALWAYS speak in the config `{communication_language}`.
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`. State plainly what this skill will do (run an entire epic through parallel subagents) and that it runs unattended through dev + review, requiring your **approval at only two release gates** — before publishing the beta package and before opening the epic PR. (It will still HALT for genuine blockers, e.g. a missing/unready epic or a dependency cycle.)
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have completed.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly.
+- **Just-In-Time Loading**: Only load the current step file.
+- **Sequential Enforcement**: Complete steps in order, no skipping.
+- **State Tracking**: Persist progress in an in-memory **Run Ledger** (see below) and mirror it to `{implementation_artifacts}/epic-runs/<epic-id>/run-ledger.md` so a resumed run can recover.
+
+### The Run Ledger
+
+Maintain a single source of truth for the run with, per story: `id`, `wave`, `status` (`pending` → `in-progress` → `review` → `fixing` → `e2e` → `merged` → `blocked`), `worktree`, `branch`, `fix_rounds_used`, and a short note. Update it at every state transition and after every subagent returns.
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting.
+2. **FOLLOW SEQUENCE**: Execute sections in order.
+3. **HONOR GATES**: Halt only at the two declared human gates (publish, PR) and wherever a step says HALT.
+4. **LOAD NEXT**: When directed, read fully and follow the next step file.
+
+### Git discipline (defer to `git-workflow-skill`)
+
+**`git-workflow-skill` is the single authority for every git operation in this run** — worktree creation, branch naming, conventional commits, hooks, rebasing, PR creation, and cleanup. Do not hand-roll git flows that contradict it. Load and follow it.
+
+This epic uses a **nested-branch topology** (epic branch off the trunk; story branches off the epic branch; stories merge back to the epic branch; one PR to the trunk). Where that diverges from the skill's script defaults — chiefly the scripts' `dev` base assumption and their auto-PR-to-`dev` — use the skill's documented **manual equivalents** with the base overridden as the step specifies (trunk for the epic branch, the epic branch for stories). Everything else (worktree-per-unit-of-work, conventional commits, hook compliance, worktree cleanup) is used exactly as the skill defines it.
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously.
+- **NEVER** perform any git action outside the `git-workflow-skill` conventions. The trunk (`main`) is never committed to or modified directly; all file-writing happens inside a worktree on a feature branch.
+- **NEVER** publish to npm or open the epic PR without explicit user confirmation at the gate.
+- **NEVER** treat the known pre-existing `npm test` CRLF failure as a regression — use the real package-integrity gate defined in step-05.
+- **ALWAYS** validate each story against INVEST and split oversized / multi-goal stories before implementing them (see step-02 and `references/story-pipeline.md`).
+- **ALWAYS** enforce the per-story Definition of Done before merging a story to the epic branch.
+- **ALWAYS** respect the configured fix-loop cap; escalate a non-converging story rather than looping forever.
+
+## FIRST STEP
+
+Read fully and follow: `./steps/step-01-intake.md`

package/lib/bmad-extension/skills/bmad-dev-epic/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: bmad-dev-epic
+module: ma-skills

package/lib/bmad-extension/skills/bmad-dev-epic/checklist.md

@@ -0,0 +1,44 @@
+# bmad-dev-epic — Run Checklist
+
+A run is correct only if every box can be checked. Use this to self-audit mid-run and before each gate.
+
+## Intake (step-01)
+- [ ] Target epic identified and its stories enumerated with dependencies.
+- [ ] Epic is genuinely ready (stories have acceptance criteria); otherwise routed to planning.
+- [ ] Model tiers mapped to actually-available models (collapsed to one if single-model/air-gapped).
+- [ ] Parallelism strategy, max-parallel, and fix-loop cap confirmed.
+- [ ] Both release gates confirmed ON (or explicitly changed by the user).
+- [ ] Real test/build gate command confirmed.
+- [ ] Single go/no-go confirmation received.
+
+## Planning (step-02 / step-03)
+- [ ] Every story checked against INVEST; oversized / multi-goal stories split into focused sub-stories (user-confirmed) before graphing.
+- [ ] Dependency DAG built; no cycles (or cycle resolved with the user).
+- [ ] Waves computed per the chosen strategy.
+- [ ] Epic branch `feature/epic-<id>` created off the trunk via `git-workflow-skill` (base overridden to trunk), in its own worktree.
+
+## Per story (step-04 / story-pipeline)
+- [ ] Story branch cut from the epic branch in its own worktree, per `git-workflow-skill`.
+- [ ] Spec re-checked against INVEST/size after create-story; if too large/multi-goal, returned `needs-split` (not implemented) and the orchestrator split it.
+- [ ] create-story → dev-story → parallel code-review + edge-case-hunter executed.
+- [ ] Blocking findings fixed within the fix-loop cap (or story marked blocked, not papered over).
+- [ ] E2E tests generated and passing; test gate green on the story branch.
+- [ ] Definition of Done met before the story is integrated.
+- [ ] Story merged into the epic branch by the orchestrator (serialized, `--no-ff`).
+- [ ] Cross-story breakage checked after each merge.
+
+## Epic gate (step-05)
+- [ ] Adversarial whole-epic review run; blocking findings cleared or HALTED.
+- [ ] `npm run build:plugin` passes; bundle drift clean/committed.
+- [ ] New test failures distinguished from the known pre-existing CRLF baseline.
+
+## Release (step-06)
+- [ ] `code-review` self-review on the full epic diff completed.
+- [ ] GATE A confirmed by user before publish; version bumped; packed `--ignore-scripts`; tarball inspected; published `--tag beta`.
+- [ ] GATE B confirmed by user before PR; single epic PR opened to the trunk; body includes blocked/follow-up section.
+- [ ] PR NOT merged (left for human approval).
+
+## Report (step-07)
+- [ ] Honest summary presented, including every blocked story.
+- [ ] Story worktrees cleaned up; epic worktree retained until merge.
+- [ ] Run Ledger persisted.

package/lib/bmad-extension/skills/bmad-dev-epic/customize.toml

@@ -0,0 +1,54 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-dev-epic. Mirrors the workflow
+# customization shape under the [workflow] namespace. Override in
+# {project-root}/_bmad/custom/bmad-dev-epic.toml (team) or
+# {project-root}/_bmad/custom/bmad-dev-epic.user.toml (personal).
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+on_complete = ""
+
+# ── Orchestration defaults ──────────────────────────────────────────────────
+# These are PROPOSED defaults the intake step shows the user; the user can
+# override every one of them at runtime. They are tier-abstract on purpose so
+# the skill works on disconnected networks and with non-Claude runtimes.
+#
+# All keys below are scalars, so a team/user override TOML replaces them by the
+# normal scalar-override merge rule (override wins over base).
+
+[workflow.defaults]
+
+# Model tiers are ABSTRACT. The intake step maps each tier to a concrete model
+# that the runtime actually exposes (Claude Opus/Sonnet, Gemini, a local model,
+# etc.). If only one model is available, both tiers collapse to it.
+#   review_tier  → deep reasoning: create-story, code-review, edge-case-hunter,
+#                  epic adversarial review.
+#   exec_tier    → implementation: dev-story, fix loops, e2e generation.
+review_tier_model = "claude-opus"          # proposed; ask at runtime
+exec_tier_model   = "claude-sonnet"        # proposed; ask at runtime
+
+# Max story pipelines running concurrently within a single wave.
+max_parallel_stories = 3
+
+# Max review→fix→re-review rounds before a story is escalated as blocked.
+fix_loop_cap = 2
+
+# Parallelization strategy: "waves" (dependency-aware) | "sequential" | "full".
+parallelism_strategy = "waves"
+
+# Human gates. Dev + review run unattended; these two are always confirmed.
+gate_before_publish = true
+gate_before_pr      = true
+
+# Release behavior at the publish gate.
+npm_dist_tag        = "beta"
+version_bump        = "prerelease"         # npm version <bump> --preid=beta
+pack_ignore_scripts = true                 # avoid Windows prepare tarball leak

package/lib/bmad-extension/skills/bmad-dev-epic/references/story-pipeline.md

@@ -0,0 +1,112 @@
+# Per-Story Pipeline Contract
+
+This is the self-contained instruction set handed to each story subagent. The
+orchestrator fills the `<…>` placeholders before spawning. The subagent owns
+exactly one story, in exactly one worktree, and never touches the epic branch.
+
+---
+
+## Inputs (filled by the orchestrator)
+
+```
+STORY_ID        = <id>
+STORY_TITLE     = <title>
+EPIC_ID         = <epic-id>
+EPIC_BRANCH     = feature/epic-<epic-id>
+STORY_BRANCH    = feature/epic-<epic-id>-story-<id>
+WORKTREE        = .worktrees/epic-<epic-id>-story-<id>
+SPRINT_STATUS   = <path to sprint-status.yaml>
+EXEC_MODEL      = <execution-tier model | "host-default">
+REVIEW_MODEL    = <review-tier model | "host-default">
+FIX_LOOP_CAP    = <n>
+TEST_CMD        = <project test/build gate>
+```
+
+## Setup
+
+All git follows `git-workflow-skill`; the only override is the base branch
+(the story branch is cut from `<EPIC_BRANCH>`, not `dev`).
+
+1. Create the worktree off the epic branch, per `git-workflow-skill` (manual
+   form shown, base overridden to the epic branch):
+   ```bash
+   git worktree add <WORKTREE> -b <STORY_BRANCH> <EPIC_BRANCH>
+   ```
+2. Work **only** inside `<WORKTREE>`. Use the Conventional Commit format the
+   skill enforces (`feat`, `fix`, `test`, `docs`, `refactor`, `chore`, `ci`),
+   scoped to the story. Honor the skill's git hooks.
+
+## Pipeline
+
+### 1. Create story spec — `bmad-create-story` [REVIEW_MODEL]
+Produce the context-filled spec for `<STORY_ID>`. If the spec already exists and
+is complete, validate it instead of regenerating. The spec's acceptance criteria
+(ACs) are the contract for the Definition of Done.
+
+**INVEST & size gate (before implementing).** Once the spec is fleshed out,
+re-check it against INVEST and the sizing/focus heuristics (same criteria as
+step-02): one focused goal, small enough to reach Definition of Done in this
+single pass, testable ACs. A spec often only reveals its true size here. **If
+the story is too large or pursues more than one goal, do NOT implement it** —
+return immediately with `status: needs-split` and a `split_proposal` (the
+smallest set of INVEST-compliant sub-stories, each with a focused goal, derived
+ids, and refined dependencies). The orchestrator owns the split because it
+affects the epic-wide wave plan (see step-04). Only proceed to step 2 when the
+story passes the gate.
+
+### 2. Implement — `bmad-dev-story` [EXEC_MODEL]
+Implement strictly against the spec. Follow the repo's always-load skills
+(language best-practices, logging, test-accompanied-development, etc.). Commit.
+
+### 3. Adversarial + edge-case review (PARALLEL) [REVIEW_MODEL]
+Run both, ideally as parallel sub-subagents, each seeing the story diff:
+- `bmad-code-review` — full adversarial review against spec + context.
+- `bmad-review-edge-case-hunter` — exhaustive boundary/branch analysis.
+Collect both findings sets.
+
+### 4. Triage & fix loop [EXEC_MODEL]
+Classify findings as **blocking** (correctness, security, AC miss, broken build)
+vs **non-blocking** (style, nits). For blocking findings:
+- Run `bmad-dev-story` to fix them. Commit.
+- Re-review **only the changed surface**.
+- Repeat until no blocking findings remain OR `FIX_LOOP_CAP` rounds are used.
+- If the cap is hit with blocking findings remaining → return `status: blocked`
+  with the unresolved findings. Do not merge, do not paper over.
+Record non-blocking findings in the return notes (not fixed, by design).
+
+### 5. E2E tests — `bmad-qa-generate-e2e-tests` [EXEC_MODEL]
+Generate e2e/automated tests for the story's behavior and **run them**. Also run
+`<TEST_CMD>` to confirm the story didn't break the package build. If e2e cannot
+be made green within the fix budget, return `status: blocked` with details.
+
+### 6. Definition of Done (gate before returning ready)
+ALL must hold, or the story is `blocked`:
+- [ ] All spec acceptance criteria implemented.
+- [ ] No blocking findings remain from either reviewer.
+- [ ] E2E tests written and passing.
+- [ ] `<TEST_CMD>` passes on the story branch (modulo known pre-existing failures).
+- [ ] All work committed with Conventional Commit messages.
+
+## Return value (structured)
+
+```
+{
+  "story_id":            "<STORY_ID>",
+  "status":              "merged-ready" | "blocked" | "needs-split",
+  "branch":              "<STORY_BRANCH>",
+  "worktree":            "<WORKTREE>",
+  "commits":             [ "<sha> <subject>", … ],
+  "e2e_status":          "passing" | "failing" | "not-created",
+  "unresolved_findings": [ "<blocking finding>", … ],
+  "split_proposal":      [ { "id": "<S3a>", "goal": "<focused goal>", "acs": [ … ], "depends_on": [ … ] }, … ],
+  "fix_rounds_used":     <n>,
+  "notes":               "<non-blocking findings, decisions, caveats>"
+}
+```
+
+`split_proposal` is populated only when `status: needs-split` (empty/omitted
+otherwise). On `needs-split` the subagent has done **no** implementation — it
+returns the proposal and stops.
+
+**Do NOT** merge into `<EPIC_BRANCH>`. The orchestrator serializes all
+integration into the epic branch (step-04) to avoid parallel-merge races.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-01-intake.md

@@ -0,0 +1,59 @@
+# Step 01 — Intake & Guided Configuration
+
+**Goal:** Confirm the epic exists and is ready, then collect the run configuration through guided questions. Nothing is spawned and no branch is created until this step completes.
+
+## 1. Locate and validate the epic (PRECONDITION)
+
+This skill *runs* an epic; it does not invent one. Find the target epic:
+
+1. Read `{sprint_status}` (`{implementation_artifacts}/sprint-status.yaml`) and the epics/stories planning artifacts under `{planning_artifacts}`.
+2. If the user named an epic (id or title), select it. Otherwise list candidate epics and **HALT** for the user to choose.
+3. Enumerate the epic's stories. For each story capture: id, title, status, and declared dependencies / "depends on" / prerequisite references.
+
+**If the epic has no stories**, or stories are placeholders without acceptance criteria: STOP and tell the user to run `bmad-create-epics-and-stories` (and `bmad-sprint-planning`) first. Do not fabricate stories.
+
+**If some stories are already `done`/`merged`**: by default skip them (treat as satisfied dependencies). Confirm this with the user.
+
+## 2. Ask the guided questions
+
+Ask these as a single grouped set (use the host's structured-question UI if available; otherwise a numbered list). Show the proposed default from `{workflow.defaults}` for each and accept "use defaults".
+
+1. **Model tiers (tier-abstract — critical for disconnected/non-Claude runtimes).**
+   First ask: *what models does this runtime actually expose?* Then map:
+   - `{review_model}` — deep reasoning tier (create-story, code-review, edge-case-hunter, epic adversarial review). Default: `{workflow.defaults.review_tier_model}`.
+   - `{exec_model}` — execution tier (dev-story, fix loops, e2e). Default: `{workflow.defaults.exec_tier_model}`.
+   - If only ONE model is available (air-gapped local model, or a single-provider CLI), **collapse both tiers to it** and note that tier separation is disabled.
+   - If the runtime is not Claude (e.g. Gemini, Codex, a local model) or does not support per-subagent model selection, record the mapping anyway but note it is **best-effort**: subagents will use whatever model the host assigns. Never block on this.
+
+2. **Parallelism strategy** — default `{workflow.defaults.parallelism_strategy}`:
+   - `waves` (recommended): dependency-aware; independent stories run in parallel, dependents wait for their predecessors to merge.
+   - `sequential`: one story fully done before the next.
+   - `full`: all stories at once (warn: ignores dependencies; high merge-conflict / broken-build risk).
+
+3. **Max parallel stories per wave** — default `{workflow.defaults.max_parallel_stories}`. Cap to what the host can sanely run concurrently.
+
+4. **Fix-loop cap** — default `{workflow.defaults.fix_loop_cap}`. Max review→fix→re-review rounds before a story is escalated as `blocked`.
+
+5. **Release gates** — confirm both default to ON: pause before npm publish (`{workflow.defaults.gate_before_publish}`) and before the epic PR (`{workflow.defaults.gate_before_pr}`). Confirm `{workflow.defaults.npm_dist_tag}` (default `beta`) and the version bump (default `{workflow.defaults.version_bump}`).
+
+6. **Test command** — the project's real test/build gate for the package-integrity check (step-05). Propose `npm run build:plugin` plus the targeted test subset; confirm. (Note: bare `npm test` has a known pre-existing CRLF failure on Windows — see step-05; do not rely on its exit code alone.)
+
+## 3. Record the resolved configuration
+
+Write the resolved config into the Run Ledger header and mirror it to
+`{implementation_artifacts}/epic-runs/<epic-id>/run-ledger.md`:
+
+```
+Epic:            <id> — <title>
+Stories:         <n> ( <ids…> )   skipped(done): <ids…>
+review_model:    <model>          exec_model: <model>   (tiers collapsed: yes/no)
+strategy:        <waves|sequential|full>   max_parallel: <n>   fix_cap: <n>
+gates:           publish=<on/off>  pr=<on/off>   dist-tag=<tag>  bump=<bump>
+test_gate:       <command(s)>
+```
+
+## 4. Confirm and proceed
+
+Present the resolved config in one compact block and **HALT for a single go/no-go confirmation**. This is the last broad confirmation — after "go", stories run unattended through to the two release gates.
+
+On "go": read fully and follow `./steps/step-02-plan-waves.md`.