bmad-method 6.7.0 → 6.7.1-next.1

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

@@ -0,0 +1,100 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-ux.
+# Overrides:
+#   {project-root}/_bmad/custom/bmad-ux.toml         (team)
+#   {project-root}/_bmad/custom/bmad-ux.user.toml    (personal)
+# Merge rules: scalars override, arrays append.
+
+[workflow]
+
+# Steps to run before/after standard activation. Append-only.
+activation_steps_prepend = []
+activation_steps_append = []
+
+# Persistent facts loaded at activation and kept in mind for the run.
+# Entries: literal sentence, `skill:NAME`, or `file:PATH` (glob ok).
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Runs at workflow completion. String or array of instructions.
+on_complete = ""
+
+# Reference DESIGN.md spines the distillation subagent reads to anchor shape
+# and editorial richness. Convention-compliant with the Google Labs DESIGN.md
+# spec (https://github.com/google-labs-code/design.md). Append entries via
+# override TOML to seed an org-specific canonical aesthetic.
+# Each entry: `file:PATH` (or bare relative path, resolved skill-relative).
+design_md_examples = [
+  "assets/design-example-mobile.md",
+  "assets/design-example-shadcn.md",
+  "assets/design-example-editorial.md",
+]
+
+# Reference EXPERIENCE.md spines for the behavioral/flow/IA layer. Each entry:
+# `file:PATH` (or bare relative path, resolved skill-relative).
+experience_md_examples = [
+  "assets/experience-example-mobile.md",
+  "assets/experience-example-shadcn.md",
+]
+
+# Design handoff targets — external tools that can take over the design /
+# visual identity work. The user runs the tool externally and saves outputs
+# (whatever the tool produces — DESIGN.md, Figma files, React components,
+# HTML mocks) to {doc_workspace}.
+# Each entry: `tool:NAME: <directive>`, `skill:NAME`, or plain-text descriptor.
+# Default: Google Stitch (emits DESIGN.md + per-screen HTML). Other producers:
+# Vercel v0, Figma, Galileo, Anima, internal generators.
+design_handoffs = [
+  "Google Stitch (https://stitch.withgoogle.com) — emits DESIGN.md + per-screen HTML. Paste assembled prompt; save outputs to {doc_workspace}.",
+]
+
+# HTML skeleton filled in by the validation synthesis pass.
+validation_report_template = "assets/validation-report-template.html"
+
+# Run folder. DESIGN.md, EXPERIENCE.md, .decision-log.md, .working/
+# (creative-tool artifacts), imports/ (user-supplied screens / brand decks /
+# Figma exports / sketches), optional mockups/ and wireframes/ (promoted
+# artifacts), optional validation-report.* all land inside
+# {ux_output_path}/{run_folder_pattern}/.
+ux_output_path = "{planning_artifacts}/ux-designs"
+run_folder_pattern = "ux-{project_name}-{date}"
+
+# Creative tools registry. Collaborative renderers invoked on demand during
+# Discovery and at Finalize. Entry forms: `file:PATH`, `skill:NAME`,
+# `tool:MCP_TOOL: <directive>`, or plain text. Defaults ship for HTML color
+# themes, HTML design directions, Excalidraw wireframes (Discovery), and
+# 1:1 HTML key-screen mockups (Finalize). Working artifacts land in
+# {doc_workspace}/.working/; finalize promotes those with lasting reference
+# value to mockups/ or wireframes/. See references/creative-tools.md.
+creative_tools = [
+  "file:assets/color-themes.md",
+  "file:assets/design-directions.md",
+  "file:assets/excalidraw-wireframe.md",
+  "file:assets/key-screens.md",
+]
+
+# Polish passes applied to DESIGN.md and EXPERIENCE.md at finalize.
+# Entries: `skill:NAME`, `file:PATH`, or plain text directive.
+# Suggested order: structural → content/voice → prose mechanics.
+doc_standards = [
+  "skill:bmad-editorial-review-structure",
+  "skill:bmad-editorial-review-prose",
+]
+
+# Information retrieval registry. Consulted on demand when the conversation
+# surfaces a matching need. Distinct from creative_tools (artifact production).
+# Example: "When researching component patterns, consult corp:design_system_search."
+external_sources = []
+
+# Routes outputs beyond local files at Finalize. Returned URLs/IDs surfaced
+# to the user. Unavailable tools skipped and flagged.
+# Example: "Upload DESIGN.md to Confluence via corp:confluence_upload (space_key='DESIGN')."
+external_handoffs = []
+
+# Reviewers spawned at Finalize step 4 and at Validate intent, alongside
+# the rubric walker. Entries: `skill:NAME`, `file:PATH`, or plain text.
+# Common ad-hoc add (judged by the skill): accessibility-focused reviewer
+# for consumer / regulated work.
+finalize_reviewers = []

package/src/bmm-skills/2-plan-workflows/bmad-ux/references/creative-tools.md

@@ -0,0 +1,19 @@
+# Creative Tools
+
+`{workflow.creative_tools}` is a registry of collaborative renderers invoked on demand when seeing options helps the user decide. Entries follow the standard prefix convention: `skill:NAME`, `file:PATH`, `tool:MCP_TOOL_NAME: <directive>`, or plain-text directive.
+
+Defaults ship for HTML color themes, HTML design directions, Excalidraw wireframes (Discovery), and 1:1 HTML key-screen mocks (Finalize). Teams append more via override TOML — Figma MCP, custom skills, prompt-based mood boards.
+
+## When to invoke
+
+Decision moments where a visual beats more conversation: picking color tokens, picking a visual personality among directions, sketching IA, mocking a tricky flow. Fast-path users typically skip; coaching-path users typically lean in. Read the room.
+
+## Artifact handling
+
+Every renderer writes to `{doc_workspace}/.working/` with a descriptive filename. `.working/` is the audit trail and survives the run. At Finalize, the facilitator walks `.working/` with the user and promotes artifacts with lasting reference value to `{doc_workspace}/mockups/` (HTML anchoring a brand or layout decision) or `{doc_workspace}/wireframes/` (Excalidraw a dev would glance at). Bar for promotion: *would a future reader of `DESIGN.md` or `EXPERIENCE.md` open this?* Default is leave-in-`.working/`.
+
+## Renderer contract
+
+The parent passes the subagent: current `.decision-log.md`, relevant prior `.working/` captures, the user's stated intent for this pass, the output path. The subagent writes its artifact under `.working/` and returns ONLY a compact summary (file path, one line per variant, mode coverage). Parent never holds the full payload.
+
+For HTML, open in browser when interactive: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`. Skip in headless.

package/src/bmm-skills/2-plan-workflows/bmad-ux/references/design-md-spec.md

@@ -0,0 +1,50 @@
+# DESIGN.md Spec — Working Reference
+
+Source of truth: [google-labs-code/design.md](https://github.com/google-labs-code/design.md) (Apache 2.0, Google Labs, April 2026). This file is a working summary; the URL wins on conflict.
+
+## Structure
+
+YAML frontmatter (machine-readable tokens) + markdown body (human-readable rationale, prose sections).
+
+## Frontmatter tokens
+
+| Key | Type | Notes |
+|---|---|---|
+| `name` | string | Required. Brand or system name. |
+| `description` | string | One-line statement of what this system is. |
+| `colors` | flat object | Kebab-case keys. Values are hex strings (`'#FBF9F4'`). |
+| `typography` | nested object | Each value: an object with any subset of `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`. |
+| `rounded` | object | Scale names (`sm`, `md`, `lg`, `xl`, `full`, `DEFAULT`) → CSS dimensions. `full` is conventionally `9999px`. |
+| `spacing` | object | Scale levels (`'1'`, `'2'`, ...) or named tokens (`gutter`, `margin-mobile`, `editorial-gap`) → dimensions. |
+| `components` | object | Component-name → object of component tokens mapped to values or `{path.to.token}` references. |
+
+## Body sections (omittable, order-locked when present)
+
+1. **Brand & Style** — Aesthetic posture in prose. The editorial voice — what *kind* of thing this is.
+2. **Colors** — Per-color story. Why each exists, where it's used, what it's *not* used for.
+3. **Typography** — Type roles, ramp, and rules. Platform conventions noted semantically when inherited.
+4. **Layout & Spacing** — Spacing scale narrative, grid behavior, margins, gutters, breakpoint rules.
+5. **Elevation & Depth** — Shadow language and tonal layering rules.
+6. **Shapes** — Corner radii rules and the aesthetic logic behind them.
+7. **Components** — Per-component visual specs: anatomy, color usage, sizing, state appearance.
+8. **Do's and Don'ts** — Hard visual rules — what to do, what to avoid.
+
+Sections may be omitted when not relevant; order is locked when present.
+
+## Cross-reference syntax
+
+`{path.to.token}` used in prose and inside component objects to reference frontmatter tokens. Examples:
+
+- `{colors.primary}`
+- `{typography.body.fontSize}`
+- `{rounded.md}`
+- `{spacing.4}`
+
+The path follows the YAML structure.
+
+## Common patterns
+
+- **Light/dark mode.** Either separate kebab-case tokens (`surface-base` / `surface-base-dark`) or separate DESIGN.md files per mode. The spec allows either; pick the form that reads cleanest for the product.
+- **Platform conventions.** When inheriting from native platforms (iOS UIKit, Android Compose, Apple Human Interface Guidelines), use a `note` field instead of literal values: `{ note: 'iOS Title 1 · Android Headline Small' }`. The spec is the spec; the platform owns the rendered values.
+- **UI-system inheritance.** When inheriting from shadcn / MUI / Tailwind / internal design system, reference the system's tokens by name rather than restating values. DESIGN.md specifies only the deltas (brand color overrides, typography swaps, component customizations).
+- **Component tokens.** The `components` frontmatter entry maps each named component (e.g., `button-primary`) to its specific token values. Use `{path.to.token}` references freely; the resolver flattens at consumption time.

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

@@ -0,0 +1,37 @@
+# Headless Mode
+
+Load this file when invoked headless. Follow it for the whole run.
+
+## Detection
+
+Headless when any of: caller sets `headless: true` (or harness equivalent); invocation is from another skill or non-interactive runner; `{workflow.activation_steps_prepend}` declares it; first message is an automation context pre-supplying inputs. Ambiguous → default interactive.
+
+## Inputs
+
+Free-form structured payload in the first message:
+
+- `intent` — `"create"`, `"update"`, or `"validate"`. If absent, infer from the artifact set.
+- **Create**: any source spec (PRD, brief, requirements list, design-thinking output, prior UX — text, path, or URL) plus brand / platform / accessibility notes; `doc_workspace` if a specific run folder is required.
+- **Update**: existing workspace containing `DESIGN.md` + `EXPERIENCE.md` (or path to either) + change signal.
+- **Validate**: existing workspace containing `DESIGN.md` + `EXPERIENCE.md` (or path to either). Workspace defaults to the spines' containing directory.
+
+Inferences → `assumptions[]`. Gaps needing a human decision → `open_questions[]`. Do not invent persona, brand, accessibility, or scope detail.
+
+Creative tools default off in headless. Caller can override; artifacts land in `.working/` and are not promoted unless the caller signals.
+
+## Behavior
+
+Do not ask. Do not greet. Complete the intent from what's provided, what exists in `{doc_workspace}`, or what you can discover. If intent stays ambiguous after inference, halt with `status: "blocked"` and a one-sentence `reason`.
+
+`status`:
+- `"complete"` — stands on its own.
+- `"partial"` — artifact produced but `open_questions[]` non-empty or critical inputs inferred.
+- `"blocked"` — no artifact produced.
+
+End with JSON matching `assets/headless-schemas.md`. `intent` reflects detected intent. Omit keys for artifacts not produced.
+
+## Mode-specific overrides
+
+**Update.** Apply the change. Log to `.decision-log.md` with rationale. Surface conflicts in `conflicts_with_prior_decisions[]`.
+
+**Validate.** Always write both `validation-report.html` and `validation-report.md` regardless of finding count. Always include `"offer_to_update": true`. Skip the browser-open step.

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

@@ -0,0 +1,115 @@
+# Validate
+
+Critique an existing spine pair (`DESIGN.md` + `EXPERIENCE.md`) or any format of UX the user provides, without changing it. The synthesis pipeline below is also used at the Reviewer Gate during Create / Update Finalize.
+
+## Orient
+
+Subagent-extract from `.decision-log.md`, sources in frontmatter, `imports/`, `mockups/`, `wireframes/`, `DESIGN.md`, `EXPERIENCE.md`. Parent assembles from extracts.
+
+## Reviewer Gate
+
+**Opt-in.** Reviewers are costly. At Finalize, ask first if the user wants to run UX validation with multiple subagent lenses. Default offered, easy skip. At Validate intent, skip that question, the user already invoked it.
+
+**Lens menu.** UNLESS HEADLESS MODE: Always present the lens picks before dispatching. Build the menu from: rubric walker (this file) + `{workflow.finalize_reviewers}` + ad-hoc reviewers the skill judges relevant. The user picks all, a subset, or none. Only picked lenses dispatch.
+
+Rubric walker prompt:
+
+> Validate the spine pair (`DESIGN.md` + `EXPERIENCE.md`) as the contract for downstream consumers (architecture, story-dev — human or AI). Can a consumer source-extract cleanly, with every reference resolving and every load-bearing decision committed? Read `{workflow.design_md_examples}` and `{workflow.experience_md_examples}` first.
+>
+> **Pass 1 — mechanical coverage.** Per category: extract, then list misses with location citations. No misses = **strong**.
+>
+> 1. **Flow coverage** (EXPERIENCE.md). Sources frontmatter → extract every UJ / requirement name. Verify each has a Key Flow with named protagonist, numbered steps, a climax beat, and a failure path where applicable.
+>
+> 2. **Token completeness** (DESIGN.md). Extract every token in the YAML frontmatter and every `{path.to.token}` reference in the prose. Verify each defined (see `references/design-md-spec.md` for type rules). **Color tokens missing hex (or light/dark pairs where applicable) are critical** — downstream code mirrors the spine. Platform conventions (native dynamic type, 8pt grid) may stay semantic. Contrast targets stated for load-bearing combinations.
+>
+> 3. **Component coverage** (both spines). Extract every component name used anywhere. Verify each has a row in DESIGN.md.Components (visual spec) *and* EXPERIENCE.md.Component Patterns (behavioral spec) — real rules, not one-word descriptions.
+>
+> 4. **State coverage** (EXPERIENCE.md). Walk every IA surface. List states it should have (empty, cold-load, focus, error, offline, permission-denied — whichever apply). Verify each covered.
+>
+> 5. **Visual reference coverage.** List every file in `mockups/`, `wireframes/`, `imports/`. Spines link to each inline at the relevant section and name what it illustrates; spines-win-on-conflict stated once. List orphans and unspecific references.
+>
+> **Pass 2 — judgment.** Verdict per category (*strong / adequate / thin / broken*); findings only where they add information.
+>
+> 6. **Bloat & overspecification.** Pixel specs where tokens cover it; source restatement (personas, FRs, scope); prose where a table works; sections no downstream consumer would read; decorative narrative untied to a decision. DESIGN.md prose may carry editorial voice; EXPERIENCE.md prose should not.
+>
+> 7. **Inheritance discipline.** `sources` frontmatter resolves. UJ / requirement names verbatim from sources. Glossary identical across spines and sources. Component names identical across all sections in both files. EXPERIENCE.md token references resolve to DESIGN.md tokens by name.
+>
+> 8. **Shape fit.** DESIGN.md sections in canonical order (Brand & Style → Colors → Typography → Layout & Spacing → Elevation & Depth → Shapes → Components → Do's and Don'ts; omittable but order-locked when present). EXPERIENCE.md required defaults present (Foundation, IA, Voice and Tone, Component Patterns, State Patterns, Interaction Primitives, Accessibility Floor, Key Flows). Dropped defaults defensible. Required-when-applicable present where triggered (Inspiration when sources / log show reference products or rejects; Responsive when multi-surface or breakpoints). Invented sections earn their place.
+>
+> Severity = downstream impact, not fix difficulty.
+>
+> Write to `{doc_workspace}/review-rubric.md`:
+>
+> ```markdown
+> # Spine Pair Review — {project_name}
+>
+> ## Overall verdict
+> [2–3 sentences]
+>
+> ## 1. Flow coverage — [verdict]
+> [What was checked.]
+> ### Findings
+> - **[critical|high|medium|low]** [finding] (location). *Fix:* [suggestion].
+>
+> (repeat 2–8)
+>
+> ## Mechanical notes
+> [Name inconsistencies, broken cross-refs, frontmatter completeness, Mermaid syntax.]
+> ```
+>
+> Return ONLY a compact summary: overall verdict, per-section verdicts, finding counts by severity, file path.
+
+The gate may dispatch `{workflow.finalize_reviewers}` and ad-hoc reviewers (accessibility for consumer / regulated). Each writes `review-{slug}.md` and returns a compact summary. Parallel.
+
+## Synthesis pipeline
+
+Under Validate intent, after every reviewer returns, render one consolidated report. Don't skip.
+
+1. Read every `{doc_workspace}/review-*.md`.
+2. Fill `{workflow.validation_report_template}`. No overall grade — the per-category verdicts and severity counts already say what's true. Synthesis paragraph lifts the rubric's overall verdict; add a second if extra reviewers shift the picture. One section per rubric category (open if thin / broken), one per extra reviewer (closed, adversarial voice preserved).
+3. Write `{doc_workspace}/validation-report.html`.
+4. Write the Markdown twin `{doc_workspace}/validation-report.md` — same content grouped by severity.
+5. Open HTML: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"`. Skip headless.
+
+Re-running overwrites the consolidated report; individual `review-*.md` files persist.
+
+## Markdown twin shape
+
+```markdown
+# Validation Report — {project_name}
+
+- **DESIGN.md:** `{design_path}`
+- **EXPERIENCE.md:** `{experience_path}`
+- **Run at:** {ISO timestamp}
+
+## Overall verdict
+{synthesis paragraphs}
+
+## Category verdicts
+- Flow coverage — {verdict}
+- Token completeness — {verdict}
+- Component coverage — {verdict}
+- State coverage — {verdict}
+- Visual reference coverage — {verdict}
+- Bloat & overspecification — {verdict}
+- Inheritance discipline — {verdict}
+- Shape fit — {verdict}
+
+## Findings by severity
+
+### Critical (n)
+**[Category or Reviewer]** — Title (§ location)
+{Note}
+Fix: {suggested fix}
+
+### High (n) / Medium (n) / Low (n)
+...
+
+## Reviewer files
+- `review-rubric.md`
+- ...
+```
+
+## Close
+
+Surface artifact paths. Always offer to roll findings into an Update.

package/src/bmm-skills/module-help.csv

@@ -16,7 +16,7 @@ BMad Method,bmad-technical-research,Technical Research,TR,Technical feasibility
 BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
 BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
 BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
-BMad Method,bmad-create-ux-design,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
+BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
 BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
 BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-create-architecture,,true,planning_artifacts,epics and stories
 BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report

package/tools/installer/core/installer.js

@@ -54,7 +54,7 @@ class Installer {
       }
 
       if (existingInstall.installed) {
-        await this._removeDeselectedModules(existingInstall, config, paths);
+        await this._removeDeselectedModules(existingInstall, config, paths, originalConfig._preserveModules || []);
         updateState = await this._prepareUpdateState(paths, config, existingInstall, officialModules);
         await this._removeDeselectedIdes(existingInstall, config, paths);
       }
@@ -76,25 +76,23 @@ class Installer {
       const results = [];
       const addResult = (step, status, detail = '', meta = {}) => results.push({ step, status, detail, ...meta });
 
-      // Capture previously installed skill IDs before they get overwritten
-      const previousSkillIds = new Set();
-      const prevCsvPath = path.join(paths.bmadDir, '_config', 'skill-manifest.csv');
-      if (await fs.pathExists(prevCsvPath)) {
-        try {
-          const csvParse = require('csv-parse/sync');
-          const content = await fs.readFile(prevCsvPath, 'utf8');
-          const records = csvParse.parse(content, { columns: true, skip_empty_lines: true });
-          for (const r of records) {
-            if (r.canonicalId) previousSkillIds.add(r.canonicalId);
-          }
-        } catch (error) {
-          await prompts.log.warn(`Failed to parse skill-manifest.csv: ${error.message}`);
-        }
-      }
+      // Capture previously installed skill rows before they get overwritten
+      const preservedModules = originalConfig._preserveModules || [];
+      const previousSkillManifestRows = await this._readSkillManifestRows(paths.bmadDir);
+      const previousSkillIds = this._getPreviousSkillIdsForCleanup(previousSkillManifestRows, preservedModules);
 
       const allModules = config.modules || [];
 
-      await this._installAndConfigure(config, originalConfig, paths, allModules, allModules, addResult, officialModules);
+      await this._installAndConfigure(
+        config,
+        originalConfig,
+        paths,
+        allModules,
+        allModules,
+        addResult,
+        officialModules,
+        previousSkillManifestRows,
+      );
 
       await this._setupIdes(config, allModules, paths, addResult, previousSkillIds);
 
@@ -144,10 +142,11 @@ class Installer {
    * Remove modules that were previously installed but are no longer selected.
    * No confirmation — the user's module selection is the decision.
    */
-  async _removeDeselectedModules(existingInstall, config, paths) {
+  async _removeDeselectedModules(existingInstall, config, paths, preservedModules = []) {
     const previouslyInstalled = new Set(existingInstall.moduleIds);
     const newlySelected = new Set(config.modules || []);
-    const toRemove = [...previouslyInstalled].filter((m) => !newlySelected.has(m) && m !== 'core');
+    const preserved = new Set(preservedModules);
+    const toRemove = [...previouslyInstalled].filter((m) => !newlySelected.has(m) && m !== 'core' && !preserved.has(m));
 
     for (const moduleId of toRemove) {
       const modulePath = paths.moduleDir(moduleId);
@@ -212,7 +211,16 @@ class Installer {
   /**
    * Install modules, create directories, generate configs and manifests.
    */
-  async _installAndConfigure(config, originalConfig, paths, officialModuleIds, allModules, addResult, officialModules) {
+  async _installAndConfigure(
+    config,
+    originalConfig,
+    paths,
+    officialModuleIds,
+    allModules,
+    addResult,
+    officialModules,
+    previousSkillManifestRows = [],
+  ) {
     const isQuickUpdate = config.isQuickUpdate();
     const moduleConfigs = officialModules.moduleConfigs;
 
@@ -291,25 +299,29 @@ class Installer {
 
         message('Generating manifests...');
         const manifestGen = new ManifestGenerator();
+        const preservedModules = originalConfig._preserveModules || [];
 
         const allModulesForManifest = config.isQuickUpdate()
           ? originalConfig._existingModules || allModules || []
-          : originalConfig._preserveModules
-            ? [...allModules, ...originalConfig._preserveModules]
+          : preservedModules.length > 0
+            ? [...allModules, ...preservedModules]
             : allModules || [];
 
         let modulesForCsvPreserve;
         if (config.isQuickUpdate()) {
           modulesForCsvPreserve = originalConfig._existingModules || allModules || [];
         } else {
-          modulesForCsvPreserve = originalConfig._preserveModules ? [...allModules, ...originalConfig._preserveModules] : allModules;
+          modulesForCsvPreserve = preservedModules.length > 0 ? [...allModules, ...preservedModules] : allModules;
         }
 
+        await this._trackPreservedModuleFiles(paths.bmadDir, preservedModules);
+
         await manifestGen.generateManifests(paths.bmadDir, allModulesForManifest, [...this.installedFiles], {
           ides: config.ides || [],
           preservedModules: modulesForCsvPreserve,
           moduleConfigs,
         });
+        await this._appendPreservedSkillManifestRows(paths.bmadDir, previousSkillManifestRows, preservedModules);
 
         // Apply post-install --set TOML patches. Runs after writeCentralConfig
         // (inside generateManifests above) so the patch operates on the
@@ -411,6 +423,62 @@ class Installer {
     }
   }
 
+  async _readSkillManifestRows(bmadDir) {
+    const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
+    if (!(await fs.pathExists(csvPath))) return [];
+
+    try {
+      const csvParse = require('csv-parse/sync');
+      const content = await fs.readFile(csvPath, 'utf8');
+      return csvParse.parse(content, { columns: true, skip_empty_lines: true });
+    } catch (error) {
+      await prompts.log.warn(`Failed to parse skill-manifest.csv: ${error.message}`);
+      return [];
+    }
+  }
+
+  _getPreviousSkillIdsForCleanup(previousRows, preservedModules = []) {
+    const preservedModuleSet = new Set(preservedModules || []);
+    const ids = new Set();
+    for (const row of previousRows || []) {
+      if (row.canonicalId && !preservedModuleSet.has(row.module)) {
+        ids.add(row.canonicalId);
+      }
+    }
+    return ids;
+  }
+
+  async _appendPreservedSkillManifestRows(bmadDir, previousRows, preservedModules = []) {
+    if (!previousRows || previousRows.length === 0 || preservedModules.length === 0) return;
+
+    const preservedModuleSet = new Set(preservedModules);
+    const rowsToPreserve = previousRows.filter((row) => row.canonicalId && row.module && preservedModuleSet.has(row.module));
+    if (rowsToPreserve.length === 0) return;
+
+    const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
+    if (!(await fs.pathExists(csvPath))) return;
+
+    const currentRows = await this._readSkillManifestRows(bmadDir);
+    const activeIds = new Set(currentRows.map((row) => row.canonicalId).filter(Boolean));
+    const appendedRows = [];
+
+    for (const row of rowsToPreserve) {
+      if (activeIds.has(row.canonicalId)) continue;
+      activeIds.add(row.canonicalId);
+      appendedRows.push(
+        [row.canonicalId, row.name || row.canonicalId, row.description || '', row.module, row.path || '']
+          .map((field) => this.escapeCSVField(field))
+          .join(','),
+      );
+    }
+
+    if (appendedRows.length === 0) return;
+
+    const currentContent = await fs.readFile(csvPath, 'utf8');
+    const prefix = currentContent.endsWith('\n') ? currentContent : `${currentContent}\n`;
+    await fs.writeFile(csvPath, prefix + appendedRows.join('\n') + '\n', 'utf8');
+  }
+
   /**
    * Restore custom and modified files that were backed up before the update.
    * No-op for fresh installs (updateState is null).
@@ -597,6 +665,15 @@ class Installer {
     }
   }
 
+  async _trackPreservedModuleFiles(bmadDir, preservedModules = []) {
+    for (const moduleName of preservedModules) {
+      const modulePath = path.join(bmadDir, moduleName);
+      if (await fs.pathExists(modulePath)) {
+        await this._trackFilesRecursive(modulePath);
+      }
+    }
+  }
+
   /**
    * Install official (non-custom) modules.
    * @param {Object} config - Installation configuration

package/tools/installer/ide/_config-driven.js

@@ -501,7 +501,7 @@ class ConfigDrivenIdeSetup {
 
     // Build removal set: previously installed skills + removals.txt entries
     let removalSet;
-    if (options.previousSkillIds && options.previousSkillIds.size > 0) {
+    if (options.previousSkillIds) {
       // Install/update flow: use pre-captured skill IDs (before manifest was overwritten)
       removalSet = new Set(options.previousSkillIds);
       if (resolvedBmadDir) {
@@ -547,7 +547,7 @@ class ConfigDrivenIdeSetup {
       // previousSkillIds — full uninstall or per-IDE removal via
       // cleanupByList), don't spare anything; the IDE itself is going away,
       // so its pointers should go with it.
-      const isInstallFlow = options.previousSkillIds && options.previousSkillIds.size > 0;
+      const isInstallFlow = !!options.previousSkillIds;
       const activeSkillIds = isInstallFlow ? await this._readActiveSkillIds(resolvedBmadDir) : new Set();
       const extension = this.installerConfig.commands_extension || '.md';
       await this.cleanupCommandPointers(

package/tools/installer/ui.js

@@ -110,6 +110,44 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
+  async _retainUnavailableInstalledModules(selectedModules, installedModuleIds, bmadDir, options = {}) {
+    const { OfficialModules } = require('./modules/official-modules');
+    const officialCodes = new Set(['core']);
+
+    const builtInModules = (await new OfficialModules().listAvailable()).modules || [];
+    for (const mod of builtInModules) {
+      officialCodes.add(mod.id);
+    }
+
+    const externalManager = new ExternalModuleManager();
+    const registryModules = await externalManager.listAvailable();
+    for (const mod of registryModules) {
+      officialCodes.add(mod.code);
+    }
+
+    const { CustomModuleManager } = require('./modules/custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const selectedSet = new Set(selectedModules);
+    const preserveModules = [];
+
+    for (const moduleId of installedModuleIds) {
+      if (moduleId === 'core') continue;
+      if (!selectedSet.has(moduleId) && !options.preserveUnselected) continue;
+      if (officialCodes.has(moduleId)) continue;
+
+      const customSource = await customMgr.findModuleSourceByCode(moduleId, { bmadDir });
+      if (!customSource) {
+        preserveModules.push(moduleId);
+      }
+    }
+
+    const preservedSet = new Set(preserveModules);
+    return {
+      selectedModules: selectedModules.filter((moduleId) => !preservedSet.has(moduleId)),
+      preserveModules,
+    };
+  }
+
   /**
    * Prompt for installation configuration
    * @param {Object} options - Command-line options from install command
@@ -273,6 +311,18 @@ class UI {
           selectedModules.unshift('core');
         }
 
+        const retainedModuleResult = await this._retainUnavailableInstalledModules(selectedModules, installedModuleIds, bmadDir, {
+          preserveUnselected: options.yes && !options.modules,
+        });
+        selectedModules = retainedModuleResult.selectedModules;
+        const preservedModules = retainedModuleResult.preserveModules;
+
+        if (preservedModules.length > 0) {
+          await prompts.log.warn(
+            `Retaining ${preservedModules.length} installed module(s) with no available source: ${preservedModules.join(', ')}`,
+          );
+        }
+
         // For existing installs, resolve per-module update decisions BEFORE
         // we clone anything. Reads the existing manifest's recorded channel
         // per module and prompts the user on available upgrades (patch/minor
@@ -317,6 +367,7 @@ class UI {
           setOverrides,
           skipPrompts: options.yes || false,
           channelOptions,
+          _preserveModules: preservedModules,
         };
       }
     }

package/tools/skill-validator.md

@@ -10,7 +10,7 @@ Before running inference-based validation, run the deterministic validator:
 node tools/validate-skills.js --json path/to/skill-dir
 ```
 
-This checks 14 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, WF-01, WF-02, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+This checks 12 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
 
 Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
 
@@ -98,24 +98,6 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
-### WF-01 — Only SKILL.md May Have `name` in Frontmatter
-
-- **Severity:** HIGH
-- **Applies to:** all `.md` files except `SKILL.md`
-- **Rule:** The `name` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `name:` in its frontmatter.
-- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `name:` key.
-- **Fix:** Remove the `name:` line from the file's frontmatter.
-- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `name` fields (to be revisited).
-
-### WF-02 — Only SKILL.md May Have `description` in Frontmatter
-
-- **Severity:** HIGH
-- **Applies to:** all `.md` files except `SKILL.md`
-- **Rule:** The `description` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `description:` in its frontmatter.
-- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `description:` key.
-- **Fix:** Remove the `description:` line from the file's frontmatter.
-- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `description` fields (to be revisited).
-
 ### WF-03 — workflow.md Frontmatter Variables Must Be Config or Runtime Only
 
 - **Severity:** HIGH