bmad-method 6.7.1 → 6.8.0

package/.claude-plugin/marketplace.json

@@ -20,7 +20,7 @@
       "skills": [
         "./src/core-skills/bmad-help",
         "./src/core-skills/bmad-brainstorming",
-        "./src/core-skills/bmad-distillator",
+        "./src/core-skills/bmad-spec",
         "./src/core-skills/bmad-party-mode",
         "./src/core-skills/bmad-shard-doc",
         "./src/core-skills/bmad-advanced-elicitation",

package/README.md

@@ -77,6 +77,16 @@ BMad Method extends with official modules for specialized domains. Available dur
 | **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)**                        | Game development workflows (Unity, Unreal, Godot) |
 | **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking        |
 
+## Web Bundles
+
+V4 shipped web bundles. V6 brings them back, new and improved.
+
+Web bundles package selected BMad skills for installation as **Google Gemini Gems** and **ChatGPT Custom GPTs**. Use them to do the upfront planning work (brainstorming, product briefs, PRDs, PRFAQs, UX specs, market and industry research) in your web LLM subscription, then bring the polished artifacts into your IDE for implementation. Planning runs on a flat-rate subscription instead of metered IDE tokens, which is a meaningful cost saver on longer engagements. Choose the best model available to you in Gemini or ChatGPT.
+
+Current shelf: brainstorming, product brief, PRFAQ, PRD, UX, market & industry research.
+
+**Browse and install at [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**. One card per bundle, inline install steps for Gemini and ChatGPT, one-click ZIP download. See [the web bundles guide](https://docs.bmad-method.org/explanation/web-bundles/) for the concept.
+
 ## Documentation
 
 [BMad Method Docs Site](https://docs.bmad-method.org) — Tutorials, guides, concepts, and reference

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.7.1",
+  "version": "6.8.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -31,6 +31,7 @@
     "docs:fix-links": "node tools/fix-doc-links.js",
     "docs:preview": "astro preview --root website",
     "docs:validate-links": "node tools/validate-doc-links.js",
+    "docs:validate-sidebar": "node tools/validate-sidebar-order.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
@@ -39,7 +40,7 @@
     "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",
+    "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",
     "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 lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",

package/removals.txt

@@ -52,3 +52,11 @@ bmad-bmm-sprint-planning
 bmad-bmm-sprint-status
 bmad-bmm-technical-research
 bmad-bmm-validate-prd
+
+# Removed skills (post-v6.7.x)
+# bmad-distillator: superseded by bmad-spec (universal intent distiller with
+# preservation-validated contract for downstream skills).
+bmad-distillator
+# bmad-create-ux-design: renamed to bmad-ux (spine-based skill with separate
+# DESIGN.md and EXPERIENCE.md outputs).
+bmad-create-ux-design

package/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.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 been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Mary, let's brainstorm"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.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 been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Paige, let's document this codebase"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/1-analysis/bmad-document-project/SKILL.md

@@ -55,7 +55,7 @@ Greet `{user_name}` (if you have not already), speaking in `{communication_langu
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+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 been completed.
 
 ## Execution
 

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

@@ -65,7 +65,7 @@ Greet `{user_name}`, speaking in `{communication_language}`. Be warm but efficie
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Continue below.
+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 been completed.
 
 ## Pre-workflow Setup
 

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

@@ -21,7 +21,10 @@ At the opening greeting, let the user know they can invoke `bmad-party-mode` for
 4. `{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 in `## Discovery`, org tools preferred when their directive matches. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant.
 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
 6. Greet `{user_name}` in `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`.
-7. Execute each entry in `{workflow.activation_steps_append}` in order.
+
+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 been completed.
 
 ## Intent Operating Modes
 
@@ -61,7 +64,7 @@ Omit keys for artifacts that were not produced.
 
 ## Discovery
 
-Conversationally surface what the user brings, why this brief exists, and the domain — 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-market-research` or `bmad-domain-research`.
 
 Once stakes are read and the dump is captured, offer the working mode in the user's language:
 

package/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+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 been completed.
 
 ## QUICK TOPIC DISCOVERY
 

package/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+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 been completed.
 
 ## QUICK TOPIC DISCOVERY
 

package/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+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 been completed.
 
 ## QUICK TOPIC DISCOVERY
 

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

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.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 been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey John, let's write the PRD"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.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 been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Sally, let's design the UX"), skip the menu and dispatch that item directly after greeting.

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

@@ -57,4 +57,4 @@ principles = [
 [[agent.menu]]
 code = "CU"
 description = "Guidance through realizing the plan for your UX to inform architecture and implementation"
-skill = "bmad-create-ux-design"
+skill = "bmad-ux"

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

@@ -20,7 +20,10 @@ You are a master facilitator and coach helping the user create, edit, or validat
 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.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
 5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
-6. Run `{workflow.activation_steps_append}`.
+
+Run `{workflow.activation_steps_append}`.
+
+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 been completed.
 
 ## Intent Modes
 
@@ -45,13 +48,15 @@ Order: **Brain dump → Stakes calibration → Working mode → mode-scoped work
 **Working mode.** Offer the choice in the user's language:
 
 - **Fast path** — I batch remaining gaps into one or two consolidated questions, then draft the full PRD with `[ASSUMPTION]` tags where I inferred. You review and we iterate. The initial quality depends on how much you gave me upfront.
-- **Coaching path** — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: **Vision + Features** (capability-first — for enterprise, dev products, internal tools, anyone who thinks in features), **Personas + Journeys** (user-first — for consumer, UX-heavy, multi-stakeholder products), or *let me suggest* based on what I heard. The chosen entry sets the section order.
+- **Coaching path** — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: **Vision + Features** (capability-first — for enterprise, dev products, internal tools, anyone who thinks in features), **Journey-led** (user-first — for consumer, UX-heavy, multi-stakeholder products; journeys with named protagonists carry persona context inline, no standalone persona section), or *let me suggest* based on what I heard. The chosen entry sets the section order.
 
 The workspace persists; stop and resume freely.
 
 **Concern scan.** As you read what the user gave you, name the concerns this product actually carries — compliance, integration density, operational SLAs, hardware constraints, public-API contracts, monetization, data governance, whatever applies. The list is open; recognize what's there, do not classify into a fixed shape. These concerns drive which template sections to pull in from the Adapt-In Menu and which to invent when no cluster names them.
 
-**User Journeys are captured, not authored.** When UJs are warranted (consumer / multi-stakeholder B2B / meaningful UX — drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, pure technical PRDs), prompt the user to narrate a real session — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm.
+**Form-factor.** If not stated in sources, probe — mobile / web / desktop / multi-surface / hardware / API.
+
+**User Journeys are captured, not authored.** When UJs are warranted (consumer / multi-stakeholder B2B / meaningful UX — drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, pure technical PRDs), prompt the user to narrate a real session with a named protagonist (Mary, mom of three — not "the user") — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm. Persona context lives inline at the moments that matter; no standalone persona section.
 
 ## PRD Discipline
 
@@ -83,5 +88,5 @@ Tell the user the sequence in one sentence, then walk it. Polish goes last so it
 4. **Triage open items.** All Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts. Phase-blockers (would make the PRD unsafe for UX/architecture/epics) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged to `.decision-log.md`. If phase-blocker count is high, flag it.
 5. **Polish.** Apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` in declared order (structural passes before prose — prose should not polish soon-to-be-cut text). Parallelize across documents, sequential within.
 6. **External handoffs.** Execute `{workflow.external_handoffs}`; surface returned URLs/IDs. Skip and flag unavailable tools.
-7. **Close.** Set `prd.md` frontmatter `status: final` and `updated` to `{date}` so future invocations distinguish this PRD from in-progress drafts. Record finalization to `.decision-log.md`. Share artifact paths. Common next: `bmad-create-ux-design`, `bmad-create-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing.
+7. **Close.** Set `prd.md` frontmatter `status: final` and `updated` to `{date}` so future invocations distinguish this PRD from in-progress drafts. Record finalization to `.decision-log.md`. Share artifact paths. Common next: `bmad-ux`, `bmad-create-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing.
 8. Run `{workflow.on_complete}` if non-empty.

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

@@ -20,16 +20,13 @@ updated: {YYYY-MM-DD}
 
 ## 2. Target User
 
-### 2.1 Primary Persona
-[Vivid but tight. Who they are, how this product fits their context.]
+### 2.1 Jobs To Be Done
+[Bulleted. Emotional, social, functional, contextual — whichever apply. Even "this is for me as the builder" is a valid framing for a hobby project.]
 
-### 2.2 Jobs To Be Done
-[Bulleted. Emotional, social, functional, contextual — whichever apply. Even "this is for me as the builder" is a valid persona for a hobby project.]
-
-### 2.3 Non-Users (v1) *(add when the audience boundary is non-obvious)*
+### 2.2 Non-Users (v1) *(add when the audience boundary is non-obvious)*
 [Who this is explicitly not for in v1.]
 
-### 2.4 Key User Journeys
+### 2.3 Key User Journeys
 *Named-persona narratives the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. If a UX doc already exists, mirror its UJ IDs here and point to the source.*
 
 **Default shape:** a named scene with entry state, path, climax, and resolution. Each beat forces specificity the team would otherwise leave implicit — auth assumptions, screen order, what tells the user value landed. Read together as a short narrative; the example below shows the form.

package/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-validation-checklist.md

@@ -107,7 +107,7 @@ Look for:
 - Glossary present; every domain noun used identically across FRs, UJs, SM definitions.
 - FR / UJ / SM IDs contiguous, unique, and cross-references that resolve.
 - Each section makes sense pulled out alone — cross-references via Glossary terms, not "see above."
-- UJs each name a persona from §2 by exact label; no floating UJs.
+- UJs each have a named protagonist; no floating UJs.
 
 For standalone PRDs (no downstream), this dimension matters less — say so.
 
@@ -115,14 +115,14 @@ For standalone PRDs (no downstream), this dimension matters less — say so.
 
 Has the PRD been forced into a shape that doesn't match the product?
 
-- Consumer product / multi-stakeholder B2B / meaningful UX → UJs and personas are load-bearing.
+- Consumer product / multi-stakeholder B2B / meaningful UX → UJs with named protagonists are load-bearing.
 - Internal tool, single-operator role → capability spec shape; UJs may be overhead; SMs may be operational rather than user-facing.
 - Regulatory or compliance update → constraint traceability is non-negotiable; UJs may be irrelevant.
 - Hobby / solo → rigor light, substance bar still applies.
 - Brownfield → existing-code references must be accurate; new UJs and existing UJs must be distinguished.
 - Chain-top (feeds UX → architecture → stories) → downstream usability matters more; standalone PRDs can be lighter on traceability.
 
-Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no personas or UJs).
+Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no UJs).
 
 ## Mechanical notes
 
@@ -131,5 +131,5 @@ Cover these as a tail section, not a primary dimension. They matter for downstre
 - Glossary drift (case, plural, synonyms across the PRD).
 - ID continuity (gaps, duplicates, unresolved cross-references).
 - Assumptions Index roundtrip (every inline `[ASSUMPTION]` indexed; index entries all appear inline).
-- UJ persona linkage (each UJ names a defined persona by exact label).
+- UJ protagonist naming (each UJ has a named protagonist carrying context inline).
 - Required sections present for the agreed stakes and product type.

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

@@ -18,11 +18,11 @@ When ambiguous, default to interactive.
 The caller passes inputs in their first message (free-form structured payload; no fixed schema, but every field below should be present when applicable):
 
 - `intent` — `"create"`, `"update"`, or `"validate"`. If absent, infer from the artifact set.
-- For **Create**: a brief or product spec the LLM works from (plain text, file path, or URL), plus any persona/scope notes; `doc_workspace` if a specific run folder is required (otherwise the workflow binds the default).
+- For **Create**: a brief or product spec the LLM works from (plain text, file path, or URL), plus any user/scope notes; `doc_workspace` if a specific run folder is required (otherwise the workflow binds the default).
 - For **Update**: the existing `prd.md` path (or a workspace path that contains one), and a change signal (the request: what to change and why).
 - For **Validate**: the existing `prd.md` path (or workspace path), and optionally a checklist override path. Workspace defaults to the PRD's containing directory.
 
-Anything the caller does not provide is either inferred from inputs/workspace or recorded as `assumptions[]` / `open_questions[]` in the JSON status. Do not invent persona detail, success metrics, or scope decisions to fill gaps — record them.
+Anything the caller does not provide is either inferred from inputs/workspace or recorded as `assumptions[]` / `open_questions[]` in the JSON status. Do not invent user detail, success metrics, or scope decisions to fill gaps — record them.
 
 ## General
 

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

@@ -0,0 +1,90 @@
+---
+name: bmad-ux
+description: Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"
+---
+# BMad UX
+
+## Overview
+
+You are a master UX facilitator. **Elicit and capture** the user's vision, never impose yours. Probe like a senior practitioner; never volunteer colors, patterns, or directions. Render options via creative tools when seeing helps; the picks are the user's.
+
+Produce two peer contracts: **`DESIGN.md`** (visual identity per the [Google Labs spec](https://github.com/google-labs-code/design.md) — owns *how it looks*) and **`EXPERIENCE.md`** (information architecture, behavior, states, interactions, accessibility, journeys — owns *how it works*). EXPERIENCE.md cross-references DESIGN.md tokens by name using `{path.to.token}` syntax. Both spines win on conflict with any mock, wireframe, or import.
+
+## The DESIGN.md spine
+
+Per the [Google Labs spec](https://github.com/google-labs-code/design.md). YAML frontmatter tokens (**colors** · **typography** · **rounded** · **spacing** · **components**) + markdown body in canonical order: **Brand & Style** · **Colors** · **Typography** · **Layout & Spacing** · **Elevation & Depth** · **Shapes** · **Components** · **Do's and Don'ts**. Sections omittable; order locked when present. Spec rules: `references/design-md-spec.md`. Shape: read every entry in `{workflow.design_md_examples}`.
+
+## The EXPERIENCE.md spine
+
+Always: **Foundation** (form-factor, UI system when present; DESIGN.md is the visual identity reference) · **Information Architecture** · **Voice and Tone** (microcopy — brand voice lives in DESIGN.md.Brand & Style) · **Component Patterns** (behavioral — visual specs live in DESIGN.md.Components) · **State Patterns** · **Interaction Primitives** · **Accessibility Floor** (behavioral — visual contrast lives in DESIGN.md) · **Key Flows** (named-protagonist journeys with a climax beat).
+
+When triggered: **Inspiration & Anti-patterns** · **Responsive & Platform**.
+
+Invent sections for product-specific concerns. Shape: read every entry in `{workflow.experience_md_examples}`.
+
+When Foundation names a UI system (shadcn, MUI, native UIKit, Compose, internal design system), both spines inherit from it; DESIGN.md tokens reference or extend the system's defaults, EXPERIENCE.md specifies only the behavioral delta.
+
+## Sources
+
+UX may lead, follow, or stand alone. Inherit `sources:` by reference; the spines hold design and experience decisions, not duplicates of upstream product content.
+
+## On Activation
+
+1. Resolve customization: `python3 {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; consult them alongside generic web research on the same triggers, org tools preferred when their directive matches.
+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.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn. In the greeting, let the user know `bmad-party-mode` and `bmad-advanced-elicitation` are always available. Then scan for misroute on the first message: PRD → `bmad-prd`; architecture → `bmad-create-architecture`; game UX → BMad GDS; agent/skill → `bmad-workflow-builder`; brief → `bmad-product-brief`.
+5. Detect intent: **Create**, **Update**, **Validate**. For Create, before binding a fresh workspace, scan `{workflow.ux_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `DESIGN.md` frontmatter `status` is not `final`) and offer to resume rather than starting over.
+
+Run `{workflow.activation_steps_append}`.
+
+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 been completed.
+
+## Modes
+
+**Create.** Bind `{doc_workspace}` to `{workflow.ux_output_path}/{workflow.run_folder_pattern}/`. Create `.working/`, `imports/`, `.decision-log.md`, `DESIGN.md` (frontmatter only), and `EXPERIENCE.md` (frontmatter only). Run Discovery → Finalize.
+
+**Update.** Read spines + log + sources. Create the log if missing — this update is entry one. Surface conflicts with prior decisions. Run Finalize.
+
+**Validate.** See `references/validate.md`.
+
+## Discovery
+
+**Capture; do not author.** The spines are distilled at Finalize. Decisions → `.decision-log.md` (canonical). Creative-tool artifacts → `.working/`. User-supplied visuals (Figma, sketches, brand decks, image folders) → `imports/`, one log line per item. Spines win on conflict.
+
+**Source scan.** Glob `{planning_artifacts}/` for candidate input paths; surface paths only — never read content in the parent. User confirms which apply or adds others; subagent-extracts on confirm.
+
+Brain dump first — even when the user opens with paragraphs (that's intake). Subagent-extract big docs. One "anything else?" probe. Stakes: hobby / internal / consumer / regulated.
+
+Working mode:
+
+- **Fast path** — batch gaps, draft both spines with `[ASSUMPTION]` tags, skip creative tools.
+- **Coaching path** — walk decisions; creative tools woven in.
+- **Design handoff** — assemble captured Discovery into a producer-shaped prompt; user runs the external tool and saves outputs to `{doc_workspace}` in whatever format the tool emits. Producer registry: `{workflow.design_handoffs}` (default: Google Stitch). EXPERIENCE.md can follow via Update mode when ready.
+
+Creative tools — scan `{workflow.creative_tools}`, invoke when seeing helps. Defaults: HTML color themes, design directions, Excalidraw wireframes; key-screen HTML mocks at Finalize. See `references/creative-tools.md`. Research subagents on demand; consult `{workflow.external_sources}` when entries match.
+
+Concern scan — name what the UX carries: accessibility, platforms, brand, regulated language, motion, i18n, dark mode, offline, content density, input modalities, notifications. Open list; drives invented sections.
+
+Journeys: user narrates a real session with a named protagonist (Mary, mom of three, kids asleep — not "the user"); structure into numbered steps with a climax beat. Mirror source-spec names verbatim when defined.
+
+Form-factor: mobile / web / desktop / multi-surface must resolve before IA closes. Named-protagonist journeys often derive it (Pary on iPad implies an iPad surface; Skeeter on Android adds a multi-surface need); when journeys don't disambiguate, probe.
+
+Surface closure: stated needs become screens through journeys. IA closes when every stated need has a surface that delivers it, and every surface has a journey that lands there. When closure fails, probe — never invent the missing piece.
+
+## Reviewer Gate
+
+Used by Validate and Finalize. **Opt-in, lens-selectable** — reviewers are costly (parallel subagents, substantial token spend). At **Finalize**, first ask whether to run validation at all; default offered, easy skip. At **Validate** intent the user already opted in — skip that question. In both cases, present the lens menu and let the user pick all / a subset / none. Menu: rubric walker (`references/validate.md`) + `{workflow.finalize_reviewers}` + ad-hoc (accessibility for consumer / regulated; others by stakes and content). Picked lenses dispatch as parallel subagents → each writes `review-{slug}.md`, returns a compact summary. If any lens ran, run the synthesis pipeline in `references/validate.md`.
+
+## Finalize
+
+Outcomes, in order:
+
+- **Spines distilled.** Subagent reads `.decision-log.md`, `.working/`, `imports/`, sources; produces `DESIGN.md` against `## The DESIGN.md spine` + `{workflow.design_md_examples}` and `EXPERIENCE.md` against `## The EXPERIENCE.md spine` + `{workflow.experience_md_examples}`. Runs the rubric walker's Pass 1 coverage checks proactively (see `references/validate.md`). Surface gaps; never invent.
+- **Inputs reconciled.** Subagent per user-supplied input → `reconcile-{slug}.md`. Surface dropped qualitative ideas.
+- **Reviewer Gate offered.** Ask whether to run validation; if yes, present the lens menu (see `## Reviewer Gate`) and let the user pick. If any lens ran, resolve findings before polish; otherwise proceed.
+- **Open items triaged.** Open Questions, `[ASSUMPTION]`, `[NOTE FOR UX]`. Phase-blockers one at a time; non-blockers → log.
+- **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. Share paths. Common next: `bmad-create-architecture`, `bmad-create-epics-and-stories`, `bmad-dev-story`. Run `{workflow.on_complete}`.

package/src/bmm-skills/2-plan-workflows/bmad-ux/assets/color-themes.md

@@ -0,0 +1,9 @@
+# Color Themes Renderer
+
+Subagent prompt. Produce one self-contained HTML page at the supplied `.working/color-themes-{n}.html` path showing 4-6 distinct theme variations side by side so the user can pick.
+
+Each variation: header (name + one-line emotional register), token chips for every semantic role decided so far, and one realistic UI snippet using the palette (content drawn from the conversation, not lorem). Include light and dark side-by-side when both modes are in scope. Avoid near-identical pastels — variations must differ in register, not just hue.
+
+Inline CSS only, system font stack, no JS, no network. Document concrete hex values in `<style>` comments per variation so the user can lift them if they pick that theme. The spine itself stays semantic.
+
+Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file with `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`.

package/src/bmm-skills/2-plan-workflows/bmad-ux/assets/design-directions.md

@@ -0,0 +1,9 @@
+# Design Directions Renderer
+
+Subagent prompt. Produce 3-6 distinct visual directions for the product's hero screen, each a separate self-contained HTML file at `.working/direction-{slug}.html` (or one combined `directions-{n}.html` if the parent's intent says side-by-side).
+
+Each direction is a *complete visual personality* applied to the same key screen — not a palette swap. Differ on density, type weight, motion implication, brand register. Each file: 2-3 sentence rationale, near-1:1 hero screen mockup in a phone or browser frame, ideally a secondary screen, at least one state variant visible (aging row, empty state, etc).
+
+Use real product content from the conversation. Voice/tone from `.decision-log.md` applied to every visible string — no lorem. Inline CSS, system fonts, no JS or network. Document hex values in `<style>` comments per direction.
+
+Return to the parent: file paths, one-line personality summary per direction, what hero screen was depicted. Do not dump HTML into parent context. If interactive, open each file in the browser.

package/src/bmm-skills/2-plan-workflows/bmad-ux/assets/design-example-editorial.md

@@ -0,0 +1,158 @@
+---
+name: Linen & Logic
+colors:
+  surface: '#fbf9f4'
+  surface-dim: '#dbdad5'
+  surface-bright: '#fbf9f4'
+  surface-container-lowest: '#ffffff'
+  surface-container-low: '#f5f3ee'
+  surface-container: '#f0eee9'
+  surface-container-high: '#eae8e3'
+  surface-container-highest: '#e4e2dd'
+  on-surface: '#1b1c19'
+  on-surface-variant: '#4e453d'
+  inverse-surface: '#30312e'
+  inverse-on-surface: '#f2f1ec'
+  outline: '#80756b'
+  outline-variant: '#d1c4b9'
+  surface-tint: '#715a3f'
+  primary: '#59452b'
+  on-primary: '#ffffff'
+  primary-container: '#735c41'
+  on-primary-container: '#f5d6b4'
+  inverse-primary: '#e0c1a1'
+  secondary: '#a43b2c'
+  on-secondary: '#ffffff'
+  secondary-container: '#fd7d69'
+  on-secondary-container: '#71160b'
+  tertiary: '#374a5f'
+  on-tertiary: '#ffffff'
+  tertiary-container: '#4f6278'
+  on-tertiary-container: '#caddf8'
+  error: '#ba1a1a'
+  on-error: '#ffffff'
+  error-container: '#ffdad6'
+  on-error-container: '#93000a'
+  primary-fixed: '#fdddbb'
+  primary-fixed-dim: '#e0c1a1'
+  on-primary-fixed: '#281804'
+  on-primary-fixed-variant: '#58432a'
+  secondary-fixed: '#ffdad4'
+  secondary-fixed-dim: '#ffb4a7'
+  on-secondary-fixed: '#400200'
+  on-secondary-fixed-variant: '#842417'
+  tertiary-fixed: '#d0e4ff'
+  tertiary-fixed-dim: '#b4c8e2'
+  on-tertiary-fixed: '#071d30'
+  on-tertiary-fixed-variant: '#35485d'
+  background: '#fbf9f4'
+  on-background: '#1b1c19'
+  surface-variant: '#e4e2dd'
+typography:
+  display-lg:
+    fontFamily: Libre Caslon Text
+    fontSize: 48px
+    fontWeight: '400'
+    lineHeight: '1.1'
+    letterSpacing: -0.02em
+  display-lg-mobile:
+    fontFamily: Libre Caslon Text
+    fontSize: 36px
+    fontWeight: '400'
+    lineHeight: '1.1'
+  headline-md:
+    fontFamily: Libre Caslon Text
+    fontSize: 32px
+    fontWeight: '400'
+    lineHeight: '1.2'
+  headline-sm:
+    fontFamily: Libre Caslon Text
+    fontSize: 24px
+    fontWeight: '400'
+    lineHeight: '1.3'
+  body-lg:
+    fontFamily: DM Sans
+    fontSize: 18px
+    fontWeight: '400'
+    lineHeight: '1.6'
+    letterSpacing: 0.01em
+  body-md:
+    fontFamily: DM Sans
+    fontSize: 16px
+    fontWeight: '400'
+    lineHeight: '1.6'
+  label-caps:
+    fontFamily: DM Sans
+    fontSize: 12px
+    fontWeight: '500'
+    lineHeight: '1.4'
+    letterSpacing: 0.1em
+  caption:
+    fontFamily: DM Sans
+    fontSize: 13px
+    fontWeight: '400'
+    lineHeight: '1.4'
+rounded:
+  sm: 0.125rem
+  DEFAULT: 0.25rem
+  md: 0.375rem
+  lg: 0.5rem
+  xl: 0.75rem
+  full: 9999px
+spacing:
+  unit: 8px
+  gutter: 24px
+  margin-mobile: 20px
+  margin-desktop: 64px
+  editorial-gap: 80px
+---
+
+## Brand & Style
+
+The design system is rooted in the philosophy of "Slow Design"—an intentional departure from the frantic pace of fast fashion. It evokes a tactile, "linen-weight" sensation through high-end editorial layouts and a restrained aesthetic. The target audience values provenance over presence, seeking a reflective and sophisticated discovery experience that feels as much like a boutique magazine as a digital marketplace.
+
+The style is **Editorial Minimalism** with **Tactile** accents. It prioritizes breathable white space, asymmetrical layouts that mimic printed lookbooks, and a soft, sun-faded palette. Every interaction is designed to be deliberate and "anti-hype," eschewing aggressive animations for subtle transitions and quiet confidence.
+
+## Colors
+
+The palette is inspired by natural fibers and weathered landscapes. 
+- **Warm White (#F9F7F2)** serves as the primary canvas, providing a soft, non-clinical background that reduces eye strain.
+- **Bone (#E3DED1)** and **Dust (#C2B9A7)** are used for structural depth, subtle dividers, and secondary surfaces.
+- **Tobacco (#735C41)** is the primary ink color, used for high-contrast typography and essential UI elements.
+- **Sun-faded Red (#B84A39)** and **Wool Blanket Blue (#4A5D73)** are used sparingly as "organic accents"—highlighting editorial picks or signifying subtle state changes without disrupting the tranquil atmosphere.
+
+## Typography
+
+Typography is the primary vehicle for the brand’s sophisticated voice. 
+- **Libre Caslon Text** is the voice of the curator. Its classic proportions and elegant serifs provide the editorial weight required for discovery and storytelling.
+- **DM Sans** provides a quiet, functional counterpoint. It is used for body copy and navigational elements, ensuring clarity without competing with the headlines. 
+
+Large display titles should often use "optical sizing" logic—tighter leading and slightly negative letter spacing to create a cohesive visual block. Labels are always tracked out (0.1em) to maintain a sense of airy premiumness.
+
+## Layout & Spacing
+
+This design system employs a **Fluid Editorial Grid**. While it follows a 12-column structure on desktop, it encourages "asymmetrical breathing room"—intentionally leaving columns empty to direct focus toward high-quality imagery.
+
+Spacing is generous. The `editorial-gap` (80px+) should be used between major content sections to allow the user to pause and reflect. Mobile layouts should maintain a minimum of 20px side margins to ensure the content feels framed like a page, rather than bleeding to the edges of the device. Elements should lean toward vertical stacks to mimic the scroll of a digital journal.
+
+## Elevation & Depth
+
+Depth is communicated through **Tonal Layering** and **Ambient Shadows** rather than sharp borders.
+- **Surfaces:** Use the "Bone" color to define containers against the "Warm White" base. 
+- **Shadows:** Shadows are highly diffused and tinted with the "Tobacco" hue (`rgba(115, 92, 65, 0.08)`). They should feel like a soft glow of light hitting fabric, with large blur radii (20px+) and very low opacity.
+- **Borders:** When borders are necessary, they are 1px thick and rendered in "Dust," creating a "ghost" outline that barely separates elements from the background.
+
+## Shapes
+
+The shape language is **Soft (0.25rem)**. While a sharp edge feels too aggressive and a pill-shape feels too digital/tech-heavy, a subtle rounding of corners mimics the natural softening of woven textiles over time. 
+
+Larger containers (Cards, Modals) may use `rounded-lg` (0.5rem) to emphasize their tactile, object-like quality. Imagery should always follow these corner radii to maintain a cohesive, "framed" appearance.
+
+## Components
+
+- **Buttons:** Primary buttons use a solid "Tobacco" fill with "Warm White" text. Secondary buttons are "Bone" with "Tobacco" text or simply "Tobacco" text with a 1px "Dust" border. Padding is generous horizontally to create an elegant, elongated silhouette.
+- **Cards:** Editorial cards feature large imagery, a "headline-sm" title, and a "caption" subline. Shadows are only applied on hover to simulate a gentle lift.
+- **Inputs:** Minimalist underlines in "Dust" that transition to "Tobacco" on focus. Label text remains in "label-caps" above the field.
+- **Chips/Tags:** Used for material types (e.g., "100% Linen"). These are rendered in "Bone" backgrounds with "Tobacco" text, using the "Soft" corner radius.
+- **Icons:** Must be "Hand-drawn" or "Fine-line" style. Lines should have slight imperfections and vary in weight to reinforce the tactile, artisanal nature of the fashion being discovered.
+- **Navigation:** A simple, centered bottom bar or a top-weighted "Ghost" header that disappears on scroll to maximize the editorial viewport.