ma-agents 3.14.0 → 3.14.1

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-05-epic-adversarial.md

@@ -0,0 +1,31 @@
+# Step 05 — Epic-Level Adversarial Review & Package-Integrity Gate
+
+**Goal:** Before any release action, prove that the assembled epic (all merged stories on the epic branch) aligns with requirements + architecture and did **not** break the `ma-agents` package. Operate on the integrated epic branch, not individual stories.
+
+## 1. Adversarial alignment review — `bmad-review-adversarial-general` [REVIEW_MODEL]
+
+Run a cynical, whole-epic review against the full diff `main...feature/epic-<epic-id>`:
+- Does the implementation satisfy the epic's requirements and acceptance criteria?
+- Does it conform to the project architecture / `project-context.md` and the always-load standards?
+- Cross-story coherence: do the merged stories form a consistent whole, or did parallel development introduce contradictions, dead code, or duplicated abstractions?
+- Did anything regress in adjacent, untouched areas?
+
+Produce a findings report graded by severity. **Blocking** findings (requirement/architecture violation, regression, broken contract) must be remediated: spawn an `{exec_model}` fix subagent scoped to the finding, re-run the relevant story/epic tests, and re-review. Loop within reason; if blocking findings cannot be cleared, **HALT** and report to the user — do not proceed to release with known blocking findings.
+
+## 2. Package-integrity gate (the "didn't break ma-agents" check)
+
+Run the real gate on the epic branch — **not** bare `npm test` alone:
+
+1. **Plugin build must pass:** `npm run build:plugin` (assembles `lib/bmad-extension-plugin/`). A failure here is a hard stop.
+2. **Bundle-drift guard:** after building, confirm `lib/bmad-extension-plugin/` and the resolved `marketplace.json` are up to date with the source (`lib/bmad-extension/`). If this epic added/renamed skills or bumped `module.yaml`, the rebuilt bundle must be committed. CI enforces this ("Bundle Drift Guard") — catch it here first.
+3. **Targeted tests:** run the test subset relevant to what the epic changed.
+4. **Known pre-existing failure:** a full `npm test` on Windows exits non-zero due to long-standing MIL-498 template CRLF drift (halts around position 13) and also regenerates `.agents/`. **Do not** classify that specific known failure as an epic regression. Distinguish new failures from the baseline: if in doubt, run the same command on `main` and diff the failure set. Only *new* failures block.
+
+Record the gate outcome (build: pass/fail, drift: clean/committed, tests: new-failures vs baseline) in the Run Ledger.
+
+## 3. Gate decision
+
+- All blocking adversarial findings cleared **and** package-integrity gate clean (no new failures, build green, no uncommitted bundle drift) → proceed.
+- Otherwise → **HALT**, report exactly what is blocking, and let the user decide whether to fix-and-retry or stop.
+
+On pass, read fully and follow `./steps/step-06-release.md`.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-06-release.md

@@ -0,0 +1,57 @@
+# Step 06 — Gated Beta Publish & Epic PR
+
+**Goal:** Ship a testable beta package and open the epic PR — both behind explicit human gates. These are the only two outward, hard-to-undo actions in the run.
+
+## Self-review before anything (mandatory)
+
+Per repo policy, run the `code-review` skill on the full epic diff (`main...feature/epic-<epic-id>`) and address its findings before opening the PR. This is in addition to the per-story reviews — it catches integration-level issues.
+
+## GATE A — npm beta publish
+
+Only if `{workflow.defaults.gate_before_publish}` (default ON). **HALT and ask the user to confirm** before running any publish command. Publishing is effectively irreversible (a version can be deprecated but not truly unpublished after 72h) and requires credentials/2FA.
+
+On confirmation:
+
+1. **Bump version** on the epic branch using the configured bump `{workflow.defaults.version_bump}`:
+   ```bash
+   npm version {workflow.defaults.version_bump} --preid=beta --no-git-tag-version
+   ```
+   (default bump `prerelease` → e.g. `3.14.0` → `3.14.1-beta.0`). Commit the bump.
+2. **Rebuild the bundle** so `marketplace.json` carries the new version, and commit any drift: `npm run build:plugin`.
+3. **Pack** — when `{workflow.defaults.pack_ignore_scripts}` is true (the default), pass `--ignore-scripts` to avoid the known Windows `prepare` tarball leak (a temp build dir leaking into the tarball):
+   ```bash
+   npm pack --ignore-scripts          # omit --ignore-scripts only if pack_ignore_scripts = false
+   ```
+   Inspect the tarball contents (`tar -tzf <tgz>`) — confirm no stray temp/build directory is included.
+4. **Publish** to the channel `{workflow.defaults.npm_dist_tag}` (default `beta`; requires npm auth + OTP/2FA; the user supplies the OTP at the gate — never hardcode it). Match the `--ignore-scripts` choice from the pack step:
+   ```bash
+   npm publish --tag {workflow.defaults.npm_dist_tag} --ignore-scripts
+   ```
+   If 2FA prompts, surface it to the user. Confirm the publish with `npm view <pkg> dist-tags`.
+5. Tell the user the exact install line to test, e.g. `npm i ma-agents@beta` (or the resolved `@<version>`).
+
+If the user declines GATE A: skip publish, continue to GATE B (the PR can still be opened without a published beta).
+
+## GATE B — Epic Pull Request
+
+Only if `{workflow.defaults.gate_before_pr}` (default ON). **HALT and ask the user to confirm** before opening the PR.
+
+On confirmation, push the epic branch and open ONE PR (`feature/epic-<epic-id>` → `main`) following `git-workflow-skill`'s finish flow. The two epic-specific overrides vs. the skill's `finish-feature.sh` defaults: the PR **base is the trunk (`main`), not `dev`**, and there is **exactly one** PR for the whole epic (no per-story PRs). Use the skill's documented manual finish equivalent:
+
+```bash
+git -C <epic-worktree> push -u origin feature/epic-<epic-id>   # <epic-worktree> = path from the Run Ledger
+gh pr create --base main --head feature/epic-<epic-id> --title "feat(epic-<id>): <epic title>" --body-file <generated-body>
+```
+
+The PR body (generated from the Run Ledger) must include:
+- Epic summary and link to the planning artifacts.
+- Per-story table: status (merged / **blocked** / skipped), e2e status, fix rounds, any unresolved non-blocking findings.
+- Adversarial review summary + package-integrity gate outcome.
+- The published beta version + install line (if GATE A ran).
+- An explicit **"Blocked / follow-up"** section if any story did not converge — never hide this.
+
+Credential note: if the default git/`gh` token is rejected, a working PAT may live in the location recorded in memory ("GitHub push credentials location"); use it masked. Never echo tokens.
+
+Do **not** merge the PR — the user approves and merges the epic PR themselves.
+
+Then read fully and follow `./steps/step-07-report.md`.

package/lib/bmad-extension/skills/bmad-dev-epic/steps/step-07-report.md

@@ -0,0 +1,40 @@
+# Step 07 — Final Report & Cleanup
+
+**Goal:** Leave the user with a complete, honest picture of the run and a clean working tree.
+
+## 1. Present the run summary
+
+From the Run Ledger, present (in `{communication_language}`):
+
+```
+Epic <id> — <title>   |   <merged>/<total> stories merged
+
+Stories
+  ✓ S1  merged    e2e: pass   fixes: 1
+  ✓ S2  merged    e2e: pass   fixes: 0
+  ⚠ S3  BLOCKED   <one-line reason + unresolved findings>
+  ⏭ S4  skipped (already done)
+
+Epic adversarial review : <pass | findings cleared: n>
+Package-integrity gate  : build ✓  drift ✓  tests: <new-failures: 0 vs baseline>
+Beta publish            : <version + install line | skipped/declined>
+Epic PR                 : <url | not opened>
+```
+
+## 2. Surface anything that needs the human
+
+- List every `blocked` story and exactly what is unresolved — these are the user's follow-ups.
+- Note any place the run HALTED and why.
+- If the beta publish or PR was declined/skipped, state the exact commands to do it manually.
+
+## 3. Cleanup
+
+- Remove any remaining story worktrees: `git worktree remove .worktrees/epic-<epic-id>-story-<sid>` (and `git worktree prune`).
+- Leave the **epic worktree and branch in place** until the user merges the PR — they may want to push fixes. After merge, the epic worktree can be removed with `git worktree remove .worktrees/epic-<epic-id>`.
+- Persist the final Run Ledger to `{implementation_artifacts}/epic-runs/<epic-id>/run-ledger.md`.
+
+## 4. Suggest next steps
+
+Recommend `bmad-retrospective` for the epic once the PR merges, and (if any stories were blocked) `bmad-correct-course` to re-plan them.
+
+This completes the workflow.

package/lib/bmad-extension/skills/ma-agent-sqa/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ma-agent-sqa
-description: SQA Agent (Gad) — Software Quality Assurance and MIL-STD-498 expert for project auditing, compliance verification, quality reporting, and defense documentation generation
+description: SQA Agent (Gadi) — Software Quality Assurance and MIL-STD-498 expert for project auditing, compliance verification, quality reporting, and defense documentation generation
 ---
 
-# Agent: Gad — Software Quality Assurance & Standards Expert
+# Agent: Gadi — Software Quality Assurance & Standards Expert
 
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
 
@@ -35,7 +35,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | # | Cmd | Action | Trigger | Skill |
 |---|-----|--------|---------|-------|
 | 1 | MH | Redisplay Menu Help | "menu", "help" | _(built-in)_ |
-| 2 | CH | Chat with Gad about quality assurance or MIL-STD-498 | "chat", "quality" | _(built-in)_ |
+| 2 | CH | Chat with Gadi about quality assurance or MIL-STD-498 | "chat", "quality" | _(built-in)_ |
 | **— SQA Workflows —** | | | | |
 | 3 | AU | Audit Project: Comprehensive quality audit across all project dimensions | "audit", "audit project", "run audit" | sqa-audit |
 | 4 | IC | IEEE 12207 Compliance: Evaluate the project against IEEE/ISO/IEC 12207 software lifecycle processes | "ieee", "12207", "lifecycle compliance", "iso 12207" | sqa-ieee12207 |

package/lib/bmad-extension/skills/ma-agent-sqa/bmad-skill-manifest.yaml

@@ -1,6 +1,6 @@
 type: agent
 name: ma-agent-sqa
-displayName: Gad
+displayName: Gadi
 title: Software Quality Assurance & Standards Expert
 icon: "🔍"
 capabilities: "Software quality assurance, project auditing, process compliance, requirements traceability, sprint health, release validation, IEEE/ISO/IEC 12207 compliance, MIL-STD-498 document generation (SRS, SDD, SDP, OCD, SSS, STD, SSDD)"

package/lib/bmad-extension/skills/module-help.csv

@@ -3,7 +3,7 @@ ma-skills,anytime,SRE Agent,ma-agent-sre,,skill:ma-agent-sre,ma-agent-sre,false,
 ma-skills,anytime,DevOps Agent,ma-agent-devops,,skill:ma-agent-devops,ma-agent-devops,false,bmm-devops,,"DevOps Engineer agent for CI/CD pipeline automation, Infrastructure as Code, and cloud-native technologies.",output_folder,"agent customization",
 ma-skills,anytime,Cyber Agent,ma-agent-cyber,,skill:ma-agent-cyber,ma-agent-cyber,false,bmm-cyber,,"Cyber Security Analyst agent for vulnerability assessment, threat modeling, and system hardening.",output_folder,"agent customization",
 ma-skills,anytime,ML Scientist Agent,ma-agent-ml,,skill:ma-agent-ml,ma-agent-ml,false,bmm-demerzel,,"Machine Learning Scientist agent for hypothesis-driven ML lifecycle with scientific rigor.",output_folder,"agent customization",
-ma-skills,anytime,SQA Agent,ma-agent-sqa,,skill:ma-agent-sqa,ma-agent-sqa,false,bmm-qa,,"Software Quality Assurance agent (Gad) for project auditing, compliance verification, and quality reporting.",output_folder,"agent customization",
+ma-skills,anytime,SQA Agent,ma-agent-sqa,,skill:ma-agent-sqa,ma-agent-sqa,false,bmm-qa,,"Software Quality Assurance agent (Gadi) for project auditing, compliance verification, and quality reporting.",output_folder,"agent customization",
 ma-skills,4-implementation,Generate SSS,mil498-sss,,skill:mil498-sss,bmad-mil-generate-sss,false,bmm-mil498,,"Generate a MIL-STD-498 System/Subsystem Specification (SSS).",output_folder,"MIL-498 document",
 ma-skills,4-implementation,Generate SSDD,mil498-ssdd,,skill:mil498-ssdd,bmad-mil-generate-ssdd,false,bmm-mil498,,"Generate a MIL-STD-498 System/Subsystem Design Description (SSDD).",output_folder,"MIL-498 document",
 ma-skills,4-implementation,Generate OCD,mil498-ocd,,skill:mil498-ocd,bmad-mil-generate-ocd,false,bmm-mil498,,"Generate a MIL-STD-498 Operational Concept Description (OCD).",output_folder,"MIL-498 document",
@@ -47,6 +47,7 @@ ma-skills,4-implementation,SQA Audit,sqa-audit,,skill:sqa-audit,sqa-audit,false,
 ma-skills,4-implementation,IEEE 12207 Compliance,sqa-ieee12207,,skill:sqa-ieee12207,sqa-ieee12207,false,bmm-qa,,"Evaluate the project against IEEE/ISO/IEC 12207:2017 software lifecycle processes — produces a compliance matrix and gap analysis report.",_bmad-output,"compliance report",
 ma-skills,4-implementation,Create Bug Story,create-bug-story,,skill:create-bug-story,create-bug-story,false,bmm-dev,,"Create a structured bug story from a detected defect and add to backlog.",_bmad-output/implementation-artifacts,"bug story",
 ma-skills,4-implementation,Dev Story,bmad-dev-story,,skill:bmad-dev-story,bmad-dev-story,false,bmm-dev,,"Execute story implementation following a context filled story spec file.",_bmad-output/implementation-artifacts,"story implementation",
+ma-skills,4-implementation,Dev Epic,bmad-dev-epic,,skill:bmad-dev-epic,bmad-dev-epic,false,bmm-dev,,"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.",_bmad-output/implementation-artifacts,"epic run ledger + PR",
 ma-skills,4-implementation,Sprint Planning,bmad-sprint-planning,,skill:bmad-sprint-planning,bmad-sprint-planning,false,bmm-sm,,"Bootstrap or update the unified sprint-status.yaml from epics with three sections (epics, backlog, sprints).",_bmad-output/implementation-artifacts,"sprint plan",
 ma-skills,4-implementation,Generate Backlog,generate-backlog,,skill:generate-backlog,generate-backlog,false,bmm-sm,,"Generate or refresh the backlog section of sprint-status.yaml from epics and bug stories.",_bmad-output/implementation-artifacts,"backlog",
 ma-skills,4-implementation,Add Sprint,add-sprint,,skill:add-sprint,add-sprint,false,bmm-sm,,"Create a new sprint entry in the sprints section of sprint-status.yaml with capacity limits, optional ISO dates, and auto-incremented ID.",_bmad-output/implementation-artifacts,"sprint plan",

package/lib/bmad-extension/skills/module.yaml

@@ -15,6 +15,6 @@
 code: ma-skills
 name: "MA-Agents Skills & Agents"
 description: "Enterprise methodology enforcement, specialized agents, and operational workflows"
-module_version: "3.6.2"
+module_version: "3.7.0"
 extends-module: bmm
 default_selected: false

package/lib/bmad-extension/skills/sqa-audit/SKILL.md

@@ -172,7 +172,7 @@ After running all selected dimensions, compile a full audit report.
 ```
 # SQA Audit Report
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Scope:** {list of audited dimensions}
 **Overall Status:** PASS | WARNING | FAIL
 
@@ -246,7 +246,7 @@ If yes, generate and save a remediation plan to:
 ```
 # SQA Remediation Plan
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Source Report:** sqa-audit-report-{YYYY-MM-DD}.md
 **Scope:** {audited dimensions}
 

package/lib/bmad-extension/skills/sqa-ieee12207/SKILL.md

@@ -193,7 +193,7 @@ Evaluate each selected process group. For each process area, assign a compliance
 
 ### Group 4 — Organizational Project-Enabling Processes
 
-Note to Gad: For Group 4 items, briefly assess based on available evidence only. These are primarily organizational-scope and marked accordingly.
+Note to Gadi: For Group 4 items, briefly assess based on available evidence only. These are primarily organizational-scope and marked accordingly.
 
 #### 4.1 Life Cycle Model Management (6.2.1)
 - Is a defined software life cycle model being followed?
@@ -216,7 +216,7 @@ Compile the full compliance report.
 ```
 # IEEE/ISO/IEC 12207:2017 Compliance Report
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Standard:** IEEE/ISO/IEC 12207:2017 — Systems and software engineering — Software life cycle processes
 **Scope:** {selected process groups}
 **Overall Compliance Level:** COMPLIANT | PARTIAL | NON-COMPLIANT
@@ -332,7 +332,7 @@ If yes, generate and save a remediation plan to:
 ```
 # IEEE/ISO/IEC 12207 Remediation Plan
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Source Report:** sqa-ieee12207-report-{YYYY-MM-DD}.md
 **Standard:** IEEE/ISO/IEC 12207:2017
 

package/lib/bmad-extension/skills/sqa-requirements-quality/SKILL.md

@@ -157,7 +157,7 @@ Compile the full report in this structure:
 ```
 # Requirements Quality Audit Report
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Scope:** {selected document sources}
 **Requirements Audited:** {total count}
 **Overall Quality Score:** {X}/{Y} ({P}%)
@@ -216,7 +216,7 @@ If yes, save a remediation plan to:
 ```
 # Requirements Quality Remediation Plan
 **Date:** {today's date}
-**Auditor:** Gad (SQA Agent)
+**Auditor:** Gadi (SQA Agent)
 **Source Report:** sqa-requirements-quality-report-{YYYY-MM-DD}.md
 
 ---

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

@@ -3,7 +3,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",
@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.14.0",
+      "version": "3.14.1",
       "author": {
         "name": "Alon Mayaffit"
       },
@@ -91,6 +91,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-plugin/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-plugin/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-plugin/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-plugin/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-plugin/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.