@wbern/claude-instructions 2.1.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

@@ -405,7 +405,7 @@ import path2 from "path";
 init_esm_shims();
 import fs from "fs";
 function getMarkdownFiles(dir) {
-  return fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith("_"));
 }
 function getErrorMessage(err) {
   return err instanceof Error ? err.message : String(err);
@@ -522,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() {
@@ -648,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;
@@ -701,7 +720,7 @@ 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 allFiles = await getSourceFiles(options?.includeContribCommands);
   const files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
   const existingFiles = [];
   const prefix = options?.commandPrefix || "";
@@ -713,7 +732,8 @@ 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)) {
@@ -886,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 || "";
@@ -907,8 +925,9 @@ async function generateToDirectory(outputPath, scope, options) {
     const cleanedContent = applyMarkdownFixes(
       stripInternalMetadata(expandedContent)
     );
+    const outputFileName = stripContribPrefix(file);
     await fs4.writeFile(
-      path4.join(destinationPath, prefix + file),
+      path4.join(destinationPath, prefix + outputFileName),
       cleanedContent
     );
   }
@@ -922,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(
@@ -950,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;
@@ -1122,7 +1143,8 @@ async function main(args) {
     if (args.updateExisting) {
       cachedExistingFiles = await checkExistingFiles(void 0, scope, {
         commandPrefix: commandPrefix || "",
-        flags: selectedFlags
+        flags: selectedFlags,
+        includeContribCommands: args.includeContribCommands
       });
       selectedCommands = cachedExistingFiles.map((f) => f.filename);
       if (selectedCommands.length === 0) {
@@ -1175,7 +1197,8 @@ async function main(args) {
         scope,
         {
           commandPrefix: commandPrefix || "",
-          flags: selectedFlags
+          flags: selectedFlags,
+          includeContribCommands: args.includeContribCommands
         }
       );
       const existingFilenames = new Set(
@@ -1223,7 +1246,8 @@ 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);
@@ -1303,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.1.0",
+  "version": "2.2.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -29,7 +29,7 @@
   "scripts": {
     "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: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",

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/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