@wbern/claude-instructions 2.0.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;
@@ -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,6 +387,7 @@ 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();
@@ -397,8 +398,20 @@ import os from "os";
 
 // scripts/fragment-expander.ts
 init_esm_shims();
-import fs from "fs-extra";
+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 = {};
@@ -415,7 +428,7 @@ function expandContent(content, options) {
     TRANSFORM_BLOCK_REGEX,
     (_match, transformName, attrString) => {
       if (transformName !== "INCLUDE") {
-        return "";
+        throw new Error(`Unknown transform type: ${transformName}`);
       }
       const attrs = parseOptions(attrString);
       const { path: includePath, featureFlag, elsePath } = attrs;
@@ -423,24 +436,24 @@ function expandContent(content, options) {
         if (elsePath) {
           const fullElsePath = path2.join(baseDir, elsePath);
           try {
-            return fs.readFileSync(fullElsePath, "utf8");
+            return fs2.readFileSync(fullElsePath, "utf8");
           } catch (err) {
             throw new Error(
-              `Failed to read elsePath '${elsePath}': ${err instanceof Error ? err.message : String(err)}`
+              `Failed to read elsePath '${elsePath}': ${getErrorMessage(err)}`
             );
           }
         }
         return "";
       }
       if (!includePath) {
-        return "";
+        throw new Error("INCLUDE directive missing required 'path' attribute");
       }
       const fullPath = path2.join(baseDir, includePath);
       try {
-        return fs.readFileSync(fullPath, "utf8");
+        return fs2.readFileSync(fullPath, "utf8");
       } catch (err) {
         throw new Error(
-          `Failed to read '${includePath}': ${err instanceof Error ? err.message : String(err)}`
+          `Failed to read '${includePath}': ${getErrorMessage(err)}`
         );
       }
     }
@@ -452,6 +465,7 @@ init_esm_shims();
 import fs3 from "fs";
 import path3 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
+import * as v from "valibot";
 
 // scripts/cli-options.ts
 init_esm_shims();
@@ -528,13 +542,6 @@ function generateHelpText() {
   return lines.join("\n");
 }
 
-// scripts/utils.ts
-init_esm_shims();
-import fs2 from "fs";
-function getMarkdownFiles(dir) {
-  return fs2.readdirSync(dir).filter((f) => f.endsWith(".md"));
-}
-
 // scripts/generate-readme.ts
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = path3.dirname(__filename2);
@@ -549,6 +556,15 @@ var CATEGORIES = {
   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 {};
@@ -591,7 +607,8 @@ function parseFrontmatter(content) {
   return frontmatter;
 }
 function getCategory(frontmatter) {
-  return frontmatter._category || CATEGORIES.UTILITIES;
+  const category = frontmatter._category || CATEGORIES.UTILITIES;
+  return v.parse(CategorySchema, category);
 }
 function generateCommandsMetadata() {
   const sourcesDir = path3.join(PROJECT_ROOT, SOURCES_DIR);
@@ -600,12 +617,13 @@ function generateCommandsMetadata() {
   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: frontmatter.description || "No description",
+      description: validated.description,
       hint: frontmatter._hint,
       category: getCategory(frontmatter),
-      order: typeof frontmatter._order === "number" ? frontmatter._order : 999,
+      order: validated._order,
       ...frontmatter._selectedByDefault === false ? { selectedByDefault: false } : {},
       ...requestedTools ? { [REQUESTED_TOOLS_KEY]: requestedTools } : {}
     };
@@ -614,6 +632,8 @@ function generateCommandsMetadata() {
 }
 
 // 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 = {
@@ -645,19 +665,14 @@ var FLAG_OPTIONS = [
     label: "Beads MCP",
     hint: "Local issue tracking",
     category: "Feature Flags"
+  },
+  {
+    value: "no-plan-files",
+    label: "No Plan Files",
+    hint: "Forbid Claude Code's internal plan.md",
+    category: "Feature Flags"
   }
 ];
-function getFlagsGroupedByCategory() {
-  const grouped = {};
-  for (const flag of FLAG_OPTIONS) {
-    const { category, ...option } = flag;
-    if (!grouped[category]) {
-      grouped[category] = [];
-    }
-    grouped[category].push(option);
-  }
-  return grouped;
-}
 function getScopeOptions(terminalWidth = 80) {
   const projectPath = path4.join(
     process.cwd(),
@@ -684,7 +699,7 @@ function getScopeOptions(terminalWidth = 80) {
 }
 async function checkExistingFiles(outputPath, scope, options) {
   const sourcePath = path4.join(__dirname3, "..", DIRECTORIES.SOURCES);
-  const destinationPath = outputPath || getDestinationPath(outputPath, scope);
+  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;
@@ -704,10 +719,14 @@ async function checkExistingFiles(outputPath, scope, options) {
     if (await fs4.pathExists(destFilePath)) {
       const existingContent = await fs4.readFile(destFilePath, "utf-8");
       const sourceContent = await fs4.readFile(sourceFilePath, "utf-8");
-      let newContent = expandContent(sourceContent, {
-        flags,
-        baseDir
-      });
+      let newContent = applyMarkdownFixes(
+        stripInternalMetadata(
+          expandContent(sourceContent, {
+            flags,
+            baseDir
+          })
+        )
+      );
       if (metadata && allowedToolsSet) {
         const commandMetadata = metadata[file];
         const requestedTools = commandMetadata?.[REQUESTED_TOOLS_KEY] || [];
@@ -760,11 +779,6 @@ async function getCommandsGroupedByCategory() {
       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;
@@ -781,10 +795,6 @@ async function getCommandsGroupedByCategory() {
   }
   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(", ");
@@ -808,7 +818,7 @@ async function getRequestedToolsOptions() {
   }
   return Array.from(toolToCommands.entries()).map(([tool, commands]) => ({
     value: tool,
-    label: extractLabelFromTool(tool),
+    label: tool,
     hint: formatCommandsHint(commands)
   }));
 }
@@ -824,6 +834,37 @@ function getDestinationPath(outputPath, scope) {
   }
   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;
@@ -863,9 +904,12 @@ async function generateToDirectory(outputPath, scope, options) {
       flags,
       baseDir
     });
+    const cleanedContent = applyMarkdownFixes(
+      stripInternalMetadata(expandedContent)
+    );
     await fs4.writeFile(
       path4.join(destinationPath, prefix + file),
-      expandedContent
+      cleanedContent
     );
   }
   if (options?.allowedTools && options.allowedTools.length > 0) {
@@ -919,7 +963,7 @@ ${allowedToolsYaml}
             modified = true;
           }
           if (modified) {
-            await fs4.writeFile(filePath, content);
+            await fs4.writeFile(filePath, applyMarkdownFixes(content));
           }
         }
         templateInjected = true;
@@ -943,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();
@@ -1067,16 +1115,15 @@ async function main(args) {
   let selectedFlags;
   let cachedExistingFiles;
   if (args?.scope) {
-    scope = args.scope;
+    scope = v2.parse(ScopeSchema, args.scope);
     commandPrefix = args.prefix ?? "";
     selectedCommands = args.commands;
-    selectedFlags = args.flags;
+    selectedFlags = args.flags ? v2.parse(FlagsSchema, args.flags) : void 0;
     if (args.updateExisting) {
-      cachedExistingFiles = await checkExistingFiles(
-        void 0,
-        scope,
-        { commandPrefix: commandPrefix || "", flags: selectedFlags }
-      );
+      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");
@@ -1107,10 +1154,15 @@ async function main(args) {
     if (isCancel(commandPrefix)) {
       return;
     }
-    const flagOptions = getFlagsGroupedByCategory();
     selectedFlags = await groupMultiselect({
       message: "Select feature flags (optional)",
-      options: flagOptions,
+      options: {
+        "Feature Flags": FLAG_OPTIONS.map(({ value, label, hint }) => ({
+          value,
+          label,
+          hint
+        }))
+      },
       required: false
     });
     if (isCancel(selectedFlags)) {
@@ -1174,15 +1226,13 @@ async function main(args) {
     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;
@@ -1236,14 +1286,12 @@ 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"
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -27,7 +27,9 @@
   "author": "wbern",
   "license": "MIT",
   "scripts": {
-    "build": "tsx scripts/build.ts",
+    "build": "pnpm build:readme && pnpm build:commands && pnpm exec markdownlint --fix .claude/commands/*.md",
+    "build:readme": "tsx scripts/build.ts",
+    "build:commands": "pnpm build:cli && node bin/cli.js --scope=project --flags=beads,no-plan-files --overwrite",
     "build:cli": "tsup",
     "test:manual": "pnpm build:cli && TMPDIR=$(mktemp -d) && pnpm pack --pack-destination $TMPDIR && cd $TMPDIR && tar -xzf *.tgz && cd package && pnpm i && node bin/cli.js",
     "test:quick-manual": "pnpm build:cli && node bin/cli.js",
@@ -52,7 +54,6 @@
     "jscpd": "^4.0.5",
     "knip": "^5.70.2",
     "lint-staged": "^16.2.7",
-    "markdownlint": "^0.40.0",
     "markdownlint-cli": "^0.46.0",
     "picocolors": "^1.1.1",
     "prettier": "^3.7.2",
@@ -64,7 +65,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "fs-extra": "^11.3.2"
+    "fs-extra": "^11.3.2",
+    "markdownlint": "^0.40.0",
+    "valibot": "^1.2.0"
   },
   "release": {
     "branches": [

package/src/fragments/no-plan-files.md

@@ -0,0 +1,3 @@
+## Plan File Restriction
+
+**NEVER create, read, or update plan.md files.** Claude Code's internal planning files are disabled for this project. Use other methods to track implementation progress (e.g., comments, todo lists, or external tools).

package/src/sources/commit.md

@@ -12,6 +12,9 @@ _order: 1
 <!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
 <!-- /docs -->
 
+<!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
+<!-- /docs -->
+
 Create a git commit following project standards
 
 Include any of the following info if specified: $ARGUMENTS