@wbern/claude-instructions 2.0.0 → 2.2.0

package/README.md

@@ -42,7 +42,7 @@ pnpm dlx @wbern/claude-instructions
 
 The interactive installer lets you choose:
 
-- **Variant**: With or without [Beads MCP](https://github.com/steveyegge/beads) integration
+- **Feature flags**: Enable optional integrations like [Beads MCP](https://github.com/steveyegge/beads)
 - **Scope**: User-level (global) or project-level installation
 
 After installation, restart Claude Code if it's currently running.
@@ -60,7 +60,7 @@ Then add a postinstall script to your `package.json`:
 ```json
 {
   "scripts": {
-    "postinstall": "npx @wbern/claude-instructions --variant=without-beads --scope=project --prefix="
+    "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
     "@wbern/claude-instructions": "^1.0.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") && !f.startsWith("_"));
+}
+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();
@@ -508,6 +522,13 @@ var CLI_OPTIONS = [
     type: "array",
     description: "Enable feature flags (beads, github, gitlab, etc.)",
     example: "--flags=beads,github"
+  },
+  {
+    flag: "--include-contrib-commands",
+    key: "includeContribCommands",
+    type: "boolean",
+    description: "Include underscore-prefixed contributor commands",
+    internal: true
   }
 ];
 function generateHelpText() {
@@ -528,13 +549,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 +563,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 +614,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 +624,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 +639,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 = {
@@ -628,6 +655,18 @@ var DIRECTORIES = {
 var TEMPLATE_SOURCE_FILES = ["CLAUDE.md", "AGENTS.md"];
 var REQUESTED_TOOLS_KEY = "_requested-tools";
 var ELLIPSIS = "...";
+function isSourceFile(filename, includeContribCommands) {
+  return filename.endsWith(".md") && (includeContribCommands || !filename.startsWith("_"));
+}
+function stripContribPrefix(filename) {
+  return filename.startsWith("_") ? filename.slice(1) : filename;
+}
+async function getSourceFiles(includeContribCommands) {
+  const sourcePath = path4.join(__dirname3, "..", DIRECTORIES.SOURCES);
+  return (await fs4.readdir(sourcePath)).filter(
+    (f) => isSourceFile(f, includeContribCommands)
+  );
+}
 function truncatePathFromLeft(pathStr, maxLength) {
   if (pathStr.length <= maxLength) {
     return pathStr;
@@ -645,19 +684,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,9 +718,9 @@ 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 allFiles = await getSourceFiles(options?.includeContribCommands);
   const files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
   const existingFiles = [];
   const prefix = options?.commandPrefix || "";
@@ -698,16 +732,21 @@ async function checkExistingFiles(outputPath, scope, options) {
   }
   const baseDir = path4.join(__dirname3, "..");
   for (const file of files) {
-    const destFileName = prefix + file;
+    const outputFileName = stripContribPrefix(file);
+    const destFileName = prefix + outputFileName;
     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 = 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 +799,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 +815,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 +838,7 @@ async function getRequestedToolsOptions() {
   }
   return Array.from(toolToCommands.entries()).map(([tool, commands]) => ({
     value: tool,
-    label: extractLabelFromTool(tool),
+    label: tool,
     hint: formatCommandsHint(commands)
   }));
 }
@@ -824,6 +854,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;
@@ -845,9 +906,7 @@ async function generateToDirectory(outputPath, scope, options) {
   const destinationPath = getDestinationPath(outputPath, scope);
   const sourcePath = path4.join(__dirname3, "..", DIRECTORIES.SOURCES);
   const flags = options?.flags ?? [];
-  const allFiles = (await fs4.readdir(sourcePath)).filter(
-    (f) => f.endsWith(".md")
-  );
+  const allFiles = await getSourceFiles(options?.includeContribCommands);
   let files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
   if (options?.skipFiles) {
     const prefix2 = options?.commandPrefix || "";
@@ -863,9 +922,13 @@ async function generateToDirectory(outputPath, scope, options) {
       flags,
       baseDir
     });
+    const cleanedContent = applyMarkdownFixes(
+      stripInternalMetadata(expandedContent)
+    );
+    const outputFileName = stripContribPrefix(file);
     await fs4.writeFile(
-      path4.join(destinationPath, prefix + file),
-      expandedContent
+      path4.join(destinationPath, prefix + outputFileName),
+      cleanedContent
     );
   }
   if (options?.allowedTools && options.allowedTools.length > 0) {
@@ -878,7 +941,8 @@ async function generateToDirectory(outputPath, scope, options) {
         (tool) => allowedToolsSet.has(tool)
       );
       if (toolsForCommand.length > 0) {
-        const filePath = path4.join(destinationPath, prefix + file);
+        const outputFileName = stripContribPrefix(file);
+        const filePath = path4.join(destinationPath, prefix + outputFileName);
         const content = await fs4.readFile(filePath, "utf-8");
         const allowedToolsYaml = `allowed-tools: ${toolsForCommand.join(", ")}`;
         const modifiedContent = content.replace(
@@ -906,8 +970,9 @@ ${allowedToolsYaml}
       const templates = extractTemplateBlocks(sourceContent);
       if (templates.length > 0) {
         for (const file of files) {
-          const commandName = path4.basename(file, ".md");
-          const actualFileName = options?.commandPrefix ? options.commandPrefix + file : file;
+          const outputFileName = stripContribPrefix(file);
+          const commandName = path4.basename(outputFileName, ".md");
+          const actualFileName = options?.commandPrefix ? options.commandPrefix + outputFileName : outputFileName;
           const filePath = path4.join(destinationPath, actualFileName);
           let content = await fs4.readFile(filePath, "utf-8");
           let modified = false;
@@ -919,7 +984,7 @@ ${allowedToolsYaml}
             modified = true;
           }
           if (modified) {
-            await fs4.writeFile(filePath, content);
+            await fs4.writeFile(filePath, applyMarkdownFixes(content));
           }
         }
         templateInjected = true;
@@ -943,6 +1008,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 +1136,16 @@ 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,
+        includeContribCommands: args.includeContribCommands
+      });
       selectedCommands = cachedExistingFiles.map((f) => f.filename);
       if (selectedCommands.length === 0) {
         log.warn("No existing commands found in target directory");
@@ -1107,10 +1176,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)) {
@@ -1123,7 +1197,8 @@ async function main(args) {
         scope,
         {
           commandPrefix: commandPrefix || "",
-          flags: selectedFlags
+          flags: selectedFlags,
+          includeContribCommands: args.includeContribCommands
         }
       );
       const existingFilenames = new Set(
@@ -1171,18 +1246,17 @@ async function main(args) {
     commandPrefix,
     commands: selectedCommands,
     allowedTools: selectedAllowedTools,
-    flags: selectedFlags
+    flags: selectedFlags,
+    includeContribCommands: args?.includeContribCommands
   });
   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 +1310,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"
       );
@@ -1255,7 +1327,8 @@ async function main(args) {
     commands: selectedCommands,
     skipFiles,
     allowedTools: selectedAllowedTools,
-    flags: selectedFlags
+    flags: selectedFlags,
+    includeContribCommands: args?.includeContribCommands
   });
   const fullPath = scope === "project" ? `${process.cwd()}/.claude/commands` : `${os2.homedir()}/.claude/commands`;
   outro(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "2.0.0",
+  "version": "2.2.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 --include-contrib-commands --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/README.md

@@ -43,7 +43,7 @@ pnpm dlx @wbern/claude-instructions
 
 The interactive installer lets you choose:
 
-- **Variant**: With or without [Beads MCP](https://github.com/steveyegge/beads) integration
+- **Feature flags**: Enable optional integrations like [Beads MCP](https://github.com/steveyegge/beads)
 - **Scope**: User-level (global) or project-level installation
 
 After installation, restart Claude Code if it's currently running.
@@ -61,7 +61,7 @@ Then add a postinstall script to your `package.json`:
 ```json
 {
   "scripts": {
-    "postinstall": "npx @wbern/claude-instructions --variant=without-beads --scope=project --prefix="
+    "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
     "@wbern/claude-instructions": "^1.0.0"

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/_contribute-a-command.md

@@ -0,0 +1,137 @@
+---
+description: Create a new slash command for this repository
+argument-hint: <command-name> <command-info>
+_hint: Create command
+_category: Utilities
+_order: 99
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+Create a new custom command in `src/sources/` following the patterns below. Assess the structure carefully using the below info but also researching the repo.
+
+Command to create: $ARGUMENTS
+
+## File Structure
+
+Create `src/sources/<command-name>.md` with:
+1. Frontmatter (required fields below)
+2. INCLUDE directives for shared content
+  - We always include the  `docs INCLUDE path='src/fragments/universal-guidelines.md'` fragment
+3. Command-specific content
+4. Exactly ONE `[DOLLAR]ARGUMENTS` placeholder
+
+After creating, run `pnpm build` and `pnpm vitest run -u` to update snapshots.
+
+## Frontmatter Template
+
+```yaml
+---
+description: Brief description for /help
+argument-hint: [optional-arg] or <required-arg> or (no arguments - interactive)
+_hint: Short 2-3 word hint
+_category: Test-Driven Development | Planning | Workflow | Ship / Show / Ask | Utilities | [Something else]
+_order: 1-99
+---
+```
+
+Optional: `_requested-tools` (array), `_selectedByDefault: false`
+
+## Category Patterns
+
+### Test-Driven Development (spike, red, green, refactor, cycle)
+
+```markdown
+[PHASE] PHASE! Apply the below to the info given by user input here:
+
+[DOLLAR]ARGUMENTS
+
+< !-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/fallback-arguments-beads.md' featureFlag='beads' elsePath='src/fragments/fallback-arguments.md' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+< !-- /docs -->
+```
+
+Add for refactor: `peeping-tom-warning.md`, `consistency-check.md`
+Add for red: `aaa-pattern.md`
+
+### Planning (issue, plan)
+
+```markdown
+# [Title]
+
+< !-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+< !-- /docs -->
+
+[Description and [DOLLAR] embedded in flow]
+
+< !-- docs INCLUDE path='src/fragments/discovery-phase.md' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+< !-- /docs -->
+```
+
+### Workflow (commit, pr, gap, code-review)
+
+```markdown
+< !-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+< !-- /docs -->
+
+< !-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+< !-- /docs -->
+
+[Workflow description]
+
+[DOLLAR]
+
+[Process steps]
+```
+
+commit: add `commit-process.md`, `no-plan-files.md` (with flag)
+pr/gap: add `beads-integration.md` at end
+code-review: add `_requested-tools` for git commands
+
+### Ship / Show / Ask (ship, show, ask)
+
+Use `_selectedByDefault: false`. Include prerequisites, safety checks, and reference other S/S/A commands.
+
+### Utilities (add-command, kata, tdd-review)
+
+Flexible structure. Interactive commands use `(no arguments - interactive)` hint.
+
+## Available Fragments
+
+| Fragment | Use For |
+|----------|---------|
+| `universal-guidelines.md` | Always first |
+| `beads-awareness.md` | Always second (featureFlag='beads') |
+| `tdd-fundamentals.md` | TDD commands |
+| `fallback-arguments-beads.md` | TDD fallback (featureFlag='beads', elsePath to fallback-arguments.md) |
+| `aaa-pattern.md` | Red phase |
+| `peeping-tom-warning.md` | Refactor phase |
+| `consistency-check.md` | Refactor, gap |
+| `discovery-phase.md` | Planning |
+| `beads-integration.md` | PR, planning (featureFlag='beads') |
+| `commit-process.md` | Commit |
+| `no-plan-files.md` | Commit (featureFlag='no-plan-files') |
+| `github-issue-fetch.md` | Issue fetching |
+| `test-quality-criteria.md` | Code review |
+
+## Rules
+
+1. `[DOLLAR]` - exactly once per source, never in fragments
+2. Fragments must not include other fragments
+3. Remove space after `<` in real INCLUDE directives (shown escaped above)
+4. Underscore-prefixed metadata stripped from output

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