bmad-method 6.10.1-next.9 → 6.11.0

package/tools/installer/prompts.js

@@ -578,10 +578,6 @@ async function autocomplete(options) {
   return result;
 }
 
-function hasPathSeparator(value) {
-  return value.endsWith('/') || value.endsWith('\\');
-}
-
 function expandHome(input) {
   if (!input) return input;
   if (input === '~') return os.homedir();
@@ -591,91 +587,54 @@ function expandHome(input) {
   return input;
 }
 
-function toDirectoryOption(value, label = value, synthetic = false) {
-  return { value, label, synthetic };
-}
-
-function isExistingDirectory(value) {
-  try {
-    return fs.existsSync(value) && fs.statSync(value).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function listDirectoryOptions(input, options) {
+/**
+ * Resolve raw prompt input to an absolute directory path.
+ * Mirrors UI.expandUserPath so what the prompt returns matches what the
+ * installer later resolves.
+ */
+function resolveDirectoryInput(input, options = {}) {
   const cwd = options.cwd || process.cwd();
-  const rawInput = input.trim();
-  const expandedInput = expandHome(rawInput);
-  const trailingSep = hasPathSeparator(rawInput) || hasPathSeparator(expandedInput);
-  const resolvedInput = expandedInput ? path.resolve(cwd, expandedInput) : cwd;
-  const browseDir = expandedInput && !trailingSep && !isExistingDirectory(resolvedInput) ? path.dirname(resolvedInput) : resolvedInput;
-  const prefix = expandedInput && browseDir !== resolvedInput ? path.basename(resolvedInput).toLowerCase() : '';
-  const results = [];
-
-  if (!trailingSep && isExistingDirectory(resolvedInput)) {
-    results.push(toDirectoryOption(resolvedInput, `. (use this directory)`));
-  }
-
-  if (isExistingDirectory(browseDir)) {
-    try {
-      for (const entry of fs.readdirSync(browseDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        if (prefix && !entry.name.toLowerCase().startsWith(prefix)) continue;
-        const fullPath = path.join(browseDir, entry.name);
-        if (!results.some((option) => option.value === fullPath)) {
-          results.push(toDirectoryOption(fullPath));
-        }
-      }
-    } catch {
-      // Skip unreadable directories; validation still reports path issues.
-    }
-  }
-
-  const validation = options.validate?.(rawInput);
-  const hasMatchingOption = results.some((option) => option.value === resolvedInput);
-  if (expandedInput && !validation && !hasMatchingOption) {
-    results.unshift(toDirectoryOption(resolvedInput, `Create/use: ${resolvedInput}`, true));
-  }
-
-  return results;
+  const rawInput = typeof input === 'string' ? input.trim() : '';
+  // An empty line means "use the default", which is resolved the same way as
+  // typed text so a `~/…` or relative default still returns an absolute path.
+  const effective = rawInput || (options.default || '').trim();
+  if (!effective) return cwd;
+  return path.resolve(cwd, expandHome(effective));
 }
 
 /**
- * Directory prompt with autocomplete candidates and create-directory support.
- * Uses @clack/core directly so typed paths that do not exist yet can still be
- * submitted when validation allows creating them.
+ * Directory prompt.
+ *
+ * A plain text entry: what is on the input line is what gets submitted,
+ * resolved to an absolute path.
+ *
+ * The line is pre-filled with the default (the current working directory,
+ * which is where installs usually run from) as real editable text rather than
+ * a placeholder, so it can be edited down or extended instead of retyped.
+ * Clearing it and pressing Enter still accepts the default.
+ *
  * @param {Object} options - Prompt options
  * @param {string} options.message - Prompt message
- * @param {string} [options.default] - Default directory
- * @param {string} [options.placeholder] - Placeholder text
+ * @param {string} [options.default] - Default directory, pre-filled on the input line
+ * @param {string} [options.placeholder] - Placeholder shown only if the line is cleared
  * @param {Function} [options.validate] - Sync validation function
- * @returns {Promise<string>} Selected or typed directory path
+ * @param {Object} [options.input] - Input stream (defaults to process.stdin; tests inject)
+ * @param {Object} [options.output] - Output stream (defaults to process.stdout; tests inject)
+ * @returns {Promise<string>} Resolved absolute directory path
  */
 async function directory(options) {
   const core = await getClackCore();
   const color = await getPicocolors();
-  const tabCompletion = {
-    prefix: '',
-    index: -1,
-    options: [],
-    lastValue: '',
-  };
 
-  let prompt;
-  prompt = new core.AutocompletePrompt({
+  const prompt = new core.TextPrompt({
+    ...(options.input ? { input: options.input } : {}),
+    ...(options.output ? { output: options.output } : {}),
     initialValue: options.default,
-    options: () => listDirectoryOptions(prompt?.userInput || '', options),
-    filter: () => true,
-    validate: (value) => options.validate?.(value ?? prompt.userInput),
+    defaultValue: options.default,
+    validate: options.validate,
     render() {
-      const title = `${color.gray('◆')}  ${options.message}`;
       const bar = color.gray('│');
-      const barEnd = color.gray('└');
       const userInput = this.userInput;
-      const placeholder = options.placeholder || options.default;
-      const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
-      const errorLine = this.state === 'error' ? [`${color.yellow('│')}  ${color.yellow(this.error)}`] : [];
 
       switch (this.state) {
         case 'submit': {
@@ -685,42 +644,20 @@ async function directory(options) {
           return `${color.gray('◇')}  ${options.message}\n${bar}  ${color.strikethrough(color.dim(userInput || ''))}`;
         }
         default: {
-          return [title, `${bar}  ${inputDisplay}`, ...errorLine, barEnd].join('\n');
+          const placeholder = options.placeholder || options.default;
+          const inputDisplay = userInput ? this.userInputWithCursor : `${color.inverse(color.hidden('_'))}${color.dim(placeholder || '')}`;
+          const lines = [`${color.gray('◆')}  ${options.message}`, `${bar}  ${inputDisplay}`];
+          if (this.state === 'error') lines.push(`${color.yellow('│')}  ${color.yellow(this.error)}`);
+          lines.push(color.gray('└'));
+          return lines.join('\n');
         }
       }
     },
   });
 
-  const hasSetUserInput = typeof prompt._setUserInput === 'function';
-  const hasClearUserInput = typeof prompt._clearUserInput === 'function';
-
-  prompt.on('key', (_, key) => {
-    if (key?.name !== 'tab') return;
-    if (!hasSetUserInput) return; // @clack/core API surface changed — skip Tab silently.
-    const currentInput = prompt.userInput;
-    const isContinuingCycle = tabCompletion.lastValue && currentInput === tabCompletion.lastValue;
-    const completionOptions = isContinuingCycle ? tabCompletion.options : prompt.filteredOptions.filter((option) => !option.synthetic);
-    if (completionOptions.length === 0) return;
-
-    if (isContinuingCycle) {
-      tabCompletion.index = (tabCompletion.index + 1) % completionOptions.length;
-    } else {
-      tabCompletion.prefix = currentInput;
-      tabCompletion.options = completionOptions;
-      tabCompletion.index = 0;
-    }
-
-    const focusedOption = completionOptions[tabCompletion.index];
-    if (!focusedOption) return;
-    const completedValue = focusedOption.value;
-    tabCompletion.lastValue = completedValue;
-    if (hasClearUserInput) prompt._clearUserInput();
-    prompt._setUserInput(completedValue, true);
-  });
-
   const result = await prompt.prompt();
   await handleCancel(result);
-  return result;
+  return resolveDirectoryInput(result, options);
 }
 
 /**
@@ -843,6 +780,8 @@ module.exports = {
   autocompleteMultiselect,
   autocomplete,
   directory,
+  // Exported for tests
+  resolveDirectoryInput,
   confirm,
   text,
   password,

package/tools/installer/ui.js

@@ -110,6 +110,44 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
+  /**
+   * Warn once for each selected module the registry marks deprecated.
+   *
+   * A deprecated module is never dropped from the selection — an existing
+   * install keeps working and keeps being updated on request. The warning is
+   * the only behavior change, and it is what tells CLI users (`--modules`,
+   * `--yes`) what the interactive picker shows as an option hint.
+   *
+   * @param {Array<string>} selectedModules - Module codes about to be installed
+   * @returns {Promise<Array<string>>} The deprecated codes that were warned about
+   */
+  async _warnDeprecatedModules(selectedModules = []) {
+    const externalManager = new ExternalModuleManager();
+    let registryModules;
+    try {
+      registryModules = await externalManager.listAvailable();
+    } catch {
+      return []; // Registry unreadable — never block an install over a notice.
+    }
+
+    const deprecatedByCode = new Map();
+    for (const mod of registryModules) {
+      if (!mod.deprecated) continue;
+      deprecatedByCode.set(mod.code, mod);
+      for (const alias of mod.aliases) deprecatedByCode.set(alias, mod);
+    }
+
+    const warned = [];
+    for (const code of selectedModules) {
+      const mod = deprecatedByCode.get(code);
+      if (!mod || warned.includes(mod.code)) continue;
+      warned.push(mod.code);
+      const detail = mod.deprecationMessage || 'It is no longer receiving updates.';
+      await prompts.log.warn(`${mod.name} (${mod.code}) is deprecated. ${detail}`);
+    }
+    return warned;
+  }
+
   async _retainUnavailableInstalledModules(selectedModules, installedModuleIds, bmadDir, options = {}) {
     const { OfficialModules } = require('./modules/official-modules');
     const officialCodes = new Set(['core']);
@@ -166,13 +204,15 @@ class UI {
     const messageLoader = new MessageLoader();
     await messageLoader.displayStartMessage();
 
-    // Probe for `uv` before any other prompts: it's becoming the de facto
-    // runner for the Python scripts BMAD workflows shell out to
-    // (`uv run <script>`), and uv provisions the interpreter itself, so it's
-    // the single thing worth checking for. The migration is still in progress
-    // (some skills still call `python3` directly), so this is informational —
-    // warn-don't-block, no ack prompt — and just points the user at setup
-    // (ideally "ask your agent to set up uv"). The installer runs in the
+    // Probe for `uv` before any other prompts: it's the runner for the Python
+    // scripts BMAD skills shell out to (`uv run <script>`), and uv provisions
+    // the interpreter itself, so it's the single thing worth checking for.
+    // As of v6.11.0 `bmad-build` and `bmad-build-auto` HALT without it.
+    //
+    // Still warn-don't-block, with no ack prompt: core-only, docs-only, and
+    // CI installs never touch a rendered skill, so a missing `uv` must not
+    // fail the run. `installer.js` repeats the warning in the post-install
+    // summary so it survives the scrollback. The installer runs in the
     // destination environment, so probing PATH here tests the right machine.
     const { checkUvEnvironment } = require('./core/uv-check');
     await checkUvEnvironment();
@@ -275,6 +315,9 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
+        // Quick update never shows the module picker, so this is the only
+        // place an existing install of a deprecated module hears about it.
+        await this._warnDeprecatedModules(existingInstall.moduleIds || []);
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
@@ -339,6 +382,11 @@ class UI {
           );
         }
 
+        // Surface deprecation notices for whatever ended up selected. The
+        // interactive picker only hints at them in the option list, and the
+        // --modules / --yes paths never see that list at all.
+        await this._warnDeprecatedModules(selectedModules);
+
         // 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
@@ -424,6 +472,8 @@ class UI {
       selectedModules.unshift('core');
     }
 
+    await this._warnDeprecatedModules(selectedModules);
+
     // Interactive channel gate: "Ready to install (all stable)? [Y/n]"
     // Only shown for fresh installs with no channel flags and an external module
     // selected. Skipped for prerelease launches because channelOptions.global
@@ -808,9 +858,15 @@ class UI {
 
     const configCollector = new OfficialModules({ channelOptions: options.channelOptions });
 
-    // Seed core config from CLI options if provided
-    if (options.userName || options.communicationLanguage || options.documentOutputLanguage || options.outputFolder) {
-      const coreConfig = {};
+    const hasCoreCliOptions =
+      options.userName || options.communicationLanguage || options.documentOutputLanguage || options.outputFolder || setOverrides.core;
+
+    // Seed core config from CLI options if provided. `--set core.<key>` seeds it
+    // too: core values are dependency-bearing — module artifact paths are built
+    // from output_folder here, and each module's config.yaml snapshots the core
+    // values — so the post-install patch alone lands too late.
+    if (hasCoreCliOptions) {
+      const coreConfig = { ...setOverrides.core };
       if (options.userName) {
         coreConfig.user_name = options.userName;
         await prompts.log.info(`Using user name from command-line: ${options.userName}`);
@@ -830,8 +886,24 @@ class UI {
 
       // Load existing config to merge with provided options
       await configCollector.loadExistingConfig(directory);
-      const existingConfig = configCollector.collectedConfig.core || {};
-      configCollector.collectedConfig.core = { ...existingConfig, ...coreConfig };
+      const existingConfig = configCollector.existingConfig.core || {};
+      let defaultConfig = {};
+      if (options.yes) {
+        let safeUsername;
+        try {
+          safeUsername = os.userInfo().username;
+        } catch {
+          safeUsername = process.env.USER || process.env.USERNAME || 'User';
+        }
+        defaultConfig = {
+          user_name: safeUsername.charAt(0).toUpperCase() + safeUsername.slice(1),
+          project_name: path.basename(directory),
+          communication_language: 'English',
+          document_output_language: 'English',
+          output_folder: '_bmad-output',
+        };
+      }
+      configCollector.collectedConfig.core = { ...defaultConfig, ...existingConfig, ...coreConfig };
 
       // If not all options are provided, collect the missing ones interactively (unless --yes flag)
       if (
@@ -843,7 +915,7 @@ class UI {
     } else if (options.yes) {
       // Use all defaults when --yes flag is set
       await configCollector.loadExistingConfig(directory);
-      const existingConfig = configCollector.collectedConfig.core || {};
+      const existingConfig = configCollector.existingConfig.core || {};
 
       if (Object.keys(existingConfig).length === 0) {
         let safeUsername;
@@ -879,7 +951,7 @@ class UI {
    * @param {Set} installedModuleIds - Currently installed module IDs
    * @param {Map<string, string>} installedModuleVersions - Installed module versions from the local manifest
    * @param {Object|null} channelOptions - Parsed installer channel options
-   * @returns {Array} Selected module codes (excluding core)
+   * @returns {Array} Selected module codes, always including core
    */
   async selectAllModules(installedModuleIds = new Set(), installedModuleVersions = new Map(), channelOptions = null) {
     // Phase 1: Official modules
@@ -920,7 +992,6 @@ class UI {
 
     const allOptions = [];
     const initialValues = [];
-    const lockedValues = ['core'];
 
     const buildModuleEntry = async (code, name, description, isDefault, repoUrl = null, registryDefault = null) => {
       const isInstalled = installedModuleIds.has(code);
@@ -937,11 +1008,15 @@ class UI {
       };
     };
 
-    // Add built-in modules first (always available regardless of network)
+    // Add built-in modules first (always available regardless of network).
+    // core is not offered as a row: it is a dependency of every module, always
+    // installed, and was only ever rendered as a locked always-on checkbox.
+    // It is still added back to the result below.
     const builtInCodes = new Set();
     for (const mod of builtInModules) {
       const code = mod.id;
       builtInCodes.add(code);
+      if (code === 'core') continue;
       const entry = await buildModuleEntry(code, mod.name, mod.description, mod.defaultSelected);
       allOptions.push({ label: entry.label, value: entry.value, hint: entry.hint });
       if (entry.selected) {
@@ -996,22 +1071,24 @@ class UI {
       message: 'Select official modules to install:',
       options: allOptions,
       initialValues: initialValues.length > 0 ? initialValues : undefined,
-      lockedValues,
-      required: true,
+      // Not required: core is installed either way, so an empty selection is a
+      // legitimate "core only" install rather than a mistake to block on.
+      required: false,
       maxItems: allOptions.length,
     });
 
-    const result = selected ? [...selected] : [];
+    const chosen = selected ? [...selected] : [];
 
-    if (result.length > 0) {
-      const moduleLines = result.map((moduleId) => {
+    if (chosen.length > 0) {
+      const moduleLines = chosen.map((moduleId) => {
         const opt = allOptions.find((o) => o.value === moduleId);
         return `  \u2022 ${opt?.label || moduleId}`;
       });
       await prompts.log.message('Selected official modules:\n' + moduleLines.join('\n'));
     }
 
-    return result;
+    // core is never shown but always installed.
+    return chosen.includes('core') ? chosen : ['core', ...chosen];
   }
 
   /**

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 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.
+This checks 13 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, TPL-01.
 
 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).
 
@@ -253,6 +253,16 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
+### TPL-01 — Template Files Must Not Contain Compile-Time Substitutions
+
+- **Severity:** HIGH
+- **Applies to:** `.md` files whose name contains `template` (case-insensitive)
+- **Rule:** Template files seed durable, version-controlled artifacts (e.g. spec files) that execute on other machines. A `{{.var}}` compile-time substitution would be baked at render time and freeze a machine-local value into every artifact produced from the template.
+- **Detection:** Regex `\{\{\.\w+\}\}` match anywhere in a file whose basename matches `/template/i`.
+- **Fix:** Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated artifact.
+
+---
+
 ### REF-01 — Variable References Must Be Defined
 
 - **Severity:** HIGH

package/tools/validate-published-implementation-model.mjs

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CANONICAL_LLMS_ENTRY = '**[Build]';
+const CANONICAL_LLMS_DESCRIPTION = 'Canonical implementation workflow for direct intent and fully planned work';
+
+const FORBIDDEN_TERMS = [
+  /\bbmad-(?:quick-dev|dev-auto)\b/gi,
+  /\bQuick[ -]?Dev\b/gi,
+  /\bDev[ -]?Auto\b/gi,
+  /\bbmad-(?:create|dev)-story\b/gi,
+  /\b(?:create-story|dev-story)\b/gi,
+  /\b(?:Create Story|Dev Story)\b/g,
+  /\b(?:createStory|devStory|create_story|dev_story)\b/g,
+  /\bquick[ -]?flow\b/gi,
+  /flux rapide|parcours parallèle/gi,
+  /paralelní cesta/gi,
+  /luồng nhanh|nhánh nhanh/gi,
+  /快速流程|并行快线/g,
+];
+
+export function validatePublishedImplementationModel(siteDir) {
+  const findings = findObsoleteImplementationTerms(siteDir);
+  if (findings.length > 0) {
+    const details = findings.map(({ file, line, match }) => `${file}:${line}: ${match}`).join('\n  ');
+    throw new Error(`Obsolete implementation terminology found in deployable documentation:\n  ${details}`);
+  }
+
+  const llmsPath = path.join(siteDir, 'llms.txt');
+  const llmsContent = fs.readFileSync(llmsPath, 'utf-8');
+  if (!llmsContent.includes(CANONICAL_LLMS_ENTRY) || !llmsContent.includes(CANONICAL_LLMS_DESCRIPTION)) {
+    throw new Error('llms.txt must describe Build as canonical for both direct intent and fully planned work');
+  }
+}
+
+export function findObsoleteImplementationTerms(siteDir) {
+  const findings = [];
+
+  for (const filePath of getPublishedTextFiles(siteDir)) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    for (const pattern of FORBIDDEN_TERMS) {
+      for (const match of content.matchAll(pattern)) {
+        findings.push({
+          file: path.relative(siteDir, filePath),
+          line: content.slice(0, match.index).split('\n').length,
+          match: match[0],
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function getPublishedTextFiles(dir) {
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...getPublishedTextFiles(fullPath));
+    } else if (/\.(?:html|txt|xml|json|svg)$/i.test(entry.name)) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}

package/tools/validate-skills.js

@@ -17,6 +17,7 @@
  * - STEP-06: step frontmatter has no name/description
  * - STEP-07: step count 2-10
  * - SEQ-02: no time estimates
+ * - TPL-01: template files must not contain compile-time {{.var}} substitutions
  *
  * Usage:
  *   node tools/validate-skills.js                    # All skills, human-readable
@@ -43,6 +44,8 @@ const positionalArgs = args.filter((a) => !a.startsWith('--'));
 const NAME_REGEX = /^bmad-[a-z0-9]+(-[a-z0-9]+)*$/;
 const STEP_FILENAME_REGEX = /^step-\d{2}[a-z]?-[a-z0-9-]+\.md$/;
 const TIME_ESTIMATE_PATTERNS = [/takes?\s+\d+\s*min/i, /~\s*\d+\s*min/i, /estimated\s+time/i, /\bETA\b/];
+const TEMPLATE_FILENAME_REGEX = /template/i;
+const COMPILE_TIME_SUB_REGEX = /\{\{\.\w+\}\}/;
 
 const SEVERITY_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
 
@@ -535,6 +538,36 @@ function validateSkill(skillDir) {
     }
   }
 
+  // --- TPL-01: template files must not contain compile-time {{.var}} substitutions ---
+  // Template files seed durable, version-controlled artifacts (spec files) that
+  // execute on other machines. Baking a {{.var}} at render time would freeze a
+  // machine-local value into every downstream artifact.
+  for (const filePath of allFiles) {
+    if (path.extname(filePath) !== '.md') continue;
+    const base = path.basename(filePath);
+    if (!TEMPLATE_FILENAME_REGEX.test(base)) continue;
+
+    const relFile = path.relative(skillDir, filePath);
+    const content = safeReadFile(filePath, findings, relFile);
+    if (content === null) continue;
+
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+      const match = line.match(COMPILE_TIME_SUB_REGEX);
+      if (match) {
+        findings.push({
+          rule: 'TPL-01',
+          title: 'Template files must not contain compile-time substitutions',
+          severity: 'HIGH',
+          file: relFile,
+          line: i + 1,
+          detail: `Template file contains compile-time substitution \`${match[0]}\` — this would be baked at render time and leak a machine-local value into every spec produced from the template.`,
+          fix: 'Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated spec.',
+        });
+      }
+    }
+  }
+
   return findings;
 }
 

package/web-bundles/prd-coach/prd-template.md

@@ -161,5 +161,5 @@ updated: {YYYY-MM-DD}
 - **Environmental and Reliability Requirements**.
 
 ### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact: chosen during the Right-skill check in Discovery)*
-- **Stories**: story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-quick-dev` is the better path; this cluster is only for "I want a doc *and* the stories."
+- **Stories**: story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-build` is the better path; this cluster is only for "I want a doc *and* the stories."
 

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

@@ -1,76 +0,0 @@
----
-name: bmad-agent-tech-writer
-description: Technical documentation specialist and knowledge curator. Use when the user asks to talk to Paige or requests the tech writer.
----
-
-# Paige — Technical Writer
-
-## Overview
-
-You are Paige, the Technical Writer. You transform complex concepts into accessible, structured documentation — writing for the reader's task, favoring diagrams when they carry more signal than prose, and adapting depth to audience. Master of CommonMark, DITA, OpenAPI, and Mermaid.
-
-## Conventions
-
-- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## On Activation
-
-### Step 1: Resolve the Agent Block
-
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
-
-**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `{skill-root}/customize.toml` — defaults
-2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Adopt Persona
-
-Adopt the Paige / Technical Writer identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
-
-Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
-
-### Step 4: Load Persistent Facts
-
-Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 5: Load Config
-
-Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
-- Use `{user_name}` for greeting
-- Use `{communication_language}` for all communications
-- Use `{document_output_language}` for output documents
-- Use `{planning_artifacts}` for output location and artifact scanning
-- Use `{project_knowledge}` for additional context scanning
-
-### Step 6: Greet the User
-
-Greet `{user_name}` warmly by name as Paige, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
-
-Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
-
-### Step 7: Execute Append Steps
-
-Execute each entry in `{agent.activation_steps_append}` in order.
-
-Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
-
-### Step 8: Dispatch or Present the Menu
-
-If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Paige, let's document this codebase"), skip the menu and dispatch that item directly after greeting.
-
-Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
-
-Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
-
-From here, Paige stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.