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

package/.claude-plugin/marketplace.json

@@ -7,59 +7,84 @@
   "license": "MIT",
   "homepage": "https://github.com/bmad-code-org/BMAD-METHOD",
   "repository": "https://github.com/bmad-code-org/BMAD-METHOD",
-  "keywords": ["bmad", "agile", "ai", "orchestrator", "development", "methodology", "agents"],
+  "keywords": ["bmad", "agile", "ai", "orchestrator", "development", "methodology", "agents", "brainstorming", "thinking"],
   "plugins": [
     {
-      "name": "bmad-pro-skills",
+      "name": "bmad-brainstorming",
       "source": "./",
-      "description": "Next level skills for power users — advanced prompting techniques, agent management, and more.",
-      "version": "6.8.0",
+      "description": "Facilitated brainstorming with a curated technique library — diverge, converge, and capture ideas with a visual technique picker.",
+      "version": "6.10.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
-      "skills": [
-        "./src/core-skills/bmad-help",
-        "./src/core-skills/bmad-brainstorming",
-        "./src/core-skills/bmad-customize",
-        "./src/core-skills/bmad-spec",
-        "./src/core-skills/bmad-party-mode",
-        "./src/core-skills/bmad-shard-doc",
-        "./src/core-skills/bmad-advanced-elicitation",
-        "./src/core-skills/bmad-editorial-review-prose",
-        "./src/core-skills/bmad-editorial-review-structure",
-        "./src/core-skills/bmad-index-docs",
-        "./src/core-skills/bmad-review-adversarial-general",
-        "./src/core-skills/bmad-review-edge-case-hunter",
-        "./src/core-skills/bmad-review-verification-gap"
-      ]
+      "skills": ["./src/core-skills/bmad-brainstorming"]
+    },
+    {
+      "name": "bmad-party-mode",
+      "source": "./",
+      "description": "Multi-perspective roundtable discussions — collide viewpoints between agents or custom personas to stress-test any topic.",
+      "version": "6.10.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": ["./src/core-skills/bmad-party-mode"]
+    },
+    {
+      "name": "bmad-forge-idea",
+      "source": "./",
+      "description": "Pressure-test an idea with persona-driven interrogation until it hardens, proves out, or dies cheaply.",
+      "version": "6.10.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": ["./src/core-skills/bmad-forge-idea"]
+    },
+    {
+      "name": "bmad-deep-recon",
+      "source": "./",
+      "description": "Decision-grade research harness — draft deep-research prompts for your own AI tools, process finished reports into downstream-ready cited summaries, or run the research directly; six research types, claim verification, and a living refresh cycle.",
+      "version": "6.10.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": ["./src/core-skills/bmad-deep-recon"]
+    },
+    {
+      "name": "bmad-analysis",
+      "source": "./",
+      "description": "The BMad thinking pack — structured brainstorming, idea pressure-testing, and multi-perspective agent roundtables in one install.",
+      "version": "6.10.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": ["./src/core-skills/bmad-brainstorming", "./src/core-skills/bmad-party-mode", "./src/core-skills/bmad-forge-idea"]
     },
     {
       "name": "bmad-method-lifecycle",
       "source": "./",
       "description": "Full-lifecycle AI development framework — agents and workflows for product analysis, planning, architecture, and implementation.",
-      "version": "6.8.0",
+      "version": "6.10.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
       "skills": [
+        "./src/core-skills/bmad-help",
+        "./src/core-skills/bmad-customize",
+        "./src/core-skills/bmad-advanced-elicitation",
+        "./src/core-skills/bmad-review",
         "./src/bmm-skills/1-analysis/bmad-product-brief",
         "./src/bmm-skills/1-analysis/bmad-prfaq",
         "./src/bmm-skills/1-analysis/bmad-agent-analyst",
         "./src/bmm-skills/1-analysis/bmad-agent-tech-writer",
         "./src/bmm-skills/1-analysis/bmad-document-project",
-        "./src/bmm-skills/1-analysis/research/bmad-domain-research",
-        "./src/bmm-skills/1-analysis/research/bmad-market-research",
-        "./src/bmm-skills/1-analysis/research/bmad-technical-research",
+        "./src/core-skills/bmad-deep-recon",
         "./src/bmm-skills/2-plan-workflows/bmad-agent-pm",
         "./src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer",
         "./src/bmm-skills/2-plan-workflows/bmad-prd",
-        "./src/bmm-skills/2-plan-workflows/bmad-create-prd",
-        "./src/bmm-skills/2-plan-workflows/bmad-edit-prd",
-        "./src/bmm-skills/2-plan-workflows/bmad-validate-prd",
+        "./src/bmm-skills/2-plan-workflows/bmad-spec",
         "./src/bmm-skills/2-plan-workflows/bmad-ux",
         "./src/bmm-skills/3-solutioning/bmad-agent-architect",
         "./src/bmm-skills/3-solutioning/bmad-architecture",
-        "./src/bmm-skills/3-solutioning/bmad-create-architecture",
         "./src/bmm-skills/3-solutioning/bmad-check-implementation-readiness",
         "./src/bmm-skills/3-solutioning/bmad-create-epics-and-stories",
         "./src/bmm-skills/3-solutioning/bmad-generate-project-context",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.10.1-next.2",
+  "version": "6.10.1-next.20",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,12 +40,13 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run test:renderer && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:renderer && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:renderer": "node test/test-quick-dev-renderer.js",
     "test:skills": "node test/test-validate-skills.js",
     "test:urls": "node test/test-parse-source-urls.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/removals.txt

@@ -68,3 +68,8 @@ bmad-investigate
 # bmad-auto-setup: renamed to bmad-loop-setup as part of the bmad-auto ->
 # bmad-loop module rename (BMad Automator's replacement).
 bmad-auto-setup
+
+# Removed skills (core streamline, post-v6.10.0)
+# bmad-index-docs, bmad-shard-doc: retired outright.
+bmad-index-docs
+bmad-shard-doc

package/src/bmm-skills/1-analysis/bmad-agent-analyst/customize.toml

@@ -62,17 +62,32 @@ skill = "bmad-brainstorming"
 [[agent.menu]]
 code = "MR"
 description = "Market analysis, competitive landscape, customer needs and trends"
-skill = "bmad-market-research"
+prompt = "Invoke the `bmad-deep-recon` skill with the market research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "DR"
 description = "Industry domain deep dive, subject matter expertise and terminology"
-skill = "bmad-domain-research"
+prompt = "Invoke the `bmad-deep-recon` skill with the domain research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "TR"
-description = "Technical feasibility, architecture options and implementation approaches"
-skill = "bmad-technical-research"
+description = "Technical landscape, architecture patterns and implementation reality"
+prompt = "Invoke the `bmad-deep-recon` skill with the technical research type pre-selected (forwarded activation: skip type inference)."
+
+[[agent.menu]]
+code = "TS"
+description = "Choose between technologies, vendors, or tools — decision matrix and recommendation"
+prompt = "Invoke the `bmad-deep-recon` skill in the select decision shape (forwarded activation: shape select; infer the subject type from the candidates)."
+
+[[agent.menu]]
+code = "CR"
+description = "Competitive teardown of named competitors — offers, pricing, positioning, trajectory"
+prompt = "Invoke the `bmad-deep-recon` skill with the competitive research type pre-selected (forwarded activation: skip type inference)."
+
+[[agent.menu]]
+code = "UV"
+description = "User-voice research — reviews, communities, jobs-to-be-done"
+prompt = "Invoke the `bmad-deep-recon` skill with the user-voice research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "CB"

package/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md

@@ -64,7 +64,7 @@ Omit keys for artifacts that were not produced.
 
 ## Discovery
 
-Conversationally surface what the user brings, why this brief exists, the domain, and the form-factor (mobile / web / desktop / multi-surface / hardware / API — what *is* this thing) — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. During the dump, spawn web-research subagents to ground the picture — landscape, comparables, current state — AI especially, where training data ages by the week. Subagent searches; parent gets a digest. Deep work (full market sizing, exhaustive teardowns) → suggest `bmad-market-research` or `bmad-domain-research`.
+Conversationally surface what the user brings, why this brief exists, the domain, and the form-factor (mobile / web / desktop / multi-surface / hardware / API — what *is* this thing) — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. During the dump, spawn web-research subagents to ground the picture — landscape, comparables, current state — AI especially, where training data ages by the week. Subagent searches; parent gets a digest. Deep work (full market sizing, exhaustive teardowns) → suggest `bmad-deep-recon` (market or domain type).
 
 Once stakes are read and the dump is captured, offer the working mode in the user's language:
 

package/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml

@@ -53,7 +53,7 @@ run_folder_pattern = "brief-{project_name}-{date}"
 # findings before the user sees the draft. Encodes standards, not options.
 #
 # Examples:
-#   "skill:bmad-editorial-review-prose"
+#   "skill:bmad-review lenses=structure,prose"
 #   "file:{project-root}/_bmad/style-guides/company-voice.md"
 #   "Convert all dates to ISO 8601 format."
 #
@@ -64,9 +64,11 @@ run_folder_pattern = "brief-{project_name}-{date}"
 #
 # Override the array in team/user TOML to add additional standards. Append-only:
 # base entries cannot be removed or replaced (resolver has no removal mechanism).
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge

package/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md

@@ -15,6 +15,8 @@ You are a master facilitator and coach helping the user create, edit, or validat
 
 ## On Activation
 
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.

package/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml

@@ -71,7 +71,7 @@ run_folder_pattern = "prd-{project_name}-{date}"
 # findings before the user sees the draft. Encodes standards, not options.
 #
 # Examples:
-#   "skill:bmad-editorial-review-prose"
+#   "skill:bmad-review lenses=structure,prose"
 #   "file:{project-root}/_bmad/style-guides/company-voice.md"
 #   "Convert all dates to ISO 8601 format."
 #
@@ -82,9 +82,11 @@ run_folder_pattern = "prd-{project_name}-{date}"
 #
 # Override the array in team/user TOML to add additional standards. Append-only:
 # base entries cannot be removed or replaced (resolver has no removal mechanism).
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge

package/src/{core-skills → bmm-skills/2-plan-workflows}/bmad-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-spec
-description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
+description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", "update the spec", or "break this into stories".
 ---
 
 # BMad Spec
@@ -20,7 +20,7 @@ Multiple skills may call to update the same spec over time.
 
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
-3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
+3. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}`, `{output_folder}` (under `core`), and `{date}`.
 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
 
 Run `{workflow.activation_steps_append}`.
@@ -46,6 +46,7 @@ Inside the spec folder:
   SPEC.md                  ← uppercase, the kernel — DERIVED from .memlog.md, never hand-edited
   <companion-1>.md         ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
   <companion-2>.md
+  stories.yaml             ← optional, written only by Story Breakdown — fixed name, never in companions:
   .memlog.md               ← canonical, append-only memory; what SPEC.md is distilled from
 ```
 
@@ -99,6 +100,8 @@ Two rules govern companions:
 
 Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs are listed as **adopted companions**, never duplicated into SPEC.md or a spec-authored companion.
 
+`stories.yaml`, when produced, is spec-authored but deliberately **not** a companion — see Story Breakdown below.
+
 ## Spec Law
 
 Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
@@ -126,9 +129,21 @@ Record the verdict for each pass to `.memlog.md` (`append --type event`). In int
 
 When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
 
+## Story Breakdown (optional, interactive-only)
+
+Requires `SPEC.md` on disk — run the normal Operation first if it doesn't exist yet. Headless runs never do this, even when the invocation text asks for it: if mode detection (On Activation, step 4) resolved headless, skip this section entirely and proceed with the normal headless response. In interactive mode, offer it at most once per run when the input reads as multiple independently shippable slices; a decline ends the offer for this run, not forever. Also run it on direct request ("break this into stories") whenever `SPEC.md` exists. When a spec update runs and `stories.yaml` exists, check the story descriptions against the updated spec; if any no longer matches, say so and offer to re-run Story Breakdown. The update itself never rewrites `stories.yaml`.
+
+Either way, walk the capabilities and constraints with the user and propose a story per independently reviewable slice — this is a conversation, not a silent render. For each story, ask the user for `spec_checkpoint`, `done_checkpoint`, and any `invoke_dev_with` note rather than defaulting them silently; capturing that human judgment is what the fields are for. If the conversation surfaces load-bearing detail beyond dispatch notes (a constraint, a design decision), route it into SPEC.md or a companion — `invoke_dev_with` carries dispatch notes only (Spec Law rule 7 still applies).
+
+The output is `stories.yaml`, a sibling of `SPEC.md` inside the spec folder, discovered by that fixed name — same convention as `SPEC.md` and `.memlog.md`. Never list it in `companions:` and never point a frontmatter key at it: companions carry the what-to-build contract every consumer reads; `stories.yaml` is input for whichever tool dispatches the stories.
+
+Field definitions, the validity rules, and a worked example live in `assets/stories-schema.md`. Before writing or re-writing the file, check every entry against those rules; fix violations rather than presenting a file that fails them. Record the check's verdict to `.memlog.md` (`append --type event`), the same discipline as Self-Validate.
+
+Derive `stories.yaml` from `.memlog.md` exactly like any other spec-authored artifact: log each proposed story (`--type decision`) as the user agrees to it, then render. On a later run against the same spec folder, re-derive the same way, handling ids per the schema's update semantics.
+
 ## Output
 
-**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
+**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. Name the story count too if `stories.yaml` was written this run. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
 
 **Headless** — return JSON per `assets/headless-schemas.md`.
 

package/src/{core-skills → bmm-skills/2-plan-workflows}/bmad-spec/assets/spec-template.md

@@ -4,7 +4,7 @@ companions: []     # files downstream MUST read alongside SPEC.md. Paths may poi
 sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never the memlog.
 ---
 
-> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
+> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.
 
 # {Spec Title}
 

package/src/bmm-skills/2-plan-workflows/bmad-spec/assets/stories-schema.md

@@ -0,0 +1,44 @@
+# Stories schema
+
+`stories.yaml` — the optional output of Story Breakdown: a top-level YAML list, one entry per story, in execution order — stories run top to bottom. Sibling of `SPEC.md`, discovered by its fixed filename (same convention as `SPEC.md` and `.memlog.md`); never listed in `companions:`, never referenced from frontmatter.
+
+## Fields
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `id` | string | yes | Identity, unique within the file. Compared for equality and used as a filename prefix; carries no other meaning. Use unpadded integers (`"1"`), or composites (`"3-2"`) when the epic sits inside a larger project spec. No zero-padding — execution order is the list order, not filename sort. Pinned once the story's spec file exists (see Update semantics); until then it may be renumbered. |
+| `title` | string, one line | yes | Display name; becomes the story's heading downstream. |
+| `description` | string | yes | What this story covers, pointing into `SPEC.md` — not a story spec. Keep it to two sentences; a writing rule, not something tooling enforces. |
+| `spec_checkpoint` | boolean | no (default `false`) | Set by the human at breakdown time; read only by the dispatching caller, never by the implementing dev skill. When true, a human reviews the story spec between planning and implementation. |
+| `done_checkpoint` | boolean | no (default `false`) | Caller-only, like `spec_checkpoint`. When true, dispatch pauses after this story completes, before anything further runs. |
+| `invoke_dev_with` | string | no (default `""`) | Free text appended verbatim to the prompt that dispatches this story; the implementing dev skill reads it as part of its prompt, and nothing else interprets it. If the text needs structure, put it inside the string. Which dev skill to invoke is the caller's configuration, never data in this file. |
+
+## Validity rules
+
+1. Every entry parses with all required fields; ids unique.
+2. Ids are prefix-free under the `<id>-` filename-matching convention: no id may equal another id plus a dash-suffix (`"3"` and `"3-2"` cannot coexist).
+3. No `status` field, ever.
+4. Ids are YAML strings, always quoted, containing only letters, digits, and dashes. An unquoted `id: 1` parses as a number and breaks string comparison; characters like `/` or `*` break the filename match.
+
+## Example
+
+```yaml
+- id: "1"
+  title: Add rate limiting to the public API
+  description: >-
+    Introduce a token-bucket limiter in front of the public endpoints;
+    return 429 with a Retry-After header on limit breach.
+  spec_checkpoint: true
+  invoke_dev_with: >-
+    Rate limit state must be shared across instances; use the existing
+    Redis client, not in-process memory.
+- id: "2"
+  title: Expose limiter metrics to the ops dashboard
+  description: >-
+    Emit per-route accept/reject counters the existing dashboard can
+    scrape; no new dashboard panels in this story.
+```
+
+## Update semantics
+
+Updates to `stories.yaml` go through Story Breakdown: append the change to `.memlog.md`, then re-derive. An id is pinned once its story spec file exists (any `stories/<id>-*.md` in the spec folder): a pinned story keeps its id through edits, its removal retires the id, and retired ids are never reassigned. Stories with no spec file yet may be renumbered, reordered, or removed freely on re-derive — typically so ids keep following list order. Never give a story an id that collides with a `stories/` file belonging to a different story.

package/src/{core-skills → bmm-skills/2-plan-workflows}/bmad-spec/customize.toml

@@ -38,10 +38,9 @@ spec_template = "assets/spec-template.md"
 # Uppercase by convention to signal "the central source of truth."
 spec_filename = "SPEC.md"
 
-# Output path for spec folders. Lands directly under {output_folder}
-# so bmad-spec works in core-only installs and matches the
-# long-term BMad direction of grouping artifacts as siblings under
-# {output_folder}/<type>/ rather than nested inside planning vs
+# Output path for spec folders. Lands directly under {output_folder},
+# matching the long-term BMad direction of grouping artifacts as siblings
+# under {output_folder}/<type>/ rather than nested inside planning vs
 # implementation folders.
 spec_output_path = "{output_folder}/specs"
 

package/src/bmm-skills/2-plan-workflows/bmad-ux/customize.toml

@@ -78,9 +78,11 @@ creative_tools = [
 # Polish passes applied to DESIGN.md and EXPERIENCE.md at finalize.
 # Entries: `skill:NAME`, `file:PATH`, or plain text directive.
 # Suggested order: structural → content/voice → prose mechanics.
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # Information retrieval registry. Consulted on demand when the conversation

package/src/bmm-skills/3-solutioning/bmad-architecture/SKILL.md

@@ -48,10 +48,10 @@ Writes go through the shared script (don't read the file back except on resume):
 
 ## On Activation
 
-**Forwarded activation:** if a caller (e.g. the `bmad-create-architecture` shim) invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
 
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand.
-2. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml`) for `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`; missing keys take neutral defaults, never block.
+2. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}` (under `core`), `{planning_artifacts}` (under `modules.bmm`), and `{date}`; missing keys take neutral defaults, never block.
 3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead.
 4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart.
 5. Interactive create: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see *How you work*) — before any drafting; default to Coaching unless the user asks for speed.

package/src/bmm-skills/3-solutioning/bmad-architecture/customize.toml

@@ -59,9 +59,11 @@ run_folder_pattern = "architecture-{project_name}-{date}"
 # short, structured outputs, which are terse and carry decisions in AD-n blocks and diagrams by
 # design. Each entry is a `skill:`, `file:`, or plain-text directive applied before the user sees
 # the polished draft. Suggested order: structural passes first, prose mechanics last. Append-only.
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge bases, MCP tools, or

package/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml

@@ -48,6 +48,9 @@ principles = [
   "No task complete without passing tests.",
   "Red, green, refactor — in that order.",
   "Tasks executed in the sequence written.",
+  "Never add epic or story references as inline code comments (e.g. # Epic: X, # Story: PROJ-42).",
+  "Code comments explain why, not what — no AI workflow metadata, planning refs, or story tracking in source code.",
+  "Generated code must be production-ready: clean, minimal, and free of AI-generated noise.",
 ]
 
 # Capabilities menu. Overrides merge by `code`: matching codes replace the item

package/src/bmm-skills/4-implementation/bmad-code-review/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: bmad-code-review
-description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+description: 'Adversarial code review using parallel review layers and structured triage. Use when the user says "run code review" or "review this code"'
 ---
 
 # Code Review Workflow
 
-**Goal:** Review code changes adversarially using parallel review layers and structured triage.
-
-**Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.
+**Goal:** Review code changes adversarially. No noise, no filler.
 
 Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
 If you need an explicit user instruction to run them, ask once now for the whole workflow run.

package/src/bmm-skills/4-implementation/bmad-code-review/customize.toml

@@ -39,3 +39,55 @@ persistent_facts = [
 # Leave empty for no custom post-completion behavior.
 
 on_complete = ""
+
+# Review layers for the review step. `instruction` is the layer's whole
+# execution recipe — subagents by default, but an override may run anything
+# (e.g. an external reviewer via bash). {diff_output} and {spec_file} are
+# substituted at run time. `when` (optional) gates a layer; empty
+# `instruction` disables it.
+
+[[workflow.review_layers]]
+id = "blind-hunter"
+name = "Blind Hunter"
+instruction = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> Invoke the `bmad-review` skill with only the `adversarial` lens on this diff:
+>
+> {diff_output}
+"""
+
+[[workflow.review_layers]]
+id = "edge-case-hunter"
+name = "Edge Case Hunter"
+instruction = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> Invoke the `bmad-review` skill with only the `edge-case-hunter` lens on this diff:
+>
+> {diff_output}
+"""
+
+[[workflow.review_layers]]
+id = "verification-gap"
+name = "Verification Gap Reviewer"
+instruction = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> Invoke the `bmad-review` skill with only the `verification-gap` lens on this diff:
+>
+> {diff_output}
+"""
+
+[[workflow.review_layers]]
+id = "acceptance-auditor"
+name = "Acceptance Auditor"
+when = 'Only when {review_mode} = "full".'
+instruction = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> You are an Acceptance Auditor. Review the provided diff against `{spec_file}` and any loaded context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+>
+> Diff:
+> {diff_output}
+"""

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-01-gather-context.md

@@ -79,7 +79,6 @@ story_key: '' # set at runtime when discovered from sprint status
 
 Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
 
-
 ## NEXT
 
 Read fully and follow `./step-02-review.md`

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-02-review.md

@@ -8,38 +8,24 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - All review subagents must run at the same model capability as the current session.
+- Run subagents synchronously: launch them together, then wait for all results before continuing.
 
 ## INSTRUCTIONS
 
-1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+1. The review layers are `{workflow.review_layers}`, resolved during activation.
 
-2. Launch Blind Hunter, Edge Case Hunter, and Verification Gap Reviewer in parallel without prior conversation context. If `{review_mode}` = `"full"`, include the Acceptance Auditor in the same parallel launch. If subagents are not available, generate prompt files in `{implementation_artifacts}` for each applicable reviewer role and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
+2. For each layer in `{workflow.review_layers}`:
+   - `instruction` empty or missing → drop the layer silently (an override disabled it).
+   - `when` condition present and not satisfied by the current context (`{review_mode}`, `{spec_file}`) → drop the layer and tell the user, e.g. "Acceptance Auditor skipped — no spec file provided."
+   - otherwise → the layer is active.
 
-   - **Blind Hunter** — prompt:
-     > Invoke the `bmad-review-adversarial-general` skill on this diff:
-     >
-     > {diff_output}
+   If no layer is active, HALT with status `blocked` and blocking condition `no active review layers`.
 
-   - **Edge Case Hunter** — prompt:
-     > Invoke the `bmad-review-edge-case-hunter` skill on this diff:
-     >
-     > {diff_output}
+3. Execute all active layers in parallel wherever their execution methods allow: substitute the runtime placeholders (`{diff_output}`, `{spec_file}`) into each layer's `instruction`, then follow it verbatim. If a layer's instruction requires subagents and subagents are not available, generate prompt files in `{implementation_artifacts}` for each such layer and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those layers' findings and resume from this point.
 
-   - **Verification Gap Reviewer** — prompt:
-     > Invoke the `bmad-review-verification-gap` skill on this diff:
-     >
-     > {diff_output}
-
-   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — prompt:
-     > You are an Acceptance Auditor. Review the provided diff against `{spec_file}` and any loaded context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
-     >
-     > Diff:
-     > {diff_output}
-
-3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
-
-4. Collect all findings from the completed layers.
+4. **Layer failure handling**: If any layer fails, times out, or returns empty results, append the layer's `name` to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
 
+5. Collect all findings from the completed layers, keeping track of each finding's originating layer `id`.
 
 ## NEXT
 

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -11,15 +11,15 @@
 
 1. **Normalize** findings from all layers into a unified list where each finding has:
    - `id` -- sequential integer
-   - `source` -- `blind`, `edge`, `vgap`, `auditor`, or merged sources (e.g., `blind+edge`)
+   - `source` -- the `id` of the layer that produced the finding (e.g., `blind-hunter`), or merged sources joined with `+` (e.g., `blind-hunter+edge-case-hunter`)
    - `title` -- one-line summary
    - `detail` -- full description
    - `location` -- file and line reference (if available)
 
 2. **Deduplicate.** Deduplicate only findings with the same claim and same required action. If two or more findings meet both conditions, merge them into one:
-   - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose).
+   - Use the most specific finding as the base (prefer findings with a precise location over prose-only findings).
    - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
-   - Set `source` to the merged sources (e.g., `blind+edge`).
+   - Set `source` to the merged sources (e.g., `blind-hunter+edge-case-hunter`).
 
 3. Then evaluate each remaining finding independently. Do not reject a finding because a related finding was rejected.
 
@@ -45,7 +45,6 @@
 
 9. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
-
 ## NEXT
 
 Read fully and follow `./step-04-present.md`