bmad-method 6.7.1 → 6.8.0

package/src/core-skills/bmad-spec/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: bmad-spec
+description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
+---
+
+# BMad Spec
+## Overview
+
+Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces **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 or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes.
+
+Multiple skills may call to update the same spec over time.
+
+## Conventions
+
+- Bare paths (e.g. `assets/spec-template.md`) resolve from the skill root.
+- `{skill-root}` is this skill's install dir; `{project-root}` is the working dir.
+- `{workflow.<name>}` resolves to fields in `customize.toml`.
+
+## On Activation
+
+1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
+3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
+4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Workspace
+
+The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{output_folder}/specs/spec-{slug}/`.
+
+`{slug}` describes the thing being specced, not the input shape:
+
+- Source artifact already carries a slug (e.g., `prd-foo-bar-2026-05-23/`): inherit (`foo-bar`).
+- Sparse, in-chat, or multi-source input: interactive asks; headless caller provides it as part of the input. If absent and underivable, headless blocks with `error_code: "missing_slug"`.
+- Same slug = same folder. A second invocation with the same `{slug}` lands at the existing spec folder and updates in place, preserving capability IDs.
+
+**No input.** Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing `error_code: "insufficient_intent"`.
+
+Inside the spec folder:
+
+```
+<spec-folder>/
+  SPEC.md                  ← uppercase, the kernel
+  <companion-1>.md         ← optional, content-typed (e.g. glossary.md)
+  <companion-2>.md
+  .decision-log.md         ← canonical memory for this spec
+```
+
+## The Operation
+
+Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in **Workspace** (ask or block). If a prior `SPEC.md` exists at the target folder, read it too — the operation becomes an update. Preserve capability IDs; new capabilities get the next unused `CAP-N`; never reuse retired IDs. Otherwise this is a create.
+
+When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream BMad skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.
+
+Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
+
+Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
+
+If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest `bmad-prd` (or sibling ceremony skill). This skill distills; it does not coach.
+
+## Load-bearing
+
+A claim is **load-bearing** if any consumer (downstream skill, implementing agent, verification pass) would change a decision without it.
+
+## Companions
+
+When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads `companions:` in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).
+
+**Spawn a companion when the content needs more than one kernel-shape line:** multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.
+
+Companions are either:
+
+- **Spec-authored** companions are written by bmad-spec and live as **siblings of SPEC.md** (e.g., `glossary.md`, `patron-archetypes.md`). bmad-spec owns them and may edit them on update operations.
+- **Adopted** companions are load-bearing artifacts written by an upstream skill that downstream still needs to read. bmad-spec references them into `companions:` by relative path but does NOT edit them (e.g., a `DESIGN.md` or `EXPERIENCE.md` from a UX run, an integration partner's API spec). The originating skill owns them.
+
+Two rules govern companions:
+
+1. **Name spec-authored companions for the content type they hold.** `glossary.md`, `<entity-class>.md` (e.g. `patron-archetypes.md`, `medication-routes.md`, `flight-modes.md`), `stack.md`, `conventions.md`, `brownfield.md`, `architecture-diagrams.md`, `state-machines.md`, `failure-modes.md`, `compliance-references.md`. The principle: "a reader should know what is inside before opening it." Adopted companions keep whatever name their originating skill gave them.
+2. **Diagrams always land in a companion**, regardless of size. SPEC.md kernel holds prose only. Mermaid blocks, ASCII diagrams, and image references all live in a companion (e.g. `architecture-diagrams.md`), with sibling image files referenced from there.
+
+Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs are listed as **adopted companions**, never duplicated into SPEC.md or a spec-authored companion.
+
+## Spec Law
+
+Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
+
+1. **Each capability has both `intent` and `success`.** Missing either = not a capability.
+2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions).
+3. **Constraints actually bend design decisions.** A "constraint" that rules nothing out is decoration.
+4. **Non-goals are explicit.** At least one. Absence means downstream skills fill the vacuum.
+5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify.
+6. **Capability IDs are stable and unique.** Never reused, never renumbered.
+7. **Preservation.** Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
+8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.decision-log.md`.
+
+## Self-Validate
+
+After every create or update, sweep the resulting artifact in **two passes** before presenting.
+
+**Pass 1 — Coherence.** Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become `assumptions[]`; gaps that could not be filled become `open_questions[]`.
+
+**Pass 2 — Preservation.** Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
+
+Append a one-paragraph verdict to `.decision-log.md` covering both passes. In interactive mode, review the verdict with the user. In headless mode, `.decision-log.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
+
+## Spec with no change signal
+
+When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
+
+## Output
+
+**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
+
+**Headless** — return JSON per `assets/headless-schemas.md`.
+
+Run `{workflow.on_complete}` if set.
+
+## After Spec is Output
+
+Any update to spec regarding assumptions, open questions, or other changes should be appended to that source's decision log also and offer to update the source.
+
+## Frontmatter conventions
+
+- `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same.
+- `sources:` array of paths to files that were **fully absorbed** into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in `companions:`, not here.
+- **Do not list** decision logs, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.

package/src/core-skills/bmad-spec/assets/headless-schemas.md

@@ -0,0 +1,33 @@
+# Headless JSON Response
+
+The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.decision-log.md`).
+
+## Success
+
+```json
+{
+  "status": "complete",
+  "files": [
+    "_bmad-output/specs/spec-quarter-drop/SPEC.md",
+    "_bmad-output/specs/spec-quarter-drop/glossary.md",
+    "_bmad-output/specs/spec-quarter-drop/.decision-log.md"
+  ]
+}
+```
+
+`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, decision log location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
+
+## Blocked
+
+```json
+{
+  "status": "blocked",
+  "error_code": "insufficient_intent",
+  "reason": "Input was a one-line idea with no surrounding context; too thin to distill. Suggest bmad-prd to draw the vision out first."
+}
+```
+
+Defined `error_code` values:
+
+- `insufficient_intent` — input too thin to distill into a kernel.
+- `missing_slug` — input is sparse or multi-source and no slug was provided by the caller or derivable from a source path.

package/src/core-skills/bmad-spec/assets/spec-template.md

@@ -0,0 +1,49 @@
+---
+id: SPEC-{slug}
+companions: []     # files downstream MUST read alongside SPEC.md. Paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill).
+sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never decision logs.
+---
+
+> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
+
+# {Spec Title}
+
+## Why
+
+{One paragraph naming the force behind this work. A spec can exist for any of:
+  - **a pain to solve** — a user or operator is stuck on a specific gap;
+  - **an opportunity to capture** — something newly possible we want to claim;
+  - **a vision to realize** — a thing we want to make exist because we want it to exist;
+  - **a mandate to meet** — a regulation, deprecation, deadline, or contractual obligation.
+
+Name which (or which combination) applies, who is affected, and the backdrop that makes it matter now. This is the anchor every downstream trade-off resolves against.}
+
+## Capabilities
+
+- id: CAP-1
+  intent: {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
+  success: {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
+
+## Constraints
+
+- {A non-negotiable that bends design. If it doesn't rule anything out, it doesn't belong.}
+
+## Non-goals
+
+- {Explicit out-of-scope item. At least one. Stops downstream from filling the vacuum.}
+
+## Success signal
+
+- {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.}
+
+## Assumptions
+
+<!-- Optional. Omit this section entirely if empty. Inferred calls made without direct confirmation from the input. -->
+
+- {Statement of fact the Spec proceeded under, e.g. "Assumed mobile-first since input mentioned GPS but no platform."}
+
+## Open Questions
+
+<!-- Optional. Omit this section entirely if empty. Gaps the input did not resolve that need a human decision before downstream skills consume the Spec. -->
+
+- {Question phrased so a human can answer it, e.g. "Is offline playback in scope for CAP-2?"}

package/src/core-skills/bmad-spec/customize.toml

@@ -0,0 +1,53 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-spec.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-spec.toml        (team)
+#   {project-root}/_bmad/custom/bmad-spec.user.toml   (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays: append
+
+# Steps to run before the standard activation (config load, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before the operation begins.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+# Each entry is either a literal sentence, a skill prefixed with `skill:`,
+# or a `file:`-prefixed path/glob whose contents are loaded as facts.
+# Default points to a single top-level file; override in team/user TOML
+# to widen the scope (e.g. `_bmad/**/project-context.md`) if needed.
+persistent_facts = [
+  "file:{project-root}/project-context.md",
+]
+
+# Executed when the workflow completes. Scalar or array of instructions.
+on_complete = ""
+
+# Spec template. The five-field kernel skeleton. Override the path in
+# team/user TOML to enforce a different shape (e.g. a hypothesis field
+# for research initiatives, or a mechanics field for games).
+spec_template = "assets/spec-template.md"
+
+# Canonical filename for the kernel artifact inside the spec folder.
+# Uppercase by convention to signal "the central source of truth."
+spec_filename = "SPEC.md"
+
+# Output path for spec folders. Lands directly under {output_folder}
+# so bmad-spec works in core-only installs and matches the
+# long-term BMad direction of grouping artifacts as siblings under
+# {output_folder}/<type>/ rather than nested inside planning vs
+# implementation folders.
+spec_output_path = "{output_folder}/specs"
+
+# Run-folder pattern inside spec_output_path. Resolved against the
+# input-derived slug at activation. Same slug = same folder, so a
+# second invocation updates the existing spec in place (capability
+# IDs preserved). Override to add {date} or other components if a
+# fresh dated history is preferred.
+run_folder_pattern = "spec-{slug}"

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

@@ -9,5 +9,5 @@ Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting
 Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
 Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
 Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
-Core,bmad-distillator,Distillator,DG,Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.,,[path],anytime,,,false,adjacent to source document or specified output_path,distillate markdown file(s)
+Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files

package/src/scripts/resolve_customization.py

@@ -177,6 +177,14 @@ def extract_key(data, dotted_key: str):
     return current
 
 
+def write_json_stdout(output):
+    """Write JSON as UTF-8 so Windows cp1252 stdout can carry emoji icons."""
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Resolve customization for a BMad skill using three-layer TOML merge.",
@@ -223,7 +231,7 @@ def main():
     else:
         output = merged
 
-    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+    write_json_stdout(output)
 
 
 if __name__ == "__main__":

package/src/scripts/tests/test_resolve_customization.py

@@ -0,0 +1,50 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "resolve_customization.py"
+
+
+class ResolveCustomizationStdoutTests(unittest.TestCase):
+    def test_writes_emoji_json_when_stdout_encoding_is_cp1252(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            skill_dir = Path(temp_dir) / "emoji-agent"
+            skill_dir.mkdir()
+            (skill_dir / "customize.toml").write_text(
+                '[agent]\nname = "Emoji Agent"\nicon = "🧭"\n',
+                encoding="utf-8",
+            )
+
+            env = os.environ.copy()
+            env["PYTHONIOENCODING"] = "cp1252"
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPT),
+                    "--skill",
+                    str(skill_dir),
+                    "--key",
+                    "agent",
+                ],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+                check=False,
+            )
+
+            stderr = result.stderr.decode("utf-8", errors="replace")
+            self.assertEqual(result.returncode, 0, msg=stderr)
+
+            output = result.stdout.decode("utf-8")
+            self.assertIn("🧭", output)
+            resolved = json.loads(output)
+            self.assertEqual(resolved["agent"]["icon"], "🧭")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tools/bundle-web-bundles.js

@@ -0,0 +1,117 @@
+/**
+ * Web Bundle Release Packager
+ *
+ * Zips each bundle under web-bundles/ into dist/web-bundles/{slug}.zip
+ * for attachment to a GitHub Release.
+ *
+ * Usage:
+ *   node tools/bundle-web-bundles.js
+ *
+ * After running, the script prints the exact `gh release create` command
+ * (with the correct tag from bundles.json) for you to copy.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const BUNDLES_DIR = path.join(REPO_ROOT, 'web-bundles');
+const DIST_DIR = path.join(REPO_ROOT, 'dist', 'web-bundles');
+const MANIFEST = path.join(BUNDLES_DIR, 'bundles.json');
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function fail(msg) {
+  console.error(`[ERROR] ${msg}`);
+  process.exit(1);
+}
+
+function requireZipCli() {
+  try {
+    execSync('zip -v', { stdio: 'ignore' });
+  } catch {
+    fail("'zip' CLI not found on PATH. Install zip (macOS: preinstalled; Debian/Ubuntu: apt install zip; Alpine: apk add zip) and re-run.");
+  }
+}
+
+function loadManifest() {
+  if (!fs.existsSync(MANIFEST)) {
+    fail(`bundles.json not found at ${MANIFEST}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(MANIFEST, 'utf-8'));
+  } catch (error) {
+    fail(`bundles.json is not valid JSON: ${error.message}`);
+  }
+  if (!Array.isArray(manifest.bundles) || manifest.bundles.length === 0) {
+    fail('bundles.json is missing a non-empty "bundles" array.');
+  }
+  if (typeof manifest.releaseTag !== 'string' || !manifest.releaseTag) {
+    fail('bundles.json is missing "releaseTag".');
+  }
+  return manifest;
+}
+
+function main() {
+  requireZipCli();
+  const manifest = loadManifest();
+  const releaseTag = manifest.releaseTag;
+
+  fs.mkdirSync(DIST_DIR, { recursive: true });
+
+  console.log(`Packaging ${manifest.bundles.length} bundles for release ${releaseTag}\n`);
+
+  const zipped = [];
+  const missing = [];
+  const invalid = [];
+  for (const bundle of manifest.bundles) {
+    if (!bundle.slug || !SLUG_RE.test(bundle.slug)) {
+      invalid.push(bundle.slug || '(no slug)');
+      console.error(`  [INVALID] slug must match ${SLUG_RE} — got: ${bundle.slug}`);
+      continue;
+    }
+    const src = path.join(BUNDLES_DIR, bundle.slug);
+    if (!fs.existsSync(src)) {
+      missing.push(bundle.slug);
+      console.error(`  [MISSING] ${bundle.slug} — directory not found`);
+      continue;
+    }
+
+    const out = path.join(DIST_DIR, `${bundle.slug}.zip`);
+    if (fs.existsSync(out)) fs.unlinkSync(out);
+
+    try {
+      execFileSync('zip', ['-r', '-X', '-q', out, bundle.slug, '-x', '*.DS_Store'], {
+        cwd: BUNDLES_DIR,
+        stdio: 'inherit',
+      });
+    } catch (error) {
+      fail(`zip failed for ${bundle.slug}: ${error.message}`);
+    }
+
+    const size = (fs.statSync(out).size / 1024).toFixed(1);
+    console.log(`  [OK] ${bundle.slug}.zip (${size} KB)`);
+    zipped.push(bundle.slug);
+  }
+
+  if (invalid.length > 0) {
+    fail(`Refusing to publish: ${invalid.length} bundle(s) have invalid slugs: ${invalid.join(', ')}`);
+  }
+  if (missing.length > 0) {
+    fail(`Refusing to publish an incomplete release: missing directories for ${missing.join(', ')}`);
+  }
+  if (zipped.length === 0) {
+    fail('No bundles were packaged. Check bundles.json against web-bundles/ subdirectories.');
+  }
+
+  console.log(`\nWrote ${zipped.length} bundles to ${path.relative(REPO_ROOT, DIST_DIR)}/`);
+  console.log('\nNext step — create or update the GitHub Release:\n');
+  console.log(`  gh release create ${releaseTag} dist/web-bundles/*.zip \\`);
+  console.log(`    --title "${releaseTag}" \\`);
+  console.log(`    --notes "BMad web bundles for Gemini Gems and ChatGPT Custom GPTs. See https://bmadcode.com/web-bundles/"\n`);
+  console.log('Or, to refresh an existing release:\n');
+  console.log(`  gh release upload ${releaseTag} dist/web-bundles/*.zip --clobber\n`);
+}
+
+main();

package/tools/installer/modules/custom-module-manager.js

@@ -19,6 +19,10 @@ function quoteCustomRef(ref) {
 class CustomModuleManager {
   /** @type {Map<string, Object>} Shared across all instances: module code -> ResolvedModule */
   static _resolutionCache = new Map();
+  /** @type {Set<string>} Repo roots refreshed in the current process (dedupe quick-update fetches). */
+  static _refreshedRepoPaths = new Set();
+  /** @type {Map<string, Promise<void>>} In-flight refresh operations keyed by repo path. */
+  static _refreshInFlight = new Map();
 
   // ─── Source Parsing ───────────────────────────────────────────────────────
 
@@ -111,7 +115,7 @@ class CustomModuleManager {
     }
 
     // SSH URL: git@host:owner/repo.git
-    const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    const sshMatch = trimmed.match(/^git@([^:]+):(.+?)\/([^/.]+?)(?:\.git)?$/);
     if (sshMatch) {
       const [, host, owner, repo] = sshMatch;
       return {
@@ -424,15 +428,39 @@ class CustomModuleManager {
             stdio: ['ignore', 'pipe', 'pipe'],
           });
         } else {
-          execSync('git reset --hard origin/HEAD', {
+          // Resolve the default branch (origin/HEAD) and fetch it explicitly.
+          // With shallow clones, `origin/HEAD` is stale and `git reset --hard
+          // origin/HEAD` never picks up new commits on the default branch.
+          let defaultBranch = 'main';
+          try {
+            defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD --short', {
+              cwd: repoCacheDir,
+              stdio: 'pipe',
+            })
+              .toString()
+              .trim()
+              .replace('origin/', '');
+          } catch {
+            // Fallback if origin/HEAD is not set
+          }
+          execSync(`git fetch --depth 1 origin ${quoteCustomRef(defaultBranch)}`, {
+            cwd: repoCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync(`git reset --hard origin/${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
           });
         }
         fetchSpinner.stop(`Updated ${displayName}`);
       } catch {
-        fetchSpinner.error(`Update failed, re-downloading ${displayName}`);
-        await fs.remove(repoCacheDir);
+        // Fetch failed against an existing cache — most often the remote is
+        // unreachable (network down, repo deleted/moved, auth revoked).
+        // Preserve the previous clone so re-deploy still works from cached
+        // content; surface a warning so the user knows the cache is stale.
+        fetchSpinner.error(`Could not refresh ${displayName} — keeping cached copy`);
+        await prompts.log.warn(`Custom module ${displayName} was not refreshed (remote unreachable). Using cached copy.`);
       }
     }
 
@@ -466,6 +494,32 @@ class CustomModuleManager {
     } catch {
       // swallow — a non-git repo (local path) wouldn't reach here anyway
     }
+    // Best-effort: capture the remote default branch name so channel marker
+    // metadata for "next" reflects the actual tracked ref (not always "main").
+    let defaultRef = 'main';
+    if (!effectiveVersion) {
+      try {
+        const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+          cwd: repoCacheDir,
+          stdio: 'pipe',
+        })
+          .toString()
+          .trim();
+        if (symbolic.startsWith('origin/')) {
+          defaultRef = symbolic.slice('origin/'.length) || defaultRef;
+        }
+      } catch {
+        // Fallback to previous marker value when symbolic ref is unavailable.
+        try {
+          const existingMarker = await fs.readJson(path.join(repoCacheDir, '.bmad-channel.json'));
+          if (existingMarker?.channel === 'next' && typeof existingMarker.version === 'string' && existingMarker.version.trim()) {
+            defaultRef = existingMarker.version.trim();
+          }
+        } catch {
+          // Keep default fallback.
+        }
+      }
+    }
 
     // Write source metadata for later URL reconstruction
     const metadataPath = path.join(repoCacheDir, '.bmad-source.json');
@@ -478,6 +532,15 @@ class CustomModuleManager {
       sha: resolvedSha,
       clonedAt: new Date().toISOString(),
     });
+    // Keep a channel marker in custom cache too so update paths that rely on
+    // channel metadata (same as official-module cache) can treat this clone as
+    // refreshable. URL + no explicit ref => next, explicit ref => pinned.
+    await fs.writeJson(path.join(repoCacheDir, '.bmad-channel.json'), {
+      channel: effectiveVersion ? 'pinned' : 'next',
+      version: effectiveVersion || defaultRef,
+      sha: resolvedSha,
+      writtenAt: new Date().toISOString(),
+    });
 
     // Install dependencies if package.json exists (skip during browsing/analysis)
     const packageJsonPath = path.join(repoCacheDir, 'package.json');
@@ -642,6 +705,13 @@ class CustomModuleManager {
       const repoRoots = await this._findCacheRepoRoots(cacheDir);
 
       for (const { repoPath, metadata } of repoRoots) {
+        // Quick-update path: refresh URL-backed cached repos before reading
+        // files from them so re-deploy uses latest commits for `next` and
+        // the pinned ref for `pinned`.
+        if (options.bmadDir && metadata?.rawInput) {
+          await this._refreshRepoCacheOnce(repoPath, metadata);
+        }
+
         // Check marketplace.json for matching module code
         const marketplacePath = path.join(repoPath, '.claude-plugin', 'marketplace.json');
         if (!(await fs.pathExists(marketplacePath))) continue;
@@ -692,6 +762,45 @@ class CustomModuleManager {
     return this._findLocalSourceFromManifest(moduleCode, options);
   }
 
+  /**
+   * Refresh one cached repo at most once per process with in-flight dedupe.
+   * Prevents concurrent quick-update callers from racing the same cache path.
+   * @param {string} repoPath - Absolute cache repo path
+   * @param {Object} metadata - Parsed .bmad-source.json metadata
+   */
+  async _refreshRepoCacheOnce(repoPath, metadata) {
+    if (CustomModuleManager._refreshedRepoPaths.has(repoPath)) return;
+
+    const existing = CustomModuleManager._refreshInFlight.get(repoPath);
+    if (existing) {
+      await existing;
+      return;
+    }
+
+    const refreshPromise = (async () => {
+      try {
+        await this.cloneRepo(metadata.rawInput, {
+          silent: true,
+          pinOverride: metadata.version || undefined,
+        });
+        CustomModuleManager._refreshedRepoPaths.add(repoPath);
+      } catch (error_) {
+        // cloneRepo only throws here for unrecoverable cases (no cache present
+        // and a fresh clone failed, or an unexpected internal error). The
+        // common "remote unreachable but cache exists" case is handled inside
+        // cloneRepo, which preserves the clone and returns normally. Reaching
+        // this catch means we have no usable cache — surface a warning so the
+        // failure isn't silent.
+        await prompts.log.warn(`Refresh of cached custom module at ${path.basename(repoPath)} failed: ${error_?.message || error_}`);
+      } finally {
+        CustomModuleManager._refreshInFlight.delete(repoPath);
+      }
+    })();
+
+    CustomModuleManager._refreshInFlight.set(repoPath, refreshPromise);
+    await refreshPromise;
+  }
+
   /**
    * Check the installation manifest for a localPath entry for this module.
    * Used as fallback when the module was installed from a local source (no cache entry).