@wbern/claude-instructions 1.21.0 → 2.1.0

package/bin/cli.js

@@ -47,17 +47,17 @@ var require_picocolors = __commonJS({
     var env = p.env || {};
     var isColorSupported = !(!!env.NO_COLOR || argv.includes("--no-color")) && (!!env.FORCE_COLOR || argv.includes("--color") || p.platform === "win32" || (p.stdout || {}).isTTY && env.TERM !== "dumb" || !!env.CI);
     var formatter = (open, close, replace = open) => (input) => {
-      let string = "" + input, index = string.indexOf(close, open.length);
-      return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
+      let string2 = "" + input, index = string2.indexOf(close, open.length);
+      return ~index ? open + replaceClose(string2, close, replace, index) + close : open + string2 + close;
     };
-    var replaceClose = (string, close, replace, index) => {
+    var replaceClose = (string2, close, replace, index) => {
       let result = "", cursor = 0;
       do {
-        result += string.substring(cursor, index) + replace;
+        result += string2.substring(cursor, index) + replace;
         cursor = index + close.length;
-        index = string.indexOf(close, cursor);
+        index = string2.indexOf(close, cursor);
       } while (~index);
-      return result + string.substring(cursor);
+      return result + string2.substring(cursor);
     };
     var createColors = (enabled = isColorSupported) => {
       let f = enabled ? formatter : () => String;
@@ -234,16 +234,16 @@ var Diff = class {
       }
     }
   }
-  addToPath(path3, added, removed, oldPosInc, options) {
-    const last = path3.lastComponent;
+  addToPath(path5, added, removed, oldPosInc, options) {
+    const last = path5.lastComponent;
     if (last && !options.oneChangePerToken && last.added === added && last.removed === removed) {
       return {
-        oldPos: path3.oldPos + oldPosInc,
+        oldPos: path5.oldPos + oldPosInc,
         lastComponent: { count: last.count + 1, added, removed, previousComponent: last.previousComponent }
       };
     } else {
       return {
-        oldPos: path3.oldPos + oldPosInc,
+        oldPos: path5.oldPos + oldPosInc,
         lastComponent: { count: 1, added, removed, previousComponent: last }
       };
     }
@@ -272,11 +272,11 @@ var Diff = class {
       return left === right || !!options.ignoreCase && left.toLowerCase() === right.toLowerCase();
     }
   }
-  removeEmpty(array) {
+  removeEmpty(array2) {
     const ret = [];
-    for (let i = 0; i < array.length; i++) {
-      if (array[i]) {
-        ret.push(array[i]);
+    for (let i = 0; i < array2.length; i++) {
+      if (array2[i]) {
+        ret.push(array2[i]);
       }
     }
     return ret;
@@ -387,19 +387,255 @@ function tokenize(value, options) {
 
 // scripts/cli.ts
 var import_picocolors = __toESM(require_picocolors(), 1);
+import * as v2 from "valibot";
 
 // scripts/cli-generator.ts
 init_esm_shims();
-import fs from "fs-extra";
+import fs4 from "fs-extra";
+import path4 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import os from "os";
+
+// scripts/fragment-expander.ts
+init_esm_shims();
+import fs2 from "fs-extra";
 import path2 from "path";
+
+// scripts/utils.ts
+init_esm_shims();
+import fs from "fs";
+function getMarkdownFiles(dir) {
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+}
+function getErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// scripts/fragment-expander.ts
+var TRANSFORM_BLOCK_REGEX = /<!--\s*docs\s+(\w+)([^>]*)-->([\s\S]*?)<!--\s*\/docs\s*-->/g;
+function parseOptions(attrString) {
+  const options = {};
+  const attrRegex = /(\w+)=['"]([^'"]*)['"]/g;
+  let match;
+  while ((match = attrRegex.exec(attrString)) !== null) {
+    options[match[1]] = match[2];
+  }
+  return options;
+}
+function expandContent(content, options) {
+  const { baseDir, flags } = options;
+  return content.replace(
+    TRANSFORM_BLOCK_REGEX,
+    (_match, transformName, attrString) => {
+      if (transformName !== "INCLUDE") {
+        throw new Error(`Unknown transform type: ${transformName}`);
+      }
+      const attrs = parseOptions(attrString);
+      const { path: includePath, featureFlag, elsePath } = attrs;
+      if (featureFlag && !flags.includes(featureFlag)) {
+        if (elsePath) {
+          const fullElsePath = path2.join(baseDir, elsePath);
+          try {
+            return fs2.readFileSync(fullElsePath, "utf8");
+          } catch (err) {
+            throw new Error(
+              `Failed to read elsePath '${elsePath}': ${getErrorMessage(err)}`
+            );
+          }
+        }
+        return "";
+      }
+      if (!includePath) {
+        throw new Error("INCLUDE directive missing required 'path' attribute");
+      }
+      const fullPath = path2.join(baseDir, includePath);
+      try {
+        return fs2.readFileSync(fullPath, "utf8");
+      } catch (err) {
+        throw new Error(
+          `Failed to read '${includePath}': ${getErrorMessage(err)}`
+        );
+      }
+    }
+  );
+}
+
+// scripts/generate-readme.ts
+init_esm_shims();
+import fs3 from "fs";
+import path3 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import os from "os";
+import * as v from "valibot";
+
+// scripts/cli-options.ts
+init_esm_shims();
+var CLI_OPTIONS = [
+  {
+    flag: "--scope",
+    key: "scope",
+    type: "string",
+    description: "Installation scope (project, user)",
+    example: "--scope=project",
+    requiredForNonInteractive: true
+  },
+  {
+    flag: "--prefix",
+    key: "prefix",
+    type: "string",
+    description: "Add prefix to command names",
+    example: "--prefix=my-"
+  },
+  {
+    flag: "--commands",
+    key: "commands",
+    type: "array",
+    description: "Install only specific commands",
+    example: "--commands=commit,red,green"
+  },
+  {
+    flag: "--skip-template-injection",
+    key: "skipTemplateInjection",
+    type: "boolean",
+    description: "Skip injecting project CLAUDE.md customizations"
+  },
+  {
+    flag: "--update-existing",
+    key: "updateExisting",
+    type: "boolean",
+    description: "Only update already-installed commands"
+  },
+  {
+    flag: "--overwrite",
+    key: "overwrite",
+    type: "boolean",
+    description: "Overwrite conflicting files without prompting"
+  },
+  {
+    flag: "--skip-on-conflict",
+    key: "skipOnConflict",
+    type: "boolean",
+    description: "Skip conflicting files without prompting"
+  },
+  {
+    flag: "--flags",
+    key: "flags",
+    type: "array",
+    description: "Enable feature flags (beads, github, gitlab, etc.)",
+    example: "--flags=beads,github"
+  }
+];
+function generateHelpText() {
+  const lines = [
+    "Usage: npx @wbern/claude-instructions [options]",
+    "",
+    "Options:"
+  ];
+  for (const opt of CLI_OPTIONS) {
+    const suffix = opt.type === "string" ? "=<value>" : opt.type === "array" ? "=<list>" : "";
+    const padding = 28 - (opt.flag.length + suffix.length);
+    lines.push(
+      `  ${opt.flag}${suffix}${" ".repeat(Math.max(1, padding))}${opt.description}`
+    );
+  }
+  lines.push("  --help, -h                  Show this help message");
+  lines.push("  --version, -v               Show version number");
+  return lines.join("\n");
+}
+
+// scripts/generate-readme.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = path2.dirname(__filename2);
-var VARIANTS = {
-  WITH_BEADS: "with-beads",
-  WITHOUT_BEADS: "without-beads"
+var __dirname2 = path3.dirname(__filename2);
+var PROJECT_ROOT = path3.resolve(__dirname2, "..");
+var SOURCES_DIR = "src/sources";
+var FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---/;
+var CATEGORIES = {
+  PLANNING: "Planning",
+  TDD: "Test-Driven Development",
+  WORKFLOW: "Workflow",
+  SHIP_SHOW_ASK: "Ship / Show / Ask",
+  WORKTREE: "Worktree Management",
+  UTILITIES: "Utilities"
 };
+var CategoryValues = Object.values(CATEGORIES);
+var CategorySchema = v.picklist(CategoryValues);
+var RequiredFrontmatterSchema = v.object({
+  description: v.pipe(v.string(), v.minLength(1)),
+  _order: v.number()
+});
+var IncludeOptionsSchema = v.object({
+  path: v.string()
+});
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) return {};
+  const frontmatter = {};
+  const lines = match[1].split("\n");
+  let currentKey = null;
+  let currentArray = null;
+  for (const line of lines) {
+    if (line.match(/^\s+-\s+/) && currentKey && currentArray) {
+      const value2 = line.replace(/^\s+-\s+/, "").trim();
+      currentArray.push(value2);
+      continue;
+    }
+    if (currentKey && currentArray) {
+      frontmatter[currentKey] = currentArray;
+      currentKey = null;
+      currentArray = null;
+    }
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    let value = line.slice(colonIndex + 1).trim();
+    if (value === "") {
+      currentKey = key;
+      currentArray = [];
+      continue;
+    }
+    if (key === "_order" && !isNaN(Number(value))) {
+      value = parseInt(value, 10);
+    }
+    if (key === "_selectedByDefault") {
+      frontmatter[key] = value === "true";
+      continue;
+    }
+    frontmatter[key] = value;
+  }
+  if (currentKey && currentArray) {
+    frontmatter[currentKey] = currentArray;
+  }
+  return frontmatter;
+}
+function getCategory(frontmatter) {
+  const category = frontmatter._category || CATEGORIES.UTILITIES;
+  return v.parse(CategorySchema, category);
+}
+function generateCommandsMetadata() {
+  const sourcesDir = path3.join(PROJECT_ROOT, SOURCES_DIR);
+  const files = getMarkdownFiles(sourcesDir);
+  const metadata = {};
+  for (const file of files) {
+    const content = fs3.readFileSync(path3.join(sourcesDir, file), "utf8");
+    const frontmatter = parseFrontmatter(content);
+    const validated = v.parse(RequiredFrontmatterSchema, frontmatter);
+    const requestedTools = frontmatter[REQUESTED_TOOLS_KEY];
+    metadata[file] = {
+      description: validated.description,
+      hint: frontmatter._hint,
+      category: getCategory(frontmatter),
+      order: validated._order,
+      ...frontmatter._selectedByDefault === false ? { selectedByDefault: false } : {},
+      ...requestedTools ? { [REQUESTED_TOOLS_KEY]: requestedTools } : {}
+    };
+  }
+  return metadata;
+}
+
+// scripts/cli-generator.ts
+import { lint } from "markdownlint/sync";
+import { applyFixes } from "markdownlint";
+var __filename3 = fileURLToPath3(import.meta.url);
+var __dirname3 = path4.dirname(__filename3);
 var SCOPES = {
   PROJECT: "project",
   USER: "user"
@@ -407,7 +643,7 @@ var SCOPES = {
 var DIRECTORIES = {
   CLAUDE: ".claude",
   COMMANDS: "commands",
-  DOWNLOADS: "downloads"
+  SOURCES: "src/sources"
 };
 var TEMPLATE_SOURCE_FILES = ["CLAUDE.md", "AGENTS.md"];
 var REQUESTED_TOOLS_KEY = "_requested-tools";
@@ -423,25 +659,27 @@ function truncatePathFromLeft(pathStr, maxLength) {
   }
   return ELLIPSIS + truncated;
 }
-var VARIANT_OPTIONS = [
+var FLAG_OPTIONS = [
   {
-    value: VARIANTS.WITH_BEADS,
-    label: "With Beads",
-    hint: "Includes Beads task tracking"
+    value: "beads",
+    label: "Beads MCP",
+    hint: "Local issue tracking",
+    category: "Feature Flags"
   },
   {
-    value: VARIANTS.WITHOUT_BEADS,
-    label: "Without Beads",
-    hint: "Standard commands only"
+    value: "no-plan-files",
+    label: "No Plan Files",
+    hint: "Forbid Claude Code's internal plan.md",
+    category: "Feature Flags"
   }
 ];
 function getScopeOptions(terminalWidth = 80) {
-  const projectPath = path2.join(
+  const projectPath = path4.join(
     process.cwd(),
     DIRECTORIES.CLAUDE,
     DIRECTORIES.COMMANDS
   );
-  const userPath = path2.join(
+  const userPath = path4.join(
     os.homedir(),
     DIRECTORIES.CLAUDE,
     DIRECTORIES.COMMANDS
@@ -459,31 +697,36 @@ function getScopeOptions(terminalWidth = 80) {
     }
   ];
 }
-async function checkExistingFiles(outputPath, variant, scope, options) {
-  const sourcePath = path2.join(
-    __dirname2,
-    "..",
-    DIRECTORIES.DOWNLOADS,
-    variant || VARIANTS.WITH_BEADS
-  );
-  const destinationPath = outputPath || getDestinationPath(outputPath, scope);
-  const allFiles = await fs.readdir(sourcePath);
+async function checkExistingFiles(outputPath, scope, options) {
+  const sourcePath = path4.join(__dirname3, "..", DIRECTORIES.SOURCES);
+  const destinationPath = getDestinationPath(outputPath, scope);
+  const flags = options?.flags ?? [];
+  const allFiles = await fs4.readdir(sourcePath);
   const files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
   const existingFiles = [];
   const prefix = options?.commandPrefix || "";
   let metadata = null;
   let allowedToolsSet = null;
   if (options?.allowedTools && options.allowedTools.length > 0) {
-    metadata = await loadCommandsMetadata(variant || VARIANTS.WITH_BEADS);
+    metadata = await loadCommandsMetadata();
     allowedToolsSet = new Set(options.allowedTools);
   }
+  const baseDir = path4.join(__dirname3, "..");
   for (const file of files) {
     const destFileName = prefix + file;
-    const destFilePath = path2.join(destinationPath, destFileName);
-    const sourceFilePath = path2.join(sourcePath, file);
-    if (await fs.pathExists(destFilePath)) {
-      const existingContent = await fs.readFile(destFilePath, "utf-8");
-      let newContent = await fs.readFile(sourceFilePath, "utf-8");
+    const destFilePath = path4.join(destinationPath, destFileName);
+    const sourceFilePath = path4.join(sourcePath, file);
+    if (await fs4.pathExists(destFilePath)) {
+      const existingContent = await fs4.readFile(destFilePath, "utf-8");
+      const sourceContent = await fs4.readFile(sourceFilePath, "utf-8");
+      let newContent = applyMarkdownFixes(
+        stripInternalMetadata(
+          expandContent(sourceContent, {
+            flags,
+            baseDir
+          })
+        )
+      );
       if (metadata && allowedToolsSet) {
         const commandMetadata = metadata[file];
         const requestedTools = commandMetadata?.[REQUESTED_TOOLS_KEY] || [];
@@ -518,19 +761,11 @@ var CATEGORY_ORDER = [
   "Utilities",
   "Ship / Show / Ask"
 ];
-async function loadCommandsMetadata(variant) {
-  const sourcePath = path2.join(
-    __dirname2,
-    "..",
-    DIRECTORIES.DOWNLOADS,
-    variant || VARIANTS.WITH_BEADS
-  );
-  const metadataPath = path2.join(sourcePath, "commands-metadata.json");
-  const metadataContent = await fs.readFile(metadataPath, "utf-8");
-  return JSON.parse(metadataContent);
+async function loadCommandsMetadata() {
+  return generateCommandsMetadata();
 }
-async function getCommandsGroupedByCategory(variant) {
-  const metadata = await loadCommandsMetadata(variant);
+async function getCommandsGroupedByCategory() {
+  const metadata = await loadCommandsMetadata();
   const grouped = {};
   for (const [filename, data] of Object.entries(metadata)) {
     const category = data.category;
@@ -544,11 +779,6 @@ async function getCommandsGroupedByCategory(variant) {
       selectedByDefault: data.selectedByDefault !== false
     });
   }
-  for (const category of Object.keys(grouped)) {
-    if (!CATEGORY_ORDER.includes(category)) {
-      throw new Error(`Unknown category: ${category}`);
-    }
-  }
   for (const category of Object.keys(grouped)) {
     grouped[category].sort((a, b) => {
       const orderA = metadata[a.value].order;
@@ -565,10 +795,6 @@ async function getCommandsGroupedByCategory(variant) {
   }
   return sortedGrouped;
 }
-function extractLabelFromTool(tool) {
-  const match = tool.match(/^Bash\(([^:]+):/);
-  return match ? match[1] : tool;
-}
 function formatCommandsHint(commands) {
   if (commands.length <= 2) {
     return commands.map((c) => `/${c}`).join(", ");
@@ -577,8 +803,8 @@ function formatCommandsHint(commands) {
   const remaining = commands.length - 2;
   return `${first.join(", ")}, and ${remaining} ${remaining === 1 ? "other" : "others"}`;
 }
-async function getRequestedToolsOptions(variant) {
-  const metadata = await loadCommandsMetadata(variant);
+async function getRequestedToolsOptions() {
+  const metadata = await loadCommandsMetadata();
   const toolToCommands = /* @__PURE__ */ new Map();
   for (const [filename, data] of Object.entries(metadata)) {
     if (data[REQUESTED_TOOLS_KEY]) {
@@ -592,7 +818,7 @@ async function getRequestedToolsOptions(variant) {
   }
   return Array.from(toolToCommands.entries()).map(([tool, commands]) => ({
     value: tool,
-    label: extractLabelFromTool(tool),
+    label: tool,
     hint: formatCommandsHint(commands)
   }));
 }
@@ -601,13 +827,44 @@ function getDestinationPath(outputPath, scope) {
     return outputPath;
   }
   if (scope === SCOPES.PROJECT) {
-    return path2.join(process.cwd(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+    return path4.join(process.cwd(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
   }
   if (scope === SCOPES.USER) {
-    return path2.join(os.homedir(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+    return path4.join(os.homedir(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
   }
   throw new Error("Either outputPath or scope must be provided");
 }
+function stripInternalMetadata(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return content;
+  }
+  const frontmatter = frontmatterMatch[1];
+  const lines = frontmatter.split("\n");
+  const filteredLines = [];
+  let skipMultiline = false;
+  for (const line of lines) {
+    if (/^_[\w-]+:/.test(line)) {
+      skipMultiline = line.endsWith(":") || /^_[\w-]+:\s*$/.test(line);
+      continue;
+    }
+    if (skipMultiline && /^\s+/.test(line)) {
+      continue;
+    }
+    skipMultiline = false;
+    filteredLines.push(line);
+  }
+  const newFrontmatter = filteredLines.join("\n");
+  return content.replace(/^---\n[\s\S]*?\n---/, `---
+${newFrontmatter}
+---`);
+}
+function applyMarkdownFixes(content) {
+  const results = lint({
+    strings: { content }
+  });
+  return applyFixes(content, results.content);
+}
 function extractTemplateBlocks(content) {
   const blocks = [];
   const withCommandsRegex = /<claude-commands-template\s+commands="([^"]+)">([\s\S]*?)<\/claude-commands-template>/g;
@@ -625,34 +882,38 @@ function extractTemplateBlocks(content) {
   }
   return blocks;
 }
-async function generateToDirectory(outputPath, variant, scope, options) {
-  const sourcePath = path2.join(
-    __dirname2,
-    "..",
-    DIRECTORIES.DOWNLOADS,
-    variant || VARIANTS.WITH_BEADS
-  );
+async function generateToDirectory(outputPath, scope, options) {
   const destinationPath = getDestinationPath(outputPath, scope);
-  const allFiles = await fs.readdir(sourcePath);
+  const sourcePath = path4.join(__dirname3, "..", DIRECTORIES.SOURCES);
+  const flags = options?.flags ?? [];
+  const allFiles = (await fs4.readdir(sourcePath)).filter(
+    (f) => f.endsWith(".md")
+  );
   let files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
   if (options?.skipFiles) {
     const prefix2 = options?.commandPrefix || "";
     files = files.filter((f) => !options.skipFiles.includes(prefix2 + f));
   }
   const prefix = options?.commandPrefix || "";
-  if (options?.commands || options?.skipFiles || options?.commandPrefix) {
-    await fs.ensureDir(destinationPath);
-    for (const file of files) {
-      await fs.copy(
-        path2.join(sourcePath, file),
-        path2.join(destinationPath, prefix + file)
-      );
-    }
-  } else {
-    await fs.copy(sourcePath, destinationPath, {});
+  await fs4.ensureDir(destinationPath);
+  const baseDir = path4.join(__dirname3, "..");
+  for (const file of files) {
+    const sourceFilePath = path4.join(sourcePath, file);
+    const sourceContent = await fs4.readFile(sourceFilePath, "utf-8");
+    const expandedContent = expandContent(sourceContent, {
+      flags,
+      baseDir
+    });
+    const cleanedContent = applyMarkdownFixes(
+      stripInternalMetadata(expandedContent)
+    );
+    await fs4.writeFile(
+      path4.join(destinationPath, prefix + file),
+      cleanedContent
+    );
   }
   if (options?.allowedTools && options.allowedTools.length > 0) {
-    const metadata = await loadCommandsMetadata(variant || VARIANTS.WITH_BEADS);
+    const metadata = await loadCommandsMetadata();
     const allowedToolsSet = new Set(options.allowedTools);
     for (const file of files) {
       const commandMetadata = metadata[file];
@@ -661,8 +922,8 @@ async function generateToDirectory(outputPath, variant, scope, options) {
         (tool) => allowedToolsSet.has(tool)
       );
       if (toolsForCommand.length > 0) {
-        const filePath = path2.join(destinationPath, prefix + file);
-        const content = await fs.readFile(filePath, "utf-8");
+        const filePath = path4.join(destinationPath, prefix + file);
+        const content = await fs4.readFile(filePath, "utf-8");
         const allowedToolsYaml = `allowed-tools: ${toolsForCommand.join(", ")}`;
         const modifiedContent = content.replace(
           /^---\n/,
@@ -670,7 +931,7 @@ async function generateToDirectory(outputPath, variant, scope, options) {
 ${allowedToolsYaml}
 `
         );
-        await fs.writeFile(filePath, modifiedContent);
+        await fs4.writeFile(filePath, modifiedContent);
       }
     }
   }
@@ -678,21 +939,21 @@ ${allowedToolsYaml}
   if (!options?.skipTemplateInjection) {
     let templateSourcePath = null;
     for (const filename of TEMPLATE_SOURCE_FILES) {
-      const candidatePath = path2.join(process.cwd(), filename);
-      if (await fs.pathExists(candidatePath)) {
+      const candidatePath = path4.join(process.cwd(), filename);
+      if (await fs4.pathExists(candidatePath)) {
         templateSourcePath = candidatePath;
         break;
       }
     }
     if (templateSourcePath) {
-      const sourceContent = await fs.readFile(templateSourcePath, "utf-8");
+      const sourceContent = await fs4.readFile(templateSourcePath, "utf-8");
       const templates = extractTemplateBlocks(sourceContent);
       if (templates.length > 0) {
         for (const file of files) {
-          const commandName = path2.basename(file, ".md");
+          const commandName = path4.basename(file, ".md");
           const actualFileName = options?.commandPrefix ? options.commandPrefix + file : file;
-          const filePath = path2.join(destinationPath, actualFileName);
-          let content = await fs.readFile(filePath, "utf-8");
+          const filePath = path4.join(destinationPath, actualFileName);
+          let content = await fs4.readFile(filePath, "utf-8");
           let modified = false;
           for (const template of templates) {
             if (template.commands && !template.commands.includes(commandName)) {
@@ -702,7 +963,7 @@ ${allowedToolsYaml}
             modified = true;
           }
           if (modified) {
-            await fs.writeFile(filePath, content);
+            await fs4.writeFile(filePath, applyMarkdownFixes(content));
           }
         }
         templateInjected = true;
@@ -712,88 +973,12 @@ ${allowedToolsYaml}
   return {
     success: true,
     filesGenerated: files.length,
-    variant,
     templateInjectionSkipped: options?.skipTemplateInjection,
-    templateInjected
+    templateInjected,
+    flags: options?.flags
   };
 }
 
-// scripts/cli-options.ts
-init_esm_shims();
-var CLI_OPTIONS = [
-  {
-    flag: "--variant",
-    key: "variant",
-    type: "string",
-    description: "Command variant (with-beads, without-beads)",
-    example: "--variant=with-beads",
-    requiredForNonInteractive: true
-  },
-  {
-    flag: "--scope",
-    key: "scope",
-    type: "string",
-    description: "Installation scope (project, user)",
-    example: "--scope=project",
-    requiredForNonInteractive: true
-  },
-  {
-    flag: "--prefix",
-    key: "prefix",
-    type: "string",
-    description: "Add prefix to command names",
-    example: "--prefix=my-"
-  },
-  {
-    flag: "--commands",
-    key: "commands",
-    type: "array",
-    description: "Install only specific commands",
-    example: "--commands=commit,red,green"
-  },
-  {
-    flag: "--skip-template-injection",
-    key: "skipTemplateInjection",
-    type: "boolean",
-    description: "Skip injecting project CLAUDE.md customizations"
-  },
-  {
-    flag: "--update-existing",
-    key: "updateExisting",
-    type: "boolean",
-    description: "Only update already-installed commands"
-  },
-  {
-    flag: "--overwrite",
-    key: "overwrite",
-    type: "boolean",
-    description: "Overwrite conflicting files without prompting"
-  },
-  {
-    flag: "--skip-on-conflict",
-    key: "skipOnConflict",
-    type: "boolean",
-    description: "Skip conflicting files without prompting"
-  }
-];
-function generateHelpText() {
-  const lines = [
-    "Usage: npx @wbern/claude-instructions [options]",
-    "",
-    "Options:"
-  ];
-  for (const opt of CLI_OPTIONS) {
-    const suffix = opt.type === "string" ? "=<value>" : opt.type === "array" ? "=<list>" : "";
-    const padding = 28 - (opt.flag.length + suffix.length);
-    lines.push(
-      `  ${opt.flag}${suffix}${" ".repeat(Math.max(1, padding))}${opt.description}`
-    );
-  }
-  lines.push("  --help, -h                  Show this help message");
-  lines.push("  --version, -v               Show version number");
-  return lines.join("\n");
-}
-
 // scripts/tty.ts
 init_esm_shims();
 function isInteractiveTTY() {
@@ -802,6 +987,10 @@ function isInteractiveTTY() {
 
 // scripts/cli.ts
 var pc = process.env.FORCE_COLOR ? import_picocolors.default.createColors(true) : import_picocolors.default;
+var ScopeValues = Object.values(SCOPES);
+var ScopeSchema = v2.picklist(ScopeValues);
+var FlagValues = FLAG_OPTIONS.map((f) => f.value);
+var FlagsSchema = v2.array(v2.picklist(FlagValues));
 function splitChangeIntoLines(value) {
   const lines = value.split("\n");
   if (lines[lines.length - 1] === "") lines.pop();
@@ -919,24 +1108,22 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 `;
 async function main(args) {
   intro(BATMAN_LOGO);
-  let variant;
   let scope;
   let commandPrefix;
   let selectedCommands;
   let selectedAllowedTools;
+  let selectedFlags;
   let cachedExistingFiles;
-  if (args?.variant && args?.scope) {
-    variant = args.variant;
-    scope = args.scope;
+  if (args?.scope) {
+    scope = v2.parse(ScopeSchema, args.scope);
     commandPrefix = args.prefix ?? "";
     selectedCommands = args.commands;
+    selectedFlags = args.flags ? v2.parse(FlagsSchema, args.flags) : void 0;
     if (args.updateExisting) {
-      cachedExistingFiles = await checkExistingFiles(
-        void 0,
-        variant,
-        scope,
-        { commandPrefix: commandPrefix || "" }
-      );
+      cachedExistingFiles = await checkExistingFiles(void 0, scope, {
+        commandPrefix: commandPrefix || "",
+        flags: selectedFlags
+      });
       selectedCommands = cachedExistingFiles.map((f) => f.filename);
       if (selectedCommands.length === 0) {
         log.warn("No existing commands found in target directory");
@@ -951,13 +1138,6 @@ async function main(args) {
       log.warn(`Non-interactive mode requires ${requiredFlags} arguments`);
       return;
     }
-    variant = await select({
-      message: "Select variant",
-      options: [...VARIANT_OPTIONS]
-    });
-    if (isCancel(variant)) {
-      return;
-    }
     const terminalWidth = process.stdout.columns || 80;
     const uiOverhead = 25;
     scope = await select({
@@ -974,15 +1154,29 @@ async function main(args) {
     if (isCancel(commandPrefix)) {
       return;
     }
-    let groupedCommands = await getCommandsGroupedByCategory(
-      variant
-    );
+    selectedFlags = await groupMultiselect({
+      message: "Select feature flags (optional)",
+      options: {
+        "Feature Flags": FLAG_OPTIONS.map(({ value, label, hint }) => ({
+          value,
+          label,
+          hint
+        }))
+      },
+      required: false
+    });
+    if (isCancel(selectedFlags)) {
+      return;
+    }
+    let groupedCommands = await getCommandsGroupedByCategory();
     if (args?.updateExisting) {
       cachedExistingFiles = await checkExistingFiles(
         void 0,
-        variant,
         scope,
-        { commandPrefix: commandPrefix || "" }
+        {
+          commandPrefix: commandPrefix || "",
+          flags: selectedFlags
+        }
       );
       const existingFilenames = new Set(
         cachedExistingFiles.map((f) => f.filename)
@@ -1011,9 +1205,7 @@ async function main(args) {
     if (isCancel(selectedCommands)) {
       return;
     }
-    const requestedToolsOptions = await getRequestedToolsOptions(
-      variant
-    );
+    const requestedToolsOptions = await getRequestedToolsOptions();
     if (requestedToolsOptions.length > 0) {
       selectedAllowedTools = await groupMultiselect({
         message: "Select allowed tools for commands (optional)",
@@ -1027,21 +1219,20 @@ async function main(args) {
       }
     }
   }
-  const existingFiles = cachedExistingFiles ?? await checkExistingFiles(void 0, variant, scope, {
+  const existingFiles = cachedExistingFiles ?? await checkExistingFiles(void 0, scope, {
     commandPrefix,
     commands: selectedCommands,
-    allowedTools: selectedAllowedTools
+    allowedTools: selectedAllowedTools,
+    flags: selectedFlags
   });
   const skipFiles = [];
+  const conflictingFiles = existingFiles.filter((f) => !f.isIdentical);
   const shouldSkipConflicts = args?.skipOnConflict || !isInteractiveTTY();
   if (args?.overwrite) {
-    for (const file of existingFiles) {
-      if (!file.isIdentical) {
-        log.info(`Overwriting ${file.filename}`);
-      }
+    for (const file of conflictingFiles) {
+      log.info(`Overwriting ${file.filename}`);
     }
   } else if (!shouldSkipConflicts) {
-    const conflictingFiles = existingFiles.filter((f) => !f.isIdentical);
     const hasMultipleConflicts = conflictingFiles.length > 1;
     let overwriteAllSelected = false;
     let skipAllSelected = false;
@@ -1095,31 +1286,25 @@ async function main(args) {
         }
       }
     }
-  } else if (shouldSkipConflicts) {
-    for (const file of existingFiles) {
-      if (!file.isIdentical) {
-        skipFiles.push(file.filename);
-        log.warn(`Skipping ${file.filename} (conflict)`);
-      }
+  } else {
+    for (const file of conflictingFiles) {
+      skipFiles.push(file.filename);
+      log.warn(`Skipping ${file.filename} (conflict)`);
     }
-    if (skipFiles.length > 0 && !isInteractiveTTY()) {
+    if (conflictingFiles.length > 0 && !isInteractiveTTY()) {
       log.info(
         "To resolve conflicts, run interactively or use --overwrite to overwrite"
       );
     }
   }
-  const result = await generateToDirectory(
-    void 0,
-    variant,
-    scope,
-    {
-      commandPrefix,
-      skipTemplateInjection: args?.skipTemplateInjection,
-      commands: selectedCommands,
-      skipFiles,
-      allowedTools: selectedAllowedTools
-    }
-  );
+  const result = await generateToDirectory(void 0, scope, {
+    commandPrefix,
+    skipTemplateInjection: args?.skipTemplateInjection,
+    commands: selectedCommands,
+    skipFiles,
+    allowedTools: selectedAllowedTools,
+    flags: selectedFlags
+  });
   const fullPath = scope === "project" ? `${process.cwd()}/.claude/commands` : `${os2.homedir()}/.claude/commands`;
   outro(
     `Installed ${result.filesGenerated} commands to ${fullPath}