ma-agents 3.14.0 → 3.14.1

package/README.md

@@ -184,7 +184,7 @@ These domain-expert agents are installed alongside BMAD-METHOD and provide guide
 | DevOps Agent | Amit | `_bmad/skills/devops/` | `_bmad/bmm/agents/devops.md` |
 | Cyber Analyst | Yael | `_bmad/skills/cyber/` | `_bmad/bmm/agents/cyber.md` |
 | ML Scientist | Demerzel | `_bmad/skills/demerzel/` | `_bmad/bmm/agents/demerzel.md` |
-| SQA & Standards Expert | Gad | `_bmad/skills/sqa/` | `_bmad/bmm/agents/qa.md` |
+| SQA & Standards Expert | Gadi | `_bmad/skills/sqa/` | `_bmad/bmm/agents/qa.md` |
 
 ## Available Skills
 
@@ -247,7 +247,7 @@ These workflows are installed as part of the BMAD agent system and are invoked t
 | `ml-revision` | ML Scientist | Amend hypothesis and requirements based on experiment findings |
 | `ml-advise` | ML Scientist | Search past experiments, surface findings and failure warnings |
 | `ml-retrospective` | ML Scientist | Capture session learnings and update project context |
-| **SQA & MIL-STD-498 (Gad)** | | |
+| **SQA & MIL-STD-498 (Gadi)** | | |
 | `sqa-audit` | SQA & Standards Expert | Multi-dimensional project quality audit: code↔story traceability, stories↔architecture/PRD alignment, process compliance, sprint health, release state — saves audit report and optional remediation plan |
 | `sqa-ieee12207` | SQA & Standards Expert | IEEE/ISO/IEC 12207:2017 compliance assessment across 23 process areas in 4 groups — produces compliance matrix, gap analysis, and optional remediation plan |
 | `sqa-requirements-quality` | SQA & Standards Expert | Requirements quality audit against 14 criteria with scope selection (PRD FRs, NFRs, epics, stories) — per-requirement audit table, critical-fail detection, Overall Quality Score, and optional remediation plan |
@@ -357,7 +357,7 @@ npx ma-agents install --yes    # fully offline BMAD install — no network neede
    - **Focus**: Hypothesis-driven machine learning lifecycle with scientific rigor.
    - **Capabilities**: EDA, architecture design, locked TechSpec contracts, experiment execution, failure-cost analysis.
    - **Workflows**: 12-stage ML lifecycle from ideation through retrospective, with mandatory review gates.
-5. **Gad (SQA & Standards Expert)**:
+5. **Gadi (SQA & Standards Expert)**:
    - **Focus**: Software quality assurance and defense documentation standards — a unified persona covering SQA auditing and MIL-STD-498 document generation.
    - **SQA Capabilities**: Multi-dimensional project quality audits, IEEE/ISO/IEC 12207:2017 compliance assessments (23 process areas, 4 groups), requirements evaluation against 14 established quality criteria (scope-selectable: PRD FRs, NFRs, epics, stories).
    - **MIL-STD-498 Capabilities**: Full Data Item Description (DID) generation for SRS, SDD, SDP, OCD, SSS, STD, and SSDD. Requirements quality review tailored to MIL-STD-498 structure and military-standard terminology (CSCI, HWCI, IRS).

package/lib/agents.js

@@ -314,10 +314,10 @@ const agents = [
   },
   {
     id: 'bmm-qa',
-    name: 'SQA & Standards Expert (Gad)',
+    name: 'SQA & Standards Expert (Gadi)',
     version: '1.0.0',
     category: 'bmad',
-    description: 'Software Quality Assurance and MIL-STD-498 Standards Expert (Gad)',
+    description: 'Software Quality Assurance and MIL-STD-498 Standards Expert (Gadi)',
     skillsDir: '_bmad/skills/sqa',
     getProjectPath: () => path.join(process.cwd(), '_bmad', 'skills', 'sqa'),
     getGlobalPath: () => null,

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",
@@ -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`.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-02-plan-waves.md

@@ -0,0 +1,56 @@
+# Step 02 — Right-Size Stories, Build the Dependency DAG, Compute Waves
+
+**Goal:** Make the story set sound (INVEST-compliant, focused, appropriately small) and then turn it into an ordered set of execution waves so independent stories parallelize and dependents only start once their prerequisites are merged.
+
+## 1. INVEST & story-sizing pre-pass
+
+Before graphing dependencies, assess **every** non-skipped story against **INVEST**:
+
+- **I**ndependent — minimal coupling to other stories (soft-couples become dependency edges in §2, not blockers).
+- **N**egotiable — describes intent, not a frozen implementation.
+- **V**aluable — delivers a discrete, demonstrable slice of user/system value.
+- **E**stimable — small and clear enough to estimate with confidence.
+- **S**mall — completable within a single focused pipeline run; **one** focused goal.
+- **T**estable — has acceptance criteria that can be verified (and later turned into e2e tests).
+
+**Sizing / focus heuristics — a story is "too long" and should be split if any hold:**
+- it pursues more than one distinct goal, or its title contains "and" joining separable outcomes;
+- it spans multiple unrelated modules/layers that could ship and be tested independently;
+- its acceptance criteria are so numerous that they read like several stories stapled together;
+- it cannot plausibly reach Definition of Done (implement + review + e2e) in one focused pass.
+
+**When a story is too large or multi-goal:** split it into the smallest set of INVEST-compliant sub-stories, each with one focused goal and its own acceptance criteria. Preserve the original as a parent/epic-let reference, give sub-stories derived ids (e.g. `S3` → `S3a`, `S3b`), and carry over / refine dependencies. **Present the proposed split to the user and HALT for confirmation** before committing it to `sprint-status.yaml` (splitting changes the planned scope). Record the final, right-sized story set — it is the input to §2.
+
+> This is the planning-time pass. The per-story pipeline (`references/story-pipeline.md`) re-checks INVEST after `bmad-create-story` and can still return `needs-split` if a story only reveals its true size once its spec is fleshed out — see step-04's handling.
+
+## 2. Build the dependency graph
+
+For every non-skipped story, resolve its dependencies into a directed graph (edge `A → B` means "A depends on B; B must merge first"). Sources of dependencies, in priority order:
+
+1. Explicit `depends_on` / prerequisite fields in `sprint-status.yaml` or the story spec.
+2. Stated dependencies in the epic / story prose ("requires the API from story X").
+3. Shared-file heuristics: if two stories are known to edit the same module, treat them as a soft conflict (same-wave concurrency risk) and prefer to sequence them.
+
+## 3. Detect cycles
+
+Run a topological sort. **If a cycle exists**, STOP and report the cycle to the user — a circular dependency cannot be waved automatically. Offer to (a) break the cycle by merging the stories, or (b) force a user-specified order.
+
+## 4. Compute waves by strategy
+
+- **`waves`** (default): Wave *k* = all stories whose dependencies are all satisfied by waves `< k`. Within a wave, cap concurrent pipelines at `max_parallel_stories`; if a wave is larger, run it in batches.
+- **`sequential`**: one story per wave, in topological order.
+- **`full`**: a single wave of all stories (only if the user explicitly chose this; re-warn about conflict risk).
+
+## 5. Present the plan
+
+Show the wave plan compactly and record it in the Run Ledger:
+
+```
+Wave 1:  S1, S2, S3        (independent)
+Wave 2:  S4 (needs S1), S5 (needs S2)
+Wave 3:  S6 (needs S4,S5)
+```
+
+Do **not** HALT here (the user already gave go in step-01) — but if the computed plan reveals a problem the user could not have anticipated (e.g. every story is sequential and the user expected parallelism, or a story has unresolved/dangling dependencies), surface it in one line and HALT for a decision.
+
+Then read fully and follow `./steps/step-03-epic-branch.md`.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-03-epic-branch.md

@@ -0,0 +1,35 @@
+# Step 03 — Create the Epic Feature Branch
+
+**Goal:** Establish the integration branch for the whole epic, off the trunk, before any story work begins. This is the branch the final PR targets `main` from, and the branch every story branch merges back into.
+
+## Branch topology (the contract)
+
+```
+main
+  └── feature/epic-<epic-id>                 ← epic integration branch (this step)
+        ├── feature/epic-<epic-id>-story-<s1>   ← per-story branch (step-04, own worktree)
+        ├── feature/epic-<epic-id>-story-<s2>
+        └── …                                    each merges back into feature/epic-<epic-id>
+```
+
+- The **epic branch** is cut from `main` (this repo's trunk; confirm the trunk name — `main` here).
+- Each **story branch** is cut from the **epic branch**, developed in its own worktree, and merged back into the epic branch when it passes its Definition of Done (step-04). Stories integrate with `--no-ff` so each story is one reviewable merge commit. No PR per story (the user approves only the epic PR).
+- The single **epic PR** (step-06) is `feature/epic-<epic-id>` → `main`.
+
+## Procedure
+
+All git here follows `git-workflow-skill`. The only epic-specific override is the **base branch**: the epic branch is cut from the **trunk** (`main`), not from `dev`.
+
+1. Follow `git-workflow-skill` to create the epic worktree + feature branch, with the base overridden to the trunk. Use its `start-feature.sh` if it accepts a base argument; otherwise use the skill's documented **manual** equivalent:
+   ```bash
+   git fetch origin
+   # git-workflow-skill manual form, base overridden to the trunk:
+   git worktree add .worktrees/epic-<epic-id> -b feature/epic-<epic-id> main
+   ```
+   (`.worktrees/` is gitignored in this repo. Confirm the trunk name first — `main` here. Ensure the skill's git hooks are installed so commit-message/branch protections apply.)
+2. Record the epic worktree path and branch in the Run Ledger.
+3. Story worktrees are created later, one per story, branched from `feature/epic-<epic-id>` — see step-04.
+
+**Do not** write any non-git file outside a worktree from here on. All story output lands in story worktrees; all integration lands on the epic branch.
+
+Then read fully and follow `./steps/step-04-run-waves.md`.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-04-run-waves.md

@@ -0,0 +1,49 @@
+# Step 04 — Run the Waves (Parallel Per-Story Pipelines)
+
+**Goal:** Execute each wave by spawning one subagent per story, each running the full per-story pipeline in its own worktree, then integrating passing stories back into the epic branch. This is the core of the orchestration.
+
+## How subagents are used
+
+- Spawn **one subagent per story** using the host's Agent/Task tool. Put all spawns for a wave (up to `max_parallel_stories`) in a **single response** so they run concurrently.
+- Each subagent is **stateless w.r.t. this conversation** — it receives a self-contained prompt (the story-pipeline contract below) plus the paths it needs. It must not assume access to the orchestrator's context.
+- Assign each subagent the model implied by the step it is running (`{review_model}` vs `{exec_model}`). Because a single subagent runs multiple BMAD skills across both tiers, prefer this split:
+  - If the host supports per-skill model switching inside one subagent, instruct it to use `{review_model}` for create-story/code-review/edge-case-hunter and `{exec_model}` for dev-story/fixes/e2e.
+  - If not, run the story as **two chained subagents**: an `{exec_model}` "builder" and a `{review_model}` "reviewer", handing the worktree between them.
+  - If model selection is unavailable (non-Claude / single-model runtime), run one subagent and note tiers are collapsed.
+
+## Per-story pipeline (the contract every story subagent runs)
+
+Give each story subagent the full contract in `references/story-pipeline.md` (skill-root–relative). The inline summary below is **illustrative only** — `references/story-pipeline.md` is the authoritative contract; if they diverge, the reference file wins. In summary, in the story's own worktree branched from the epic branch:
+
+1. `bmad-create-story` → produce the context-filled story spec.            [review tier]
+2. `bmad-dev-story` → implement against the spec.                          [exec tier]
+3. Parallel review: `bmad-code-review` **and** `bmad-review-edge-case-hunter`. [review tier]
+4. Triage findings → if any are blocking, `bmad-dev-story` fix loop (cap `fix_loop_cap`), then re-review only the changed surface. [exec tier]
+5. `bmad-qa-generate-e2e-tests` → generate e2e tests and run them.          [exec tier]
+6. Enforce the **Definition of Done** (review clean + e2e green + spec ACs met). Commit with Conventional Commits.
+
+The subagent returns a structured result: `{story_id, status: merged-ready|blocked|needs-split, branch, worktree, commits, unresolved_findings[], split_proposal[], e2e_status, notes}`. It must **not** merge to the epic branch itself — the orchestrator integrates (step below) to keep merges serialized. A `needs-split` result means the story was found too large/multi-goal at spec time and was **not** implemented — the orchestrator handles the split (see below).
+
+## Wave loop
+
+For each wave in order:
+
+1. **Spawn** the wave's story subagents in parallel (respect `max_parallel_stories`; batch if larger). Mark each story `in-progress` in the Run Ledger.
+2. **Collect** results as subagents return. Update the Ledger per story.
+3. **Handle `needs-split` results**: the story was found too large/multi-goal and was not implemented. Apply its `split_proposal`: present the proposed sub-stories to the user and **HALT for confirmation** (splitting changes planned scope), then add the confirmed sub-stories to `sprint-status.yaml`, replace the parent in the Ledger, recompute affected dependencies/waves (re-enter step-02's §2–§4 for just the new stories), and schedule the sub-stories into the current wave (if independent) or a later wave. Discard the parent's unused story worktree/branch via `git-workflow-skill` cleanup.
+4. **Integrate** each `merged-ready` story into the epic branch, **one at a time** (serialized), from the epic worktree (use the epic worktree path recorded in the Run Ledger, not a re-derived guess). Use `git-workflow-skill` conventions; the merge into the epic branch is the epic-specific manual step:
+   ```bash
+   git -C <epic-worktree> merge --no-ff feature/epic-<epic-id>-story-<sid>
+   ```
+   - On a **merge conflict**: do not guess. Spawn an `{exec_model}` subagent scoped to resolve only that conflict against both stories' intent, or HALT and report if it cannot. Re-run that story's e2e after resolution.
+   - After a successful merge, run the project build/test gate (the step-01 `test_gate`) on the epic branch to catch cross-story breakage early. If it breaks, treat as a blocking finding against the just-merged story.
+5. **Blocked stories**: a story that exhausts `fix_loop_cap` without converging, or whose e2e cannot pass, is marked `blocked` with its `unresolved_findings`. Do **not** silently drop it. Continue the epic with the rest, but record it for the step-05 report and the PR description. If a *downstream* story depends on a blocked story, mark the dependents `blocked (upstream)` and skip their wave entry.
+6. Clean up each story worktree after its merge, per `git-workflow-skill` (manual form: `git worktree remove .worktrees/epic-<epic-id>-story-<sid>`).
+
+**Persist the Run Ledger to disk** (`{implementation_artifacts}/epic-runs/<epic-id>/run-ledger.md`) after integrating each story and again at the end of each wave, so a crashed run can be resumed without redoing merged stories.
+
+Proceed to the next wave only when the current wave's stories are all `merged` or `blocked`.
+
+## After all waves
+
+Record the final tally in the Run Ledger (merged / blocked / skipped) and persist it to disk. Then read fully and follow `./steps/step-05-epic-adversarial.md`.