Merge remote-tracking branch 'origin/main' into feat/bmad-marketplace-plugin

# Conflicts:
#	.prettierignore
#	package.json

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

.gitignore

@@ -81,3 +81,6 @@ _bmad/custom/*.user.toml
 website/.astro/
 website/dist/
 build/
+
+# Web bundle release artifacts
+dist/web-bundles/

.husky/pre-commit

@@ -10,11 +10,13 @@ npm test
 if command -v rg >/dev/null 2>&1; then
   if git diff --cached --name-only | rg -q '^docs/'; then
     npm run docs:validate-links
+		npm run docs:validate-sidebar
 		npm run docs:build
   fi
 else
   if git diff --cached --name-only | grep -Eq '^docs/'; then
     npm run docs:validate-links
+		npm run docs:validate-sidebar
 		npm run docs:build
   fi
 fi

.prettierignore

@@ -13,3 +13,8 @@ _bmad*/
 
 # Generated vendored bundles in the bmad-module skill (not authored source)
 src/core-skills/bmad-module/scripts/lib/vendor/**
+
+# Quality scan artifacts produced by bmad-workflow-builder
+# (per-skill .analysis/ folders contain JSON/HTML reports that should
+# not block commits with formatting checks)
+**/.analysis/

CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v6.8.0 - 2026-05-25
+
+### ✨ Headline
+
+**New planning shapes lead this release.** **bmad-ux** replaces the old single-spine UX skill with a two-spine contract: **DESIGN.md** (visual identity, Google Labs spec) and **EXPERIENCE.md** (behavior, flow, IA). **bmad-spec** distills any messy intent (brain dump, PRD, transcript, brief) into a tight five-field SPEC.md kernel that any downstream skill can consume. Both extend the streamlined Create/Update/Validate + Fast/Coaching template that **bmad-prd** and **bmad-product-brief** set in v6.7.0. The handoff from design into engineering is now a sealed file contract, not a translation layer.
+
+**Also shipping:** **Web Bundles** for Gemini Gems and ChatGPT Custom GPTs ([bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)) bring six planning bundles to non-IDE users with full IDE schema parity. **bmad-automator** (story automation) lands on the `next` channel. **bmad-method-ui** ships a community-alpha VS Code dashboard + standalone Next.js web UI. 19 new elicitation techniques arrive. Plus a long tail of installer and activation fixes.
+
+### 💥 Breaking Changes
+
+* **`bmad-create-ux-design` replaced by `bmad-ux`.** Single `design.md` spine is gone. New skill emits **DESIGN.md** (visual tokens per the Google Labs spec) and **EXPERIENCE.md** (behavior, flow, IA, states, a11y), with EXPERIENCE.md referencing DESIGN.md tokens via `{path.to.token}` syntax. Adds named-protagonist journeys, surface-closure validation, opt-in reviewer gate, and an extensible producer-handoff registry (default: Stitch). Installer auto-removes the legacy skill. PRD and brief templates aligned (form-factor probe, named-protagonist UJs, no standalone Primary Persona) (#2413)
+* **`bmad-distillator` retired, superseded by `bmad-spec`.** Promoted to core because the kernel pattern is domain-agnostic. Installer cleans up automatically. No internal pipelines called it, but custom workflows must switch to `bmad-spec`.
+
+### 🎁 Features
+
+* **Web Bundles v6 shelf**: Six bundles purpose-built for Gemini Gems and ChatGPT Custom GPTs. Brainstorming (60 techniques, 10 categories), Product Brief (Create/Update/Validate, Fast/Coaching paths), PRFAQ (Working Backwards, 4 stages, weasel-word challenge), PRD (Vision- or Journey-led, 7-dimension validation), UX (two-spine, Don Norman framing, Stitch handoff), Market & Industry Research (Deep Research + Porter + Christensen). Full schema parity with IDE skills so Gem ↔ IDE handoffs do not break. [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/) is the single supported install path (#2421, #2423, #2425)
+* **Web Bundle release packager**: `tools/bundle-web-bundles.js` zips each bundle into `dist/web-bundles/{slug}.zip` for GitHub Release attachment. `web-bundles/bundles.json` carries persona, copy, accent color, knowledge files, and platform feature flags (web-browsing, deep-research, Stitch). Zero deps; `execFileSync` + strict slug regex (`^[a-z0-9][a-z0-9-]*$`) eliminates shell-injection surface (#2424)
+* **`bmad-spec`, new core skill**: Distills any intent (brain dump, PRD, transcript, brief) into `SPEC.md` with a five-field kernel (Problem, Capabilities, Constraints, Non-goals, Success signal). Catalogs, tables, diagrams, and editorial-voice content go to named companions; absorbed inputs land in a `sources:` list downstream skips. Eight-rule Spec Law with lean-prose discipline. Outputs to `{output_folder}/specs/spec-{slug}/`, works without bmm installed. Headless callers get JSON; interactive runs close conversationally (#2417)
+* **`bmad-ux`, spine-based UX skill**: Rewrite around DESIGN.md (visual identity, Google Labs spec) + EXPERIENCE.md (behavior, flow, IA). Six-step activation matches `bmad-prd` and `bmad-product-brief`. Fast/Coaching modes. Opt-in reviewer gate (no auto-spend on parallel reviewers for hobby work). Per-category verdicts, no misleading headline grade. Ships three DESIGN.md examples (editorial/Linen & Logic, native mobile/Quill, web SaaS/Drift), two paired EXPERIENCE.md examples, one unpaired DESIGN.md modeling the pure Stitch handoff (#2413)
+* **19 new advanced-elicitation techniques**: New `framing` category plus additions across 7 categories (all 50 existing methods preserved). Highlights: Chain-of-Thought Scaffolding, Six Thinking Hats, Delphi Method, Inversion Analysis, Steelmanning, Morphological Analysis, Abstraction Laddering, Cascading Failure Simulation, Boundary & Edge Case Sweep (#2062)
+* **Docs sidebar-order validator**: `tools/validate-sidebar-order.js` flags duplicates, gaps, missing fields, and translation drift across English and translated docs. Wired into `docs:validate-sidebar`. Locale-pattern detection prevents nested English subfolders from being silently excluded (#2409)
+
+### 🐛 Fixes
+
+* **Skill activation guardrails strengthened across 23+ skills**: LLM agents were short-circuiting activation sequences (INCLUDE → READ → RUN → CHECK → FILTER → CD) by guessing variables instead of executing in order, silently skipping append steps and `on_complete` hooks. New guardrail names prepend/append steps explicitly and requires confirmation. Applied to all BMM planning + execution skills, all persona agents (analyst, tech-writer, pm, ux-designer, architect, dev), and new skills (bmad-spec, bmad-ux) (#2398)
+* **Installer reads `config.toml` on re-run**: `loadExistingConfig` only read legacy `_bmad/<module>/config.yaml`, so user-scoped answers (`user_name`, `communication_language`) written to `_bmad/config.user.toml` were ignored and users got re-prompted. Adds `parseCentralToml`; central toml read first, legacy yaml as fallback (#2411)
+* **Stale custom-source caches refreshed on quick-update**: Quick-update now calls `cloneRepo` for every cached custom module, persists the real `next` ref, and atomically dedupes the refresh. When `git fetch` fails (network, deleted repo, revoked auth), the previous clone is preserved with a warning instead of being wiped (#2399)
+* **Shallow-clone default branch resolution**: `--depth 1` clones leave `origin/HEAD` stale, so `git reset --hard origin/HEAD` never pulled new commits. Now resolves the default branch via `git symbolic-ref` and resets against `origin/<branch>` explicitly, falling back to `main` (#2332)
+* **SSH Git URLs with nested group paths**: Custom module installer parses GitLab subgroup and Gitea nested-team SSH URLs correctly (#2379)
+* **`project_context` defined in dev-story, sprint-planning, sprint-status**: Skills referenced the variable without resolving it, producing unresolved expansions at activation in some configurations (#2422)
+* **Dev story baseline commits captured**: Baselining records the commit set the story was scoped against, so reviews compare against a stable reference (#2403)
+* **Customization JSON written as UTF-8**: Non-ASCII team names, product names, and editorial overrides survive a round trip through `_bmad/custom/` (#2414)
+* **Brainstorming idea-flow stays collaborative**: Agent was prematurely converging on its own preferred ideas instead of mirroring and expanding the user's. Collaborative posture restored (#2402)
+
+### 📚 Docs
+
+* **bmad-investigate added to agent trigger tables**: `agents.md` and `named-agents.md` now show the `IN` trigger and forensic-investigation capability on Amelia's row, closing a v6.7.0 gap (#2410)
+* **Web Bundles install framing and update/customize guidance**: Drops misleading "one-click install" and "two files" claims; adds explicit Gem/GPT setup pattern and an "Updating and customizing" section: custom changes belong in the pasted instructions block, not the knowledge files, so updates do not clobber team customizations (#2423)
+* **Web-bundles install traffic centralized at bmadcode.com/web-bundles**: README, web-bundles README, explanation, and how-to pages all point at the site as the single supported install path (#2425)
+* **Reference docs for bmad-spec**: Full entry in `docs/reference/core-tools.md` (en); table-row stubs in cs/fr/vi-vn/zh-cn pending full translation
+
 ## v6.7.1 - 2026-05-18
 
 ### 🐛 Fixes

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

docs/cs/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Pokročilá elicitace"
 description: Přimějte LLM přehodnotit svou práci pomocí strukturovaných metod uvažování
 sidebar:
-  order: 6
+  order: 3
 ---
 
 Přimějte LLM přehodnotit, co právě vygeneroval. Vyberete metodu uvažování, LLM ji aplikuje na svůj vlastní výstup, a vy rozhodnete, zda si vylepšení ponecháte.

docs/cs/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Adversariální revize"
 description: Technika vynuceného uvažování, která zabraňuje líným „vypadá dobře“ revizím
 sidebar:
-  order: 5
+  order: 7
 ---
 
 Vynuťte hlubší analýzu tím, že budete vyžadovat nalezení problémů.

docs/cs/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ pro existující projekty"
 description: Časté otázky o používání BMad Method na existujících projektech
 sidebar:
-  order: 8
+  order: 10
 ---
 Rychlé odpovědi na časté otázky o práci na existujících projektech s BMad Method (BMM).
 

docs/cs/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Spolupráce více agentů — všichni vaši AI agenti v jedné konverzaci
 sidebar:
-  order: 7
+  order: 8
 ---
 
 Všichni vaši AI agenti v jedné konverzaci.

docs/cs/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Předcházení konfliktům agentů"
 description: Jak architektura zabraňuje konfliktům, když více agentů implementuje systém
 sidebar:
-  order: 4
+  order: 5
 ---
 
 Když více AI agentů implementuje různé části systému, mohou dělat protichůdná technická rozhodnutí. Dokumentace architektury tomu zabraňuje stanovením sdílených standardů.

docs/cs/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Kontext projektu"
 description: Jak project-context.md vede AI agenty s pravidly a preferencemi vašeho projektu
 sidebar:
-  order: 7
+  order: 9
 ---
 
 Soubor `project-context.md` je implementační průvodce vašeho projektu pro AI agenty. Podobně jako „ústava“ v jiných vývojových systémech zachycuje pravidla, vzory a preference, které zajišťují konzistentní generování kódu napříč všemi workflow.

docs/cs/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Snižte tření human-in-the-loop bez ztráty kontrolních bodů chránících kvalitu výstupu
 sidebar:
-  order: 2
+  order: 6
 ---
 
 Záměr na vstupu, změny kódu na výstupu, s co nejmenším počtem human-in-the-loop kroků — bez obětování kvality.

docs/cs/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Proč je solutioning důležitý"
 description: Pochopení toho, proč je fáze solutioningu klíčová pro projekty s více epicy
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Fáze 3 (Solutioning) překládá **co** budovat (z plánování) na **jak** to budovat (technický návrh). Tato fáze zabraňuje konfliktům agentů v projektech s více epicy tím, že dokumentuje architektonická rozhodnutí před zahájením implementace.

docs/cs/reference/commands.md

@@ -2,7 +2,7 @@
 title: Skills
 description: Reference BMad skills — co to je, jak fungují a kde je najít.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills jsou předpřipravené prompty, které načítají agenty, spouštějí workflow nebo provádějí úkoly ve vašem IDE. Instalátor BMad je generuje z vašich nainstalovaných modulů při instalaci. Pokud později přidáte, odeberete nebo změníte moduly, přeinstalujte pro synchronizaci skills (viz [Řešení problémů](#řešení-problémů)).

docs/cs/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Základní nástroje
 description: Reference všech vestavěných úkolů a workflow dostupných v každé instalaci BMad bez dalších modulů.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Každá instalace BMad zahrnuje sadu základních skills, které lze použít v kombinaci s čímkoli — samostatné úkoly a workflow, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Ty jsou vždy dostupné bez ohledu na to, které volitelné moduly nainstalujete.
@@ -18,7 +18,7 @@ Spusťte jakýkoli základní nástroj zadáním jeho názvu skillu (např. `bma
 | [`bmad-help`](#bmad-help) | Task | Kontextové poradenství, co dělat dál |
 | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitace interaktivních brainstormingových sezení |
 | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrace skupinových diskuzí více agentů |
-| [`bmad-distillator`](#bmad-distillator) | Task | Bezeztrátová LLM-optimalizovaná komprese dokumentů |
+| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
 | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Iterativní zdokonalování LLM výstupu |
 | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynická revize hledající chybějící a chybné |
 | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Vyčerpávající analýza větvících cest pro neošetřené hraniční případy |
@@ -97,32 +97,6 @@ Kouzlo se děje v nápadech 50–100. Workflow povzbuzuje generování 100+ náp
 
 **Výstup:** Real-time multi-agentní konverzace s udržovanými osobnostmi agentů
 
-## bmad-distillator
-
-**Bezeztrátová LLM-optimalizovaná komprese zdrojových dokumentů.** — Produkuje husté, tokenově efektivní destiláty, které zachovávají všechny informace pro následné LLM zpracování. Ověřitelné prostřednictvím round-trip rekonstrukce.
-
-**Použijte když:**
-
-- Dokument je příliš velký pro kontextové okno LLM
-- Potřebujete tokenově efektivní verze výzkumů, specifikací nebo plánovacích artefaktů
-- Chcete ověřit, že během komprese nebyly ztraceny žádné informace
-
-**Jak to funguje:**
-
-1. **Analýza** — Čte zdrojové dokumenty, identifikuje hustotu informací a strukturu
-2. **Komprese** — Převádí prózu na hustý odrážkový formát, odstraňuje dekorativní formátování
-3. **Ověření** — Kontroluje úplnost pro zajištění zachování všech informací
-4. **Validace** (volitelné) — Round-trip rekonstrukční test dokazuje bezeztrátovou kompresi
-
-**Vstup:**
-
-- `source_documents` (povinné) — Cesty k souborům, složkám nebo glob vzory
-- `downstream_consumer` (volitelné) — Co to konzumuje (např. „tvorba PRD“)
-- `token_budget` (volitelné) — Přibližná cílová velikost
-- `--validate` (příznak) — Spuštění round-trip rekonstrukčního testu
-
-**Výstup:** Destilátové markdown soubory s reportem kompresního poměru (např. „3.2:1“)
-
 ## bmad-advanced-elicitation
 
 **Iterativní zdokonalování LLM výstupu metodami elicitace.** — Vybírá z knihovny elicitačních technik pro systematické zlepšování obsahu více průchody.

docs/cs/reference/modules.md

@@ -2,7 +2,7 @@
 title: Oficiální moduly
 description: Doplňkové moduly pro tvorbu vlastních agentů, kreativní inteligenci, vývoj her a testování
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad se rozšiřuje prostřednictvím oficiálních modulů, které vyberete během instalace. Tyto doplňkové moduly poskytují specializované agenty, workflow a úkoly pro specifické domény nad rámec vestavěného jádra a BMM (Agile suite).

docs/cs/reference/testing.md

@@ -2,7 +2,7 @@
 title: Možnosti testování
 description: Srovnání vestavěného QA agenta (Quinn) s modulem Test Architect (TEA) pro automatizaci testů.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad poskytuje dvě testovací cesty: vestavěného QA agenta pro rychlé generování testů a instalovatelný modul Test Architect pro podnikovou testovací strategii.

docs/cs/reference/workflow-map.md

@@ -37,7 +37,7 @@ Definujte, co budovat a pro koho.
 | Workflow                    | Účel                                     | Produkuje    |
 | --------------------------- | ---------------------------------------- | ------------ |
 | `bmad-create-prd`           | Definice požadavků (FR/NFR)              | `PRD.md`     |
-| `bmad-create-ux-design`     | Návrh uživatelského zážitku (když záleží na UX) | `ux-spec.md` |
+| `bmad-ux`                | Návrh uživatelského zážitku (když záleží na UX) | `DESIGN.md`, `EXPERIENCE.md` |
 
 ## Fáze 3: Solutioning
 

docs/cs/tutorials/getting-started.md

@@ -150,7 +150,7 @@ Všechny workflow v této fázi jsou volitelné:
 - Spusťte `bmad-quick-dev` — zvládne plánování i implementaci v jednom workflow, přeskočte k implementaci
 
 :::note[UX Design (volitelné)]
-Pokud má váš projekt uživatelské rozhraní, vyvolejte **UX-Designer agenta** (`bmad-agent-ux-designer`) a spusťte UX design workflow (`bmad-create-ux-design`) po vytvoření PRD.
+Pokud má váš projekt uživatelské rozhraní, vyvolejte **UX-Designer agenta** (`bmad-agent-ux-designer`) a spusťte UX design workflow (`bmad-ux`) po vytvoření PRD.
 :::
 
 ### Fáze 3: Solutioning (BMad Method/Enterprise)

docs/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Advanced Elicitation"
 description: Push the LLM to rethink its work using structured reasoning methods
 sidebar:
-  order: 6
+  order: 4
 ---
 
 Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.

docs/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Adversarial Review"
 description: Forced reasoning technique that prevents lazy "looks good" reviews
 sidebar:
-  order: 5
+  order: 9
 ---
 
 Force deeper analysis by requiring problems to be found.

docs/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "Analysis Phase: From Idea to Foundation"
 description: What brainstorming, research, product briefs, and PRFAQs are — and when to use each
 sidebar:
-  order: 1
+  order: 2
 ---
 
 The Analysis phase (Phase 1) helps you think clearly about your product before committing to building it. Every tool in this phase is optional, but skipping analysis entirely means your PRD is built on assumptions instead of insight.

docs/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "Brainstorming"
 description: Interactive creative sessions using 60+ proven ideation techniques
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Unlock your creativity through guided exploration.

docs/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Checkpoint Preview"
 description: LLM-assisted human-in-the-loop review that guides you through a change from purpose to details
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` is an interactive, LLM-assisted human-in-the-loop review workflow. It walks you through a code change — from purpose and context into details — so you can make an informed decision about whether to ship, rework, or dig deeper.

docs/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "Established Projects FAQ"
 description: Common questions about using BMad Method on established projects
 sidebar:
-  order: 8
+  order: 13
 ---
 Quick answers to common questions about working on established projects with the BMad Method (BMM).
 

docs/explanation/forensic-investigation.md

@@ -2,7 +2,7 @@
 title: "Forensic Investigation"
 description: How bmad-investigate treats every issue like a crime scene, grades evidence, and produces a structured case file engineers can act on
 sidebar:
-  order: 6
+  order: 10
 ---
 
 You hand `bmad-investigate` a crash log, a stack trace, or just a "this used to work, now it doesn't". The skill takes

docs/explanation/named-agents.md

@@ -36,7 +36,7 @@ BMad ships six named agents, each anchored to a phase of the BMad Method:
 | 📋 **John**, Product Manager | Planning | PRD creation, epic/story breakdown, implementation readiness |
 | 🎨 **Sally**, UX Designer | Planning | UX design specifications |
 | 🏗️ **Winston**, System Architect | Solutioning | technical architecture, alignment checks |
-| 💻 **Amelia**, Senior Engineer | Implementation | story execution, quick-dev, code review, sprint planning |
+| 💻 **Amelia**, Senior Engineer | Implementation | story execution, quick-dev, code review, sprint planning, [forensic investigation](./forensic-investigation.md) |
 
 They each have a hardcoded identity (name, title, domain) and a customizable layer (role, principles, communication style, icon, menu). You can rewrite Mary's principles or add menu items; you can't rename her — that's deliberate. Brand recognition survives customization so "hey Mary" always activates the analyst, regardless of how a team has shaped her behavior.
 

docs/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Multi-agent collaboration - get all your AI agents in one conversation
 sidebar:
-  order: 7
+  order: 11
 ---
 
 Get all your AI agents in one conversation.

docs/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Preventing Agent Conflicts"
 description: How architecture prevents conflicts when multiple agents implement a system
 sidebar:
-  order: 4
+  order: 6
 ---
 
 When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.

docs/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Project Context"
 description: How project-context.md guides AI agents with your project's rules and preferences
 sidebar:
-  order: 7
+  order: 12
 ---
 
 The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.

docs/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Reduce human-in-the-loop friction without giving up the checkpoints that protect output quality
 sidebar:
-  order: 2
+  order: 7
 ---
 
 Intent in, code changes out, with as few human-in-the-loop turns as possible — without sacrificing quality.

docs/explanation/web-bundles.md

@@ -0,0 +1,82 @@
+---
+title: 'Web Bundles'
+description: BMad skills packaged for Google Gemini Gems and ChatGPT Custom GPTs
+---
+
+Run the planning side of BMad in your web LLM subscription, then bring the artifacts into your IDE.
+
+## What is a Web Bundle?
+
+A web bundle is a BMad skill repackaged for installation as a **Google Gemini Gem** or **ChatGPT Custom GPT**. Each bundle includes a `SKILL.md` protocol you upload as a knowledge file, an `INSTRUCTIONS.md` block you paste into the Gem or GPT instructions, and any data files the skill needs (CSVs, templates, validation checklists, additionally progressively disclosed content). The persona lives in the pasted instructions; the protocol lives in the knowledge file. Swap personas without touching the protocol.
+
+Setup is not one-click, but the steps are guided. **Install from [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**. The site lists every bundle in a card grid, shows you the Gemini and ChatGPT install steps inline, and hands you the ZIP download. That is the supported install path; the pattern is the same across the shelf, so once you've installed one the next one is mechanical.
+
+V4 of BMad shipped web bundles. V6 brings them back, rewritten for the current Gem and Custom GPT platforms with Canvas, Deep Research, and image generation in mind.
+
+## Why use them
+
+Planning work and implementation work want different tools. Web bundles let each use the right one.
+
+| Concern | Web LLM (Gem or GPT) | IDE (Claude Code, Cursor) |
+| --- | --- | --- |
+| Cost model | Flat-rate subscription | Metered tokens |
+| Strongest at | Conversation, Canvas, Deep Research, images | Files, terminal, codebase context |
+| Best for | Brainstorming, briefs, PRDs, research | Implementation, refactoring, code review |
+
+Running a full PRD or market research conversation in an IDE burns tokens that a Gem or Custom GPT handles for the price of your existing subscription. The polished artifact then drops into your repo and Claude Code or Cursor takes it from there.
+
+:::tip[Plan in the web, build in the IDE]
+The cost saving compounds on longer engagements. A PRFAQ pass and three rounds of research in a Gem cost zero marginal dollars; the same work in an IDE is real spend.
+:::
+
+## What's in the shelf
+
+The current set of bundles covers the analysis and planning phases:
+
+| Bundle | Phase | Persona lineage |
+| --- | --- | --- |
+| Brainstorming Coach | Analysis | Osborn (default), Minto (swap) |
+| Product Brief Coach | Analysis | Mary (BMad analyst) |
+| PRFAQ Coach | Analysis | Working Backwards (Bezos) |
+| PRD Coach | Planning | Cagan |
+| UX Coach | Planning | Norman |
+| Market & Industry Research | Analysis | Porter and Christensen |
+
+Each bundle carries a default persona inherited from its owning BMad agent (where one exists) and a contrasting swap example to demonstrate the voice change pattern.
+
+## How a session works
+
+1. **Open the Gem or Custom GPT.** Persona greets in character and opens conversational discovery.
+2. **Discover scope.** The persona asks what you're trying to do, what you have on hand, what constraints apply. No form fill.
+3. **Do the work in Canvas.** The protocol opens Canvas at session start and updates it continuously. Mermaid diagrams and HTML tables go in alongside the prose.
+4. **Hand off.** When you're done, you have a Canvas document you can export, paste into your repo, or feed to a BMad skill in your IDE for the next phase.
+
+For bundles that integrate Deep Research (currently Market & Industry Research), the persona drafts a Deep Research brief mid-session for you to paste into Gemini's or ChatGPT's Deep Research mode, then ingests the returned report.
+
+## When to use a web bundle
+
+- You're doing the upfront thinking for a project and you want a focused tool with persona, Canvas, and Deep Research.
+- You want to keep IDE token spend for actual coding.
+- You're sharing the planning artifact with collaborators who don't have your IDE setup.
+
+## When to stay in the IDE
+
+- The work needs to read or modify code in your repo.
+- You're already mid-implementation and want to keep context.
+- You don't have a Gemini Advanced or ChatGPT Plus subscription.
+
+## Updating and customizing
+
+Bundles evolve. When you pull a newer version of a bundle, the typical update is to its knowledge files (the `SKILL.md` protocol and any attached templates, CSVs, or validation checklists). Re-upload those into your Gem or Custom GPT to take the update. The instructions block usually does not change.
+
+If you want to customize a bundle for your team or your voice, do it in the **instructions block** you pasted into the Gem or GPT, not in the knowledge files. The instructions block is where the persona, preferences, and any local overrides live; the knowledge files are the protocol the bundle ships with. Keeping customization in the instructions block means future updates are a swap-the-attachments operation, not a merge-your-edits-back-in operation.
+
+:::tip[Customize the instructions, attach the knowledge]
+Persona swaps, default user name, team-specific guardrails, preferred phrasing: all of that belongs in the pasted instructions block. The knowledge files stay stock so you can refresh them without losing your changes.
+:::
+
+## Building your own
+
+Web bundles are generated from BMad skills using the `bmad-os-skill-to-bundle` utility skill. Point it at any BMad skill folder and it produces the bundle files with persona inheritance from the owning agent.
+
+Install any bundle from [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/).

docs/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Why Solutioning Matters"
 description: Understanding why the solutioning phase is critical for multi-epic projects
 sidebar:
-  order: 3
+  order: 5
 ---
 
 

docs/fr/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Élicitation Avancée"
 description: Pousser le LLM à repenser son travail en utilisant des méthodes de raisonnement structurées
 sidebar:
-  order: 8
+  order: 3
 ---
 
 Faites repenser au LLM ce qu'il vient de générer. Vous choisissez une méthode de raisonnement, il l'applique à sa propre sortie, et vous décidez de conserver ou non les améliorations.

docs/fr/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Revue Contradictoire"
 description: Technique de raisonnement forcée qui empêche les revues paresseuses du style "ça à l'air bon"
 sidebar:
-  order: 7
+  order: 8
 ---
 
 Forcez une analyse plus approfondie en exigeant que des problèmes soient trouvés.

docs/fr/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Checkpoint Preview"
 description: Revue assistée par LLM, avec intervention humaine, qui vous guide à travers une modification, de son objectif jusqu’aux détails
 sidebar:
-  order: 4
+  order: 7
 ---
 
 `bmad-checkpoint-preview` est un workflow de revue interactif, assisté par LLM, avec intervention humaine. Il vous guide à travers une modification de code — de l'intention et du contexte jusqu'aux détails — afin que vous puissiez prendre une décision éclairée sur la mise en production, la refonte ou l'approfondissement.

docs/fr/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ Projets Existants"
 description: Questions courantes sur l'utilisation de la méthode BMad sur des projets existants
 sidebar:
-  order: 11
+  order: 12
 ---
 Réponses rapides aux questions courantes sur l'utilisation de la méthode BMad (BMM) sur des projets existants.
 

docs/fr/explanation/forensic-investigation.md

@@ -2,7 +2,7 @@
 title: "Enquête de code"
 description: Comment bmad-investigate traite chaque problème comme une scène d'enquête, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir
 sidebar:
-  order: 6
+  order: 9
 ---
 
 Vous confiez à `bmad-investigate` un journal de plantage, une trace de pile, ou simplement un « ça marchait avant, plus

docs/fr/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Collaboration multi-agents - regroupez tous vos agents IA dans une seule conversation
 sidebar:
-  order: 9
+  order: 10
 ---
 
 Regroupez tous vos agents IA dans une seule conversation.

docs/fr/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Prévention des conflits entre agents"
 description: Comment l'architecture empêche les conflits lorsque plusieurs agents implémentent un système
 sidebar:
-  order: 6
+  order: 5
 ---
 
 Lorsque plusieurs agents IA implémentent différentes parties d'un système, ils peuvent prendre des décisions techniques contradictoires. La documentation d'architecture prévient cela en établissant des standards partagés.

docs/fr/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Contexte du Projet"
 description: Comment project-context.md guide les agents IA avec les règles et préférences de votre projet
 sidebar:
-  order: 10
+  order: 11
 ---
 
 Le fichier `project-context.md` est le guide d'implémentation de votre projet pour les agents IA. Similaire à une « constitution » dans d'autres systèmes de développement, il capture les règles, les patterns et les préférences qui garantissent une génération de code cohérente à travers tous les workflows.

docs/fr/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Réduire la friction de l’interaction humaine sans renoncer aux points de contrôle qui protègent la qualité des résultats
 sidebar:
-  order: 3
+  order: 6
 ---
 
 Intention en entrée, modifications de code en sortie, avec aussi peu d'interactions humaines dans la boucle que possible — sans sacrifier la qualité.

docs/fr/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Pourquoi le Solutioning est Important"
 description: Comprendre pourquoi la phase de solutioning est critique pour les projets multi-epics
 sidebar:
-  order: 5
+  order: 4
 ---
 
 La Phase 3 (Solutioning) traduit le **quoi** construire (issu de la Planification) en **comment** le construire (conception technique). Cette phase évite les conflits entre agents dans les projets multi-epics en documentant les décisions architecturales avant le début de l'implémentation.

docs/fr/reference/core-tools.md

@@ -18,7 +18,7 @@ Exécutez n'importe quel outil principal en tapant son nom de compétence (par e
 | [`bmad-help`](#bmad-help)                                             | Tâche    | Obtenir des conseils contextuels sur la prochaine étape                      |
 | [`bmad-brainstorming`](#bmad-brainstorming)                           | Workflow | Faciliter des sessions de brainstorming interactives                         |
 | [`bmad-party-mode`](#bmad-party-mode)                                 | Workflow | Orchestrer des discussions de groupe multi-agents                            |
-| [`bmad-distillator`](#bmad-distillator)                               | Tâche    | Compression sans perte optimisée pour LLM de documents                       |
+| [`bmad-spec`](#bmad-spec)                                             | Workflow | Distill any intent input into a SPEC kernel and companions (translation pending)                   |
 | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation)             | Tâche    | Pousser la sortie LLM à travers des méthodes de raffinement itératives       |
 | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tâche    | Revue cynique qui trouve ce qui manque et ce qui ne va pas                   |
 | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter)       | Tâche    | Analyse exhaustive des chemins de branchement pour les cas limites non gérés |
@@ -97,33 +97,6 @@ La magie se produit dans les idées 50–100. Le workflow encourage la générat
 
 **Sortie :** Conversation multi-agents en temps réel avec des personnalités d'agents maintenues
 
-## bmad-distillator
-
-**Compression sans perte optimisée pour LLM de documents sources.** — Produit des distillats denses et efficaces en tokens qui préservent toute l'information pour la consommation par des LLM en aval. Vérifiable par reconstruction aller-retour.
-
-**Utilisez-le quand :**
-
-- Un document est trop volumineux pour la fenêtre de contexte d'un LLM
-- Vous avez besoin de versions économes en tokens de recherches, spécifications ou artefacts de planification
-- Vous voulez vérifier qu'aucune information n'est perdue pendant la compression
-- Les agents auront besoin de référencer et de trouver fréquemment des informations dedans
-
-**Fonctionnement :**
-
-1. **Analyser** — Lit les documents sources, identifie la densité d'information et la structure
-2. **Compresser** — Convertit la prose en format dense de liste de points, supprime le formatage décoratif
-3. **Vérifier** — Vérifie l'exhaustivité pour s'assurer que toute l'information originale est préservée
-4. **Valider** (optionnel) — Le test de reconstruction aller-retour prouve la compression sans perte
-
-**Entrée :**
-
-- `source_documents` (requis) — Chemins de fichiers, chemins de dossiers ou motifs glob
-- `downstream_consumer` (optionnel) — Ce qui va le consommer (par ex., "création de PRD")
-- `token_budget` (optionnel) — Taille cible approximative
-- `--validate` (drapeau) — Exécuter le test de reconstruction aller-retour
-
-**Sortie :** Fichier(s) markdown distillé(s) avec rapport de ratio de compression (par ex., "3.2:1")
-
 ## bmad-advanced-elicitation
 
 **Passer la sortie du LLM à travers des méthodes de raffinement itératives.** — Sélectionne depuis une bibliothèque de techniques d'élicitation pour améliorer systématiquement le contenu à travers multiples passages.

docs/fr/reference/workflow-map.md

@@ -48,7 +48,7 @@ Définissez ce qu'il faut construire et pour qui.
 | Workflow                | Objectif                                                | Produit      |
 |-------------------------|---------------------------------------------------------|--------------|
 | `bmad-create-prd`       | Définissez les exigences (FRs/NFRs)[^1]                 | `PRD.md`[^2] |
-| `bmad-create-ux-design` | Concevez l'expérience utilisateur (lorsque l'UX compte) | `ux-spec.md` |
+| `bmad-ux`            | Concevez l'expérience utilisateur (lorsque l'UX compte) | `DESIGN.md`, `EXPERIENCE.md` |
 
 ## Phase 3 : Solutioning
 

docs/fr/tutorials/getting-started.md

@@ -150,7 +150,7 @@ Tous les workflows de cette phase sont optionnels. [**Pas sûr de quel outil uti
 - Exécutez `bmad-quick-dev` — il gère la planification et l'implémentation dans un seul workflow, passez directement à l'implémentation
 
 :::note[Design UX (Optionnel)]
-Si votre projet a une interface utilisateur, invoquez l'**agent Designer UX** (`bmad-agent-ux-designer`) et exécutez le workflow de design UX (`bmad-create-ux-design`) après avoir créé votre PRD.
+Si votre projet a une interface utilisateur, invoquez l'**agent Designer UX** (`bmad-agent-ux-designer`) et exécutez le workflow de design UX (`bmad-ux`) après avoir créé votre PRD.
 :::
 
 ### Phase 3 : Solutioning (méthode BMad/Enterprise)

docs/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: 'How to Expand BMad for Your Organization'
 description: Six customization patterns that reshape BMad without forking — agent-wide rules, workflow conventions, external publishing, template swaps, agent roster changes, and advanced integration patterns
 sidebar:
-  order: 9
+  order: 11
 ---
 
 BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through six recipes that cover most enterprise needs.

docs/how-to/use-web-bundles.md

@@ -0,0 +1,41 @@
+---
+title: 'Use Web Bundles'
+description: Install a BMad web bundle as a Google Gemini Gem or ChatGPT Custom GPT
+---
+
+Web bundles install from **[bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**.
+
+## Why a single front door
+
+The site is the only supported install path for the shelf. It keeps the steps current as Gemini and ChatGPT evolve, always points at the newest tagged release, and lets one signup put you on the list for new bundles as they ship.
+
+## What you'll do on the site
+
+1. Pick a bundle from the card grid.
+2. Open the install modal. Switch between the **Gemini Gem** and **ChatGPT GPT** tabs for the platform-specific steps.
+3. Download the bundle ZIP (one click; one-time free signup for email-only members).
+4. Follow the inline steps: create the Gem or Custom GPT, upload the knowledge files, paste the instructions block, save.
+
+## Prerequisites
+
+- **For Gemini Gems**: Gemini Advanced subscription.
+- **For ChatGPT Custom GPTs**: Plus, Pro, Business, or Enterprise plan.
+- For bundles that use **Deep Research** (currently Market & Industry Research), enable it from the prompt bar (Tools → Deep Research). Deep Research has its own plan limits.
+
+## Customize the persona
+
+Each bundle's `INSTRUCTIONS.md` (inside the ZIP) includes a **Persona Swap Example** above the paste boundary. Replace the `[persona]` block in your installed instructions with the swap example to change voice without changing the protocol. You can also write your own persona from scratch; the protocol stays the same.
+
+## What you get
+
+- A reusable Gem or Custom GPT scoped to one BMad planning capability.
+- Polished artifacts (briefs, PRDs, research reports, UX specs) ready to drop into your IDE for implementation.
+- Planning conversation runs on your existing web LLM subscription instead of metered IDE tokens.
+
+:::caution[Persona drift]
+Web LLMs occasionally drop persona partway through long sessions. If the model starts speaking out of character, remind it of its persona or start a fresh session.
+:::
+
+## Building your own
+
+To turn an existing BMad skill into a web bundle, use the `bmad-os-skill-to-bundle` utility skill from [bmad-utility-skills](https://github.com/bmad-code-org/bmad-utility-skills). It produces the bundle files with persona inheritance from the owning agent and a swap-example contrast voice. Submit your bundle to the shelf by opening a PR on [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) that adds the bundle directory and an entry in `web-bundles/bundles.json`.

docs/reference/agents.md

@@ -20,7 +20,7 @@ This page lists the default BMM (Agile suite) agents that install with BMad Meth
 | Analyst (Mary)              | `bmad-analyst`       | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorm, Market Research, Domain Research, Technical Research, Create Brief, PRFAQ Challenge, Document Project |
 | Product Manager (John)      | `bmad-pm`            | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course        |
 | Architect (Winston)         | `bmad-architect`     | `CA`, `IR`                         | Create Architecture, Implementation Readiness                                                       |
-| Developer (Amelia)          | `bmad-agent-dev`     | `DS`, `QD`, `QA`, `CR`, `SP`, `CS`, `ER` | Dev Story, Quick Dev, QA Test Generation, Code Review, Sprint Planning, Create Story, Epic Retrospective |
+| Developer (Amelia)          | `bmad-agent-dev`     | `DS`, `QD`, `QA`, `CR`, `SP`, `CS`, `ER`, `IN` | Dev Story, Quick Dev, QA Test Generation, Code Review, Sprint Planning, Create Story, Epic Retrospective, [Forensic Investigation](../explanation/forensic-investigation.md) |
 | UX Designer (Sally)         | `bmad-ux-designer`   | `CU`                               | Create UX Design                                                                                    |
 | Technical Writer (Paige)    | `bmad-tech-writer`   | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept |
 

docs/reference/commands.md

@@ -2,7 +2,7 @@
 title: Skills
 description: Reference for BMad skills — what they are, how they work, and where to find them.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep skills in sync (see [Troubleshooting](#troubleshooting)).

docs/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Core Tools
 description: Reference for all built-in tasks and workflows available in every BMad installation without additional modules.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing — standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install.
@@ -18,7 +18,7 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a
 | [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
 | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions |
 | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions |
-| [`bmad-distillator`](#bmad-distillator) | Task | Lossless LLM-optimized compression of documents |
+| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work |
 | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods |
 | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong |
 | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases |
@@ -97,32 +97,36 @@ The magic happens in ideas 50–100. The workflow encourages generating 100+ ide
 
 **Output:** Real-time multi-agent conversation with maintained agent personalities
 
-## bmad-distillator
+## bmad-spec
 
-**Lossless LLM-optimized compression of source documents.** — Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction.
+**Distill any intent input into the canonical SPEC contract for downstream work.** Takes a brief, PRD, GDD, RFC, brain dump, transcript, UX folder, or mixed multi-source input and produces a `SPEC.md` carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit the kernel.
 
 **Use it when:**
 
-- A document is too large for an LLM's context window
+- You need to lock the WHAT before the HOW for any kind of work (software, game design, research, editorial, policy, business).
-- You need token-efficient versions of research, specs, or planning artifacts
+- You want a LLM Optimized succinct, no-fluff contract that downstream skills can consume without re-reading every upstream artifact.
-- You want to verify no information is lost during compression
+- You want to validate or update an existing spec.
-- Agents will need to frequently reference and find information in it
 
 **How it works:**
 
-1. **Analyze** — Reads source documents, identifies information density and structure
+1. Reads the input and any ancillary linked materials.
-2. **Compress** — Converts prose to dense bullet-point format, strips decorative formatting
+2. Distills into the five-field kernel using a configurable template; routes overflow into appropriately-named companions.
-3. **Verify** — Checks completeness to ensure all original information is preserved
+3. Runs a two-pass self-validate (coherence rules, then preservation of every load-bearing source claim).
-4. **Validate** (optional) — Round-trip reconstruction test proves lossless compression
+4. Writes `SPEC.md`, sibling companions, and a `.decision-log.md` under `{output_folder}/specs/spec-{slug}/`.
+
+Spec Law enforces eight rules: capabilities carry both intent and success; intents are WHAT not HOW; constraints actually bend decisions; non-goals are explicit; success signals are concrete; capability IDs are stable; every load-bearing source claim is preserved; prose is lean.
 
 **Input:**
 
-- `source_documents` (required) — File paths, folder paths, or glob patterns
+- `input` (required) — path or inline text. Vague idea, brain dump, PRD, GDD, RFC, brief, transcript, mockup folder, mixed multi-source.
-- `downstream_consumer` (optional) — What consumes this (e.g., "PRD creation")
+- `slug` (optional) — required only when input is sparse and no slug is derivable from a source filename.
-- `token_budget` (optional) — Approximate target size
+- `target_spec_path` (optional) — set to update an existing spec instead of creating a new one.
-- `--validate` (flag) — Run round-trip reconstruction test
 
-**Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1")
+**Output:** Spec folder containing `SPEC.md`, any companion files, and a `.decision-log.md`. Headless callers receive a JSON response with the result status and the list of files written or modified.
+
+:::note[Mutation contract]
+`bmad-spec` is the only writer of `SPEC.md` and of spec-authored companions. Other skills produce their own native artifacts and invoke `bmad-spec` headless when they need to express intent as the canonical contract or propose updates.
+:::
 
 ## bmad-advanced-elicitation
 

docs/reference/modules.md

@@ -2,7 +2,7 @@
 title: Official Modules
 description: Add-on modules for building custom agents, creative intelligence, game development, and testing
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad extends through official modules that you select during installation. These add-on modules provide specialized agents, workflows, and tasks for specific domains beyond the built-in core and BMM (Agile suite).

docs/reference/testing.md

@@ -2,7 +2,7 @@
 title: Testing Options
 description: Comparing the built-in QA workflow with the Test Architect (TEA) module for test automation.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad provides two testing paths: a built-in QA workflow for fast test generation and an installable Test Architect module for enterprise-grade test strategy.

docs/reference/workflow-map.md

@@ -47,7 +47,7 @@ Define what to build and for whom.
 | Workflow                | Purpose                                                                             | Produces                                          |
 |-------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------|
 | `bmad-prd`              | Create, update, or validate a PRD — facilitated discovery, three intents in one skill | Create/Update: `prd.md`, `addendum.md`, `decision-log.md`; Validate: `validation-report.html` + `.md` |
-| `bmad-create-ux-design` | Design user experience (when UX matters)                                            | `ux-spec.md`                                      |
+| `bmad-ux`               | Design user experience (when UX matters) — DESIGN.md (visual) + EXPERIENCE.md (behavioral) spine pair | `DESIGN.md`, `EXPERIENCE.md`, `.decision-log.md`  |
 
 :::tip[Three intents in one skill]
 `bmad-prd` handles the full PRD lifecycle. State your intent when invoking or the skill will ask:

docs/tutorials/getting-started.md

@@ -162,7 +162,7 @@ All workflows in this phase are optional. [**Not sure which to use?**](../explan
 - Run `bmad-quick-dev` — it handles planning and implementation in a single workflow, skip to implementation
 
 :::note[UX Design (Optional)]
-If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD.
+If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-ux`) after creating your PRD.
 :::
 
 ### Phase 3: Solutioning (BMad Method/Enterprise)

docs/vi-vn/bmad-developer-guide.md

@@ -694,15 +694,7 @@ Review kiểu "devil's advocate" — giả định vấn đề luôn tồn tại
 - Tìm những gì **còn thiếu**, không chỉ những gì sai
 - Trực giao với Edge Case Hunter
 
-### 8.4. Distillator — Nén tài liệu cho LLM
+### 8.4. Shard Large Documents — Tách file lớn
-
-```bash
-bmad-distillator
-```
-
-Khi tài liệu quá lớn (PRD dài, Architecture phức tạp), Distillator nén nội dung tối ưu cho LLM mà không mất thông tin quan trọng.
-
-### 8.5. Shard Large Documents — Tách file lớn
 
 ```bash
 bmad-shard-doc

docs/vi-vn/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Khai thác nâng cao"
 description: Buộc LLM xem xét lại kết quả của nó bằng các phương pháp lập luận có cấu trúc
 sidebar:
-  order: 6
+  order: 4
 ---
 
 Buộc LLM xem xét lại những gì nó vừa tạo ra. Bạn chọn một phương pháp lập luận, nó áp dụng phương pháp đó lên chính output của mình, rồi bạn quyết định có giữ các cải tiến hay không.

docs/vi-vn/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Đánh giá đối kháng"
 description: Kỹ thuật lập luận ép buộc giúp tránh các bản review lười kiểu "nhìn ổn"
 sidebar:
-  order: 5
+  order: 9
 ---
 
 Buộc quá trình phân tích đi sâu hơn bằng cách ép phải tìm ra vấn đề.

docs/vi-vn/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "Giai đoạn phân tích: từ ý tưởng đến nền tảng"
 description: Động não, nghiên cứu, product brief và PRFAQ là gì, và nên dùng từng công cụ khi nào
 sidebar:
-  order: 1
+  order: 2
 ---
 
 Giai đoạn phân tích (giai đoạn 1) giúp bạn suy nghĩ rõ ràng về sản phẩm trước khi cam kết bắt tay vào xây dựng. Mọi công cụ trong giai đoạn này đều là tùy chọn, nhưng nếu bỏ qua toàn bộ phần phân tích thì PRD của bạn sẽ được dựng trên giả định thay vì hiểu biết thực chất.

docs/vi-vn/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "Động não ý tưởng"
 description: Các phiên sáng tạo tương tác sử dụng hơn 60 kỹ thuật khơi ý đã được kiểm chứng
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Mở khóa sự sáng tạo của bạn thông qua quá trình khám phá có hướng dẫn.

docs/vi-vn/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Xem trước Checkpoint"
 description: Review có người trong vòng lặp với hỗ trợ của LLM, dẫn bạn đi qua thay đổi từ mục đích đến chi tiết
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` là một workflow review tương tác có người trong vòng lặp với hỗ trợ của LLM. Nó dẫn bạn đi qua một thay đổi mã nguồn, từ mục đích và bối cảnh đến các chi tiết quan trọng, để bạn có thể quyết định có nên phát hành, làm lại, hay đào sâu thêm.

docs/vi-vn/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ cho dự án đã tồn tại"
 description: Các câu hỏi phổ biến khi dùng BMad Method trên dự án đã tồn tại
 sidebar:
-  order: 8
+  order: 12
 ---
 
 Các câu trả lời nhanh cho những câu hỏi thường gặp khi làm việc với dự án đã tồn tại bằng BMad Method (BMM).

docs/vi-vn/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Chế độ Party"
 description: Cộng tác đa agent - đưa tất cả agent AI vào cùng một cuộc trò chuyện
 sidebar:
-  order: 7
+  order: 10
 ---
 
 Đưa tất cả agent AI của bạn vào cùng một cuộc trò chuyện.

docs/vi-vn/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Ngăn xung đột giữa các agent"
 description: Cách kiến trúc ngăn xung đột khi nhiều agent cùng triển khai một hệ thống
 sidebar:
-     order: 4
+     order: 6
 ---
 
 Khi nhiều agent AI cùng triển khai các phần khác nhau của hệ thống, chúng có thể đưa ra các quyết định kỹ thuật mâu thuẫn nhau. Tài liệu kiến trúc ngăn điều đó bằng cách thiết lập các tiêu chuẩn dùng chung.

docs/vi-vn/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Bối cảnh dự án"
 description: Cách project-context.md định hướng các agent AI theo quy tắc và ưu tiên của dự án
 sidebar:
-  order: 7
+  order: 11
 ---
 
 Tệp `project-context.md` là kim chỉ nam cho việc triển khai của các agent AI trong dự án của bạn. Tương tự như một "bản hiến pháp" trong các hệ thống phát triển khác, nó ghi lại các quy tắc, pattern và ưu tiên giúp việc sinh mã được nhất quán trong mọi workflow.

docs/vi-vn/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Phát triển nhanh"
 description: Giảm ma sát có người trong vòng lặp mà vẫn giữ các điểm kiểm tra bảo vệ chất lượng đầu ra
 sidebar:
-  order: 2
+  order: 7
 ---
 
 Đưa ý định vào, nhận thay đổi mã nguồn ra, với số lần cần con người nhảy vào giữa quy trình ít nhất có thể - nhưng không đánh đổi chất lượng.

docs/vi-vn/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Vì sao solutioning quan trọng"
 description: Hiểu vì sao giai đoạn solutioning là tối quan trọng đối với dự án nhiều epic
 sidebar:
-  order: 3
+  order: 5
 ---
 
 Giai đoạn 3 (Solutioning) biến **xây gì** (từ giai đoạn Planning) thành **xây như thế nào** (thiết kế kỹ thuật). Giai đoạn này ngăn xung đột giữa các agent trong dự án nhiều epic bằng cách ghi lại các quyết định kiến trúc trước khi bắt đầu triển khai.

docs/vi-vn/how-to/established-projects.md

@@ -2,7 +2,7 @@
 title: "Dự án đã tồn tại"
 description: Cách sử dụng BMad Method trên các codebase hiện có
 sidebar:
-  order: 6
+  order: 7
 ---
 
 Sử dụng BMad Method hiệu quả khi làm việc với các dự án hiện có và codebase legacy.

docs/vi-vn/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: 'Cách mở rộng BMad cho tổ chức của bạn'
 description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent
 sidebar:
-  order: 9
+  order: 11
 ---
 
 Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.

docs/vi-vn/how-to/get-answers-about-bmad.md

@@ -2,7 +2,7 @@
 title: "Cách tìm câu trả lời về BMad"
 description: Sử dụng LLM để tự nhanh chóng trả lời các câu hỏi về BMad
 sidebar:
-        order: 4
+        order: 5
 ---
 
 Hãy dùng trợ giúp tích hợp sẵn của BMad, tài liệu nguồn, hoặc cộng đồng để tìm câu trả lời, theo thứ tự từ nhanh nhất đến đầy đủ nhất.

docs/vi-vn/how-to/project-context.md

@@ -2,7 +2,7 @@
 title: "Quản lý bối cảnh dự án"
 description: Tạo và duy trì project-context.md để định hướng cho các agent AI
 sidebar:
-  order: 8
+  order: 9
 ---
 
 Sử dụng tệp `project-context.md` để đảm bảo các agent AI tuân theo ưu tiên kỹ thuật và quy tắc triển khai của dự án trong suốt mọi workflow. Để đảm bảo tệp này luôn sẵn có, bạn cũng có thể thêm dòng `Important project context and conventions are located in [path to project context]/project-context.md` vào file context của công cụ hoặc file always rules của bạn (như `AGENTS.md`).

docs/vi-vn/how-to/quick-fixes.md

@@ -2,7 +2,7 @@
 title: "Sửa nhanh"
 description: Cách thực hiện các sửa nhanh và thay đổi ad-hoc
 sidebar:
-  order: 5
+  order: 6
 ---
 
 Sử dụng **Quick Dev** cho sửa lỗi, refactor, hoặc các thay đổi nhỏ có mục tiêu rõ ràng mà không cần quy trình BMad Method đầy đủ.

docs/vi-vn/how-to/shard-large-documents.md

@@ -2,7 +2,7 @@
 title: "Hướng dẫn chia nhỏ tài liệu"
 description: Tách các tệp markdown lớn thành nhiều tệp nhỏ có tổ chức để quản lý context tốt hơn
 sidebar:
-       order: 9
+       order: 10
 ---
 
 Sử dụng công cụ `bmad-shard-doc` nếu bạn cần tách các tệp markdown lớn thành nhiều tệp nhỏ có tổ chức để quản lý context tốt hơn.

docs/vi-vn/how-to/upgrade-to-v6.md

@@ -2,7 +2,7 @@
 title: "Cách nâng cấp lên v6"
 description: Di chuyển từ BMad v4 sang v6
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Sử dụng trình cài đặt BMad để nâng cấp từ v4 lên v6, bao gồm khả năng tự động phát hiện bản cài đặt cũ và hỗ trợ di chuyển.

docs/vi-vn/reference/commands.md

@@ -2,7 +2,7 @@
 title: Các skill
 description: Tài liệu tham chiếu cho skill của BMad — skill là gì, hoạt động ra sao và tìm ở đâu.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills là các prompt dựng sẵn để nạp agent, chạy workflow hoặc thực thi task bên trong IDE của bạn. Trình cài đặt BMad sinh chúng từ các module bạn đã chọn tại thời điểm cài đặt. Nếu sau này bạn thêm, xóa hoặc thay đổi module, hãy chạy lại trình cài đặt để đồng bộ skills (xem [Khắc phục sự cố](#khắc-phục-sự-cố)).

docs/vi-vn/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Công cụ cốt lõi
 description: Tài liệu tham chiếu cho mọi tác vụ và quy trình tích hợp sẵn có trong mọi bản cài BMad mà không cần module bổ sung.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Mọi bản cài BMad đều bao gồm một tập skill cốt lõi có thể dùng cùng với bất cứ việc gì bạn đang làm, các tác vụ và quy trình độc lập hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Chúng luôn có sẵn bất kể bạn cài những module tùy chọn nào.
@@ -18,7 +18,7 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
 | [`bmad-help`](#bmad-help) | Tác vụ | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo |
 | [`bmad-brainstorming`](#bmad-brainstorming) | Quy trình | Tổ chức các phiên brainstorming có tương tác |
 | [`bmad-party-mode`](#bmad-party-mode) | Quy trình | Điều phối thảo luận nhóm nhiều agent |
-| [`bmad-distillator`](#bmad-distillator) | Tác vụ | Nén tài liệu tối ưu cho LLM mà không mất thông tin |
+| [`bmad-spec`](#bmad-spec) | Quy trình | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
 | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tác vụ | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp |
 | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tác vụ | Rà soát hoài nghi để tìm chỗ thiếu và chỗ sai |
 | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tác vụ | Phân tích toàn bộ nhánh rẽ để tìm trường hợp biên chưa được xử lý |
@@ -97,33 +97,6 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
 
 **Đầu ra:** Cuộc hội thoại nhiều agent theo thời gian thực, vẫn giữ nguyên cá tính từng agent
 
-## bmad-distillator
-
-**Nén tài liệu nguồn tối ưu cho LLM mà không mất thông tin.** Công cụ này tạo ra các bản chưng cất dày đặc, tiết kiệm token nhưng vẫn giữ nguyên toàn bộ thông tin cho LLM dùng về sau. Có thể xác minh bằng tái dựng hai chiều.
-
-**Dùng khi:**
-
-- Một tài liệu quá lớn so với context window của LLM
-- Bạn cần phiên bản tiết kiệm token của tài liệu nghiên cứu, đặc tả hoặc artifact lập kế hoạch
-- Bạn muốn xác minh rằng không có thông tin nào bị mất trong quá trình nén
-- Các agent sẽ cần tham chiếu và tìm thông tin trong đó thường xuyên
-
-**Cách hoạt động:**
-
-1. **Analyze** — Đọc tài liệu nguồn, nhận diện mật độ thông tin và cấu trúc
-2. **Compress** — Chuyển văn xuôi thành dạng bullet dày đặc, bỏ trang trí không cần thiết
-3. **Verify** — Kiểm tra tính đầy đủ để đảm bảo mọi thông tin gốc còn nguyên
-4. **Validate** *(tùy chọn)* — Tái dựng hai chiều để chứng minh nén không mất mát
-
-**Đầu vào:**
-
-- `source_documents` *(bắt buộc)* — Đường dẫn file, thư mục hoặc mẫu glob
-- `downstream_consumer` *(tùy chọn)* — Thành phần sẽ dùng đầu ra này, ví dụ "PRD creation"
-- `token_budget` *(tùy chọn)* — Kích thước mục tiêu gần đúng
-- `--validate` *(cờ)* — Chạy kiểm tra tái dựng hai chiều
-
-**Đầu ra:** Một hoặc nhiều file markdown distillate kèm báo cáo tỷ lệ nén, ví dụ `3.2:1`
-
 ## bmad-advanced-elicitation
 
 **Đẩy đầu ra của LLM qua các phương pháp tinh luyện lặp.** Công cụ này chọn từ thư viện kỹ thuật elicitation để cải thiện nội dung một cách có hệ thống qua nhiều lượt.

docs/vi-vn/reference/modules.md

@@ -2,7 +2,7 @@
 title: Các Module Chính Thức
 description: Các module bổ sung để xây agent tùy chỉnh, tăng cường sáng tạo, phát triển game và kiểm thử
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad được mở rộng thông qua các module chính thức mà bạn chọn trong quá trình cài đặt. Những module bổ sung này cung cấp agent, workflow và task chuyên biệt cho các lĩnh vực cụ thể, vượt ra ngoài phần lõi tích hợp sẵn và BMM (Agile suite).

docs/vi-vn/reference/testing.md

@@ -2,7 +2,7 @@
 title: Các Tùy Chọn Kiểm Thử
 description: So sánh workflow QA tích hợp sẵn với module Test Architect (TEA) cho tự động hóa kiểm thử.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad cung cấp hai hướng kiểm thử: workflow QA tích hợp sẵn để tạo test nhanh và module Test Architect có thể cài thêm cho chiến lược kiểm thử c<><63>p doanh nghiệp.

docs/vi-vn/reference/workflow-map.md

@@ -37,7 +37,7 @@ Xác định cần xây gì và xây cho ai.
 | Quy trình | Mục đích | Tạo ra |
 | --------------------------- | ---------------------------------------- | ------------ |
 | `bmad-create-prd` | Xác định yêu cầu (FR/NFR) | `PRD.md` |
-| `bmad-create-ux-design` | Thiết kế trải nghiệm người dùng khi UX là yếu tố quan trọng | `ux-spec.md` |
+| `bmad-ux`            | Thiết kế trải nghiệm người dùng khi UX là yếu tố quan trọng | `DESIGN.md`, `EXPERIENCE.md` |
 
 ## Giai đoạn 3: Định hình giải pháp
 

docs/vi-vn/tutorials/getting-started.md

@@ -150,7 +150,7 @@ Tất cả workflow trong phase này đều là tùy chọn. [**Chưa chắc nê
 - Chạy `bmad-quick-dev` — workflow này gộp cả planning và implementation trong một lần, nên bạn có thể chuyển thẳng sang triển khai
 
 :::note[Thiết kế UX (Tùy chọn)]
-Nếu dự án của bạn có giao diện người dùng, hãy gọi **UX-Designer agent** (`bmad-agent-ux-designer`) và chạy workflow thiết kế UX (`bmad-create-ux-design`) sau khi tạo PRD.
+Nếu dự án của bạn có giao diện người dùng, hãy gọi **UX-Designer agent** (`bmad-agent-ux-designer`) và chạy workflow thiết kế UX (`bmad-ux`) sau khi tạo PRD.
 :::
 
 ### Phase 3: Solutioning (BMad Method/Enterprise)

docs/zh-cn/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "高级启发"
 description: 使用结构化推理方法推动 LLM 重新思考其工作
 sidebar:
-  order: 6
+  order: 4
 ---
 
 高级启发（advanced elicitation）是“第二轮思考”机制：不是笼统地让模型“再来一次”，而是让它按指定推理方法重审自己的输出。

docs/zh-cn/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "对抗性评审"
 description: 防止懒惰“看起来不错”评审的强制推理技术
 sidebar:
-  order: 5
+  order: 9
 ---
 
 对抗性评审（adversarial review）是一种“强制找问题”的评审方法：不允许直接“Looks good”，必须给出可验证发现，或者明确解释为什么没有发现。

docs/zh-cn/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "分析阶段：从想法到基础"
 description: 头脑风暴、调研、产品简报和 PRFAQ 分别是什么——以及何时使用
 sidebar:
-  order: 1
+  order: 2
 ---
 
 分析阶段（Phase 1）帮助你在决定动手构建之前，把产品想清楚。这个阶段的每个工具都是可选的，但如果完全跳过分析，你的 PRD 就是建立在假设而非洞察之上。

docs/zh-cn/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "头脑风暴"
 description: 使用 60+ 种经过验证的构思技术进行互动创意会议
 sidebar:
-  order: 2
+  order: 3
 ---
 
 `bmad-brainstorming` 是一个“思考引导”工作流：它不替你拍脑袋给答案，而是用结构化提问把你的想法挖出来、扩展开、再收敛成可执行方向。

docs/zh-cn/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "检查点预览"
 description: LLM 辅助的人机协作审查，引导你从目的到细节逐步走过一个变更
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` 是一个交互式的、LLM 辅助的人机协作审查工作流。它带你逐步走过一个代码变更——从目的和上下文到细节——让你能做出知情决策：是发布、返工，还是深入挖掘。

docs/zh-cn/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "既有项目常见问题"
 description: 关于在既有项目上使用 BMad Method 的常见问题
 sidebar:
-  order: 8
+  order: 12
 ---
 关于在 established projects（既有项目）中使用 BMad Method 的高频问题，快速说明如下。
 

docs/zh-cn/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "派对模式"
 description: 多智能体协作——将所有 AI 智能体汇聚到一次对话中
 sidebar:
-  order: 7
+  order: 10
 ---
 
 `bmad-party-mode` 用于多角色协作讨论：把 PM、架构、开发、UX 等视角放到同一轮对话里，快速暴露分歧、对齐取舍。

docs/zh-cn/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "防止智能体冲突"
 description: 架构如何在多个智能体实现系统时防止冲突
 sidebar:
-  order: 4
+  order: 6
 ---
 
 当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。

docs/zh-cn/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "项目上下文"
 description: project-context.md 如何使用项目规则和偏好指导 AI 智能体
 sidebar:
-  order: 7
+  order: 11
 ---
 
 `project-context.md` 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 `story` 中做出一致决策。

docs/zh-cn/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "快速开发"
 description: 在不牺牲输出质量检查点的情况下减少人机交互的摩擦
 sidebar:
-  order: 2
+  order: 7
 ---
 
 `bmad-quick-dev` 的目标很直接：在保证质量边界的前提下，把“意图到代码”的人机往返轮次降到最低。

docs/zh-cn/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "为什么解决方案阶段很重要"
 description: 理解为什么解决方案阶段对于多史诗项目至关重要
 sidebar:
-  order: 3
+  order: 5
 ---
 
 Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。

docs/zh-cn/how-to/customize-bmad.md

@@ -2,7 +2,7 @@
 title: "如何自定义 BMad"
 description: 自定义智能体、工作流和模块，同时保持更新兼容性
 sidebar:
-  order: 7
+  order: 8
 ---
 
 使用 `.customize.yaml` 文件，自定义智能体（agent）的行为、角色（persona）和菜单，同时在后续更新中保留你的改动。

docs/zh-cn/how-to/established-projects.md

@@ -2,7 +2,7 @@
 title: "既有项目"
 description: 如何在现有代码库中使用 BMad Method
 sidebar:
-  order: 6
+  order: 7
 ---
 
 当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。

docs/zh-cn/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: "如何为组织扩展 BMad"
 description: 五个自定义方案，无需 fork 即可重塑 BMad——涵盖智能体全局规则、工作流约定、外部发布、模板替换和花名册变更
 sidebar:
-  order: 9
+  order: 11
 ---
 
 BMad 的自定义机制让组织无需编辑已安装文件或 fork 技能就能重塑行为。本指南介绍五个方案，覆盖大部分企业级需求。

docs/zh-cn/how-to/get-answers-about-bmad.md

@@ -2,7 +2,7 @@
 title: "如何获取关于 BMad 的答案"
 description: 使用 LLM 快速回答您自己的 BMad 问题
 sidebar:
-  order: 4
+  order: 5
 ---
 
 ## 先从 BMad-Help 开始

docs/zh-cn/how-to/project-context.md

@@ -2,7 +2,7 @@
 title: "管理项目上下文"
 description: 创建并维护 project-context.md 以指导 AI 智能体
 sidebar:
-  order: 8
+  order: 9
 ---
 
 使用 `project-context.md`，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。

docs/zh-cn/how-to/quick-fixes.md

@@ -2,7 +2,7 @@
 title: "快速修复"
 description: 如何进行快速修复和临时更改
 sidebar:
-  order: 5
+  order: 6
 ---
 
 对于 bug 修复、重构或小范围改动，使用 **Quick Dev** 即可，不必走完整的 BMad Method。

docs/zh-cn/how-to/shard-large-documents.md

@@ -2,7 +2,7 @@
 title: "文档分片指南"
 description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文
 sidebar:
-  order: 9
+  order: 10
 ---
 
 当单个 Markdown 文档过大、影响模型读取时，可使用 `bmad-shard-doc` 工作流把文档拆成按章节组织的小文件，降低上下文压力。

docs/zh-cn/how-to/upgrade-to-v6.md

@@ -2,7 +2,7 @@
 title: "如何升级到 v6"
 description: 从 BMad v4 迁移到 v6
 sidebar:
-  order: 3
+  order: 4
 ---
 
 使用 BMad 安装程序把 v4 升级到 v6。安装程序会自动识别旧安装，并提供迁移辅助，帮助你在已有项目中平滑过渡。