bmad-method 6.10.1-next.3 → 6.10.1-next.30

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.3",
+  "version": "6.10.1-next.30",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,12 +40,15 @@
     "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:site-url && npm run test:install && npm run test:urls && npm run test:renderer && npm run test:dev-auto-contract && 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:site-url && npm run test:channels && npm run test:renderer && npm run test:dev-auto-contract && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
+    "test:dev-auto-contract": "node test/test-dev-auto-contract.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-quick-dev-renderer.js && node test/test-dev-auto-renderer.js",
+    "test:site-url": "node test/test-site-url.mjs",
     "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/SKILL.md

@@ -87,4 +87,4 @@ Outcomes, in order:
 - **Key-screen mocks rendered.** Key-screens tool → `.working/` for surfaces where layout drives behavior or anchors visual language.
 - **Mock coverage confirmed.** Walk every IA surface; classify *mocked* vs *spine-only*. Ask: *"These will be built from spine tables alone — any need a visual reference?"* Render more if named; log spine-only choices.
 - **Layout extracted, artifacts promoted.** Distill subagent re-reads each `.working/` and `imports/` artifact; lifts visual decisions into DESIGN.md and behavioral decisions into EXPERIENCE.md. Promote `.working/` keepers to `mockups/` (HTML) or `wireframes/` (Excalidraw); imports stay. Inline relative links at relevant spine sections; state spines-win-on-conflict once.
-- **Polished, handed off, closed.** Apply `{workflow.doc_standards}` in order. Execute `{workflow.external_handoffs}`; surface URLs. Set both files' `status: final`, `updated: {date}`. Log finalization via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type event --text "spines finalized"`. Share paths. Common next: `bmad-architecture`, `bmad-create-epics-and-stories`, `bmad-dev-story`. Run `{workflow.on_complete}`.
+- **Polished, handed off, closed.** Apply `{workflow.doc_standards}` in order. Execute `{workflow.external_handoffs}`; surface URLs. Set both files' `status: final`, `updated: {date}`. Log finalization via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type event --text "spines finalized"`. Share paths. Common next: `bmad-architecture`, `bmad-create-epics-and-stories`, `bmad-quick-dev`. Run `{workflow.on_complete}`.

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.
@@ -73,7 +73,7 @@ Walk the sequence; reviewer fixes land before polish.
 4. **Triage.** Open questions and `[ASSUMPTION]` tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog.
 5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any *additional* human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine.
 6. **External handoffs.** Run `{workflow.external_handoffs}`; surface returned URLs/IDs. Offer to invoke the `bmad-spec` skill to adopt the spine as a companion, keeping `AD` IDs stable so downstream can cite them.
-7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-create-story`; or invoke `bmad-help` to route.
+7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-quick-dev`; or invoke `bmad-help` to route.
 8. Run `{workflow.on_complete}`.
 
 ## Update

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,20 +48,18 @@ 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
 # in place, new codes append. Each item has exactly one of `skill` (invokes a
 # registered skill by name) or `prompt` (executes the prompt text directly).
 
-[[agent.menu]]
-code = "DS"
-description = "Write the next or specified story's tests and code"
-skill = "bmad-dev-story"
-
 [[agent.menu]]
 code = "QD"
-description = "Unified quick flow — clarify intent, plan, implement, review, present"
+description = "Implement a feature, fix, or story"
 skill = "bmad-quick-dev"
 
 [[agent.menu]]
@@ -79,11 +77,6 @@ code = "SP"
 description = "Generate or update the sprint plan that sequences tasks for implementation"
 skill = "bmad-sprint-planning"
 
-[[agent.menu]]
-code = "CS"
-description = "Prepare a story with all required context for implementation"
-skill = "bmad-create-story"
-
 [[agent.menu]]
 code = "ER"
 description = "Party mode review of all work completed across an epic"

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,71 @@ 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 context-free subagent with this prompt:
+
+Read `{skill-root}/review-prompts/adversarial.md` completely and follow it as your review instructions.
+
+Review content:
+
+{diff_output}
+
+Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "edge-case-hunter"
+name = "Edge Case Hunter"
+instruction = """
+Launch a context-free subagent with this prompt:
+
+Read `{skill-root}/review-prompts/edge-case-hunter.md` completely and follow it as your review instructions.
+
+Review content:
+
+{diff_output}
+
+Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "verification-gap"
+name = "Verification Gap Reviewer"
+instruction = """
+Launch a context-free subagent with this prompt:
+
+Read `{skill-root}/review-prompts/verification-gap.md` completely and follow it as your review instructions.
+
+Review content:
+
+{diff_output}
+
+Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "acceptance-auditor"
+name = "Acceptance Auditor"
+when = 'Only when {review_mode} = "full".'
+instruction = """
+Launch a subagent 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/{core-skills/bmad-review-adversarial-general/SKILL.md → bmm-skills/4-implementation/bmad-code-review/review-prompts/adversarial.md}

@@ -1,8 +1,3 @@
----
-name: bmad-review-adversarial-general
-description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
----
-
 # Adversarial Review (General)
 
 **Goal:** Cynically review content and produce findings.
@@ -18,7 +13,7 @@ description: 'Perform a Cynical Review and produce a findings report. Use when t
 
 ### Step 1: Receive Content
 
-- Load the content to review from provided input or context
+- Load the content to review from the parent message that launched you (not from this instruction file)
 - If content to review is empty, ask for clarification and abort
 - Identify content type (diff, branch, uncommitted changes, document, etc.)
 
@@ -35,3 +30,7 @@ Output findings as a Markdown list: descriptions only, no severity, priority, or
 
 - HALT if zero findings — this is suspicious, re-analyze or ask for guidance
 - HALT if content is empty or unreadable
+
+## CONTENT SOURCE
+
+Load the review target from the parent message, or from a trailing `## REVIEW TARGET` section if present (offline fallback). This file has no `{review_content}` slot. If neither supplies content, treat content as empty and follow the empty-content halt rules above.