@wbern/claude-instructions 1.9.0 → 1.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wbern
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,6 +21,10 @@ TDD workflow commands for Claude Code CLI.
 
 ```bash
 npx @wbern/claude-instructions
+
+// or
+
+pnpm dlx @wbern/claude-instructions
 ```
 
 The interactive installer lets you choose:
@@ -57,13 +61,14 @@ This ensures commands are regenerated whenever anyone runs `npm install`, `pnpm
 
 | Option | Description |
 |--------|-------------|
-| `--variant=with-beads` | Include Beads MCP integration |
-| `--variant=without-beads` | Standard commands only |
-| `--scope=project` | Install to `.claude/commands` in current directory |
-| `--scope=user` | Install to `~/.claude/commands` (global) |
-| `--prefix=my-` | Add prefix to command names (e.g., `my-commit.md`) |
-| `--skip-template-injection` | Don't inject CLAUDE.md template content |
+| `--variant=with-beads` | Command variant (with-beads, without-beads) |
+| `--scope=project` | Installation scope (project, user) |
+| `--prefix=my-` | Add prefix to command names |
 | `--commands=commit,red,green` | Install only specific commands |
+| `--skip-template-injection` | Skip injecting project CLAUDE.md customizations |
+| `--update-existing` | Only update already-installed commands |
+| `--overwrite` | Overwrite conflicting files without prompting |
+| `--skip-on-conflict` | Skip conflicting files without prompting |
 
 ## Customizing Commands
 
@@ -190,14 +195,6 @@ flowchart TB
 - `/issue` - Analyze GitHub issue and create TDD implementation plan
 - `/plan` - Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria
 
-### Workflow
-
-- `/commit` - Create a git commit following project standards
-- `/busycommit` - Create multiple atomic git commits, one logical change at a time
-- `/pr` - Creates a pull request using GitHub MCP
-- `/summarize` - Summarize conversation progress and next steps
-- `/gap` - Analyze conversation context for unaddressed items and gaps
-
 ### Test-Driven Development
 
 - `/spike` - Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
@@ -207,6 +204,15 @@ flowchart TB
 - `/refactor` - Execute TDD Refactor Phase - improve code structure while keeping tests green
 - `/cycle` - Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
 
+### Workflow
+
+- `/commit` - Create a git commit following project standards
+- `/busycommit` - Create multiple atomic git commits, one logical change at a time
+- `/pr` - Creates a pull request using GitHub MCP
+- `/summarize` - Summarize conversation progress and next steps
+- `/gap` - Analyze conversation context for unaddressed items and gaps
+- `/code-review` - Code review using dynamic category detection and domain-specific analysis
+
 ### Ship / Show / Ask
 
 - `/ship` - Ship code directly to main - for small, obvious changes that don't need review
@@ -215,7 +221,7 @@ flowchart TB
 
 ### Worktree Management
 
-- `/worktree-add` - Add a new git worktree from branch name or GitHub issue URL, copy settings, install deps, and open in current IDE
+- `/worktree-add` - Add a new git worktree from branch name or issue URL, copy settings, install deps, and open in current IDE
 - `/worktree-cleanup` - Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees
 
 ### Utilities

package/bin/cli.js

@@ -119,6 +119,7 @@ init_esm_shims();
 import {
   select,
   text,
+  multiselect,
   groupMultiselect,
   isCancel,
   intro,
@@ -496,7 +497,7 @@ var CATEGORY_ORDER = [
   "Utilities",
   "Ship / Show / Ask"
 ];
-async function getCommandsGroupedByCategory(variant) {
+async function loadCommandsMetadata(variant) {
   const sourcePath = path2.join(
     __dirname2,
     "..",
@@ -505,7 +506,10 @@ async function getCommandsGroupedByCategory(variant) {
   );
   const metadataPath = path2.join(sourcePath, "commands-metadata.json");
   const metadataContent = await fs.readFile(metadataPath, "utf-8");
-  const metadata = JSON.parse(metadataContent);
+  return JSON.parse(metadataContent);
+}
+async function getCommandsGroupedByCategory(variant) {
+  const metadata = await loadCommandsMetadata(variant);
   const grouped = {};
   for (const [filename, data] of Object.entries(metadata)) {
     const category = data.category;
@@ -519,6 +523,11 @@ 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;
@@ -527,12 +536,7 @@ async function getCommandsGroupedByCategory(variant) {
     });
   }
   const sortedCategories = Object.keys(grouped).sort((a, b) => {
-    const indexA = CATEGORY_ORDER.indexOf(a);
-    const indexB = CATEGORY_ORDER.indexOf(b);
-    if (indexA !== -1 && indexB !== -1) return indexA - indexB;
-    if (indexA !== -1) return -1;
-    if (indexB !== -1) return 1;
-    return a.localeCompare(b);
+    return CATEGORY_ORDER.indexOf(a) - CATEGORY_ORDER.indexOf(b);
   });
   const sortedGrouped = {};
   for (const category of sortedCategories) {
@@ -540,6 +544,37 @@ 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(", ");
+  }
+  const first = commands.slice(0, 2).map((c) => `/${c}`);
+  const remaining = commands.length - 2;
+  return `${first.join(", ")}, and ${remaining} ${remaining === 1 ? "other" : "others"}`;
+}
+async function getRequestedToolsOptions(variant) {
+  const metadata = await loadCommandsMetadata(variant);
+  const toolToCommands = /* @__PURE__ */ new Map();
+  for (const [filename, data] of Object.entries(metadata)) {
+    if (data["_requested-tools"]) {
+      const commandName = filename.replace(/\.md$/, "");
+      for (const tool of data["_requested-tools"]) {
+        const commands = toolToCommands.get(tool) || [];
+        commands.push(commandName);
+        toolToCommands.set(tool, commands);
+      }
+    }
+  }
+  return Array.from(toolToCommands.entries()).map(([tool, commands]) => ({
+    value: tool,
+    label: extractLabelFromTool(tool),
+    hint: formatCommandsHint(commands)
+  }));
+}
 function getDestinationPath(outputPath, scope) {
   if (outputPath) {
     return outputPath;
@@ -596,6 +631,20 @@ async function generateToDirectory(outputPath, variant, scope, options) {
   } else {
     await fs.copy(sourcePath, destinationPath, {});
   }
+  if (options?.allowedTools && options.allowedTools.length > 0) {
+    for (const file of files) {
+      const filePath = path2.join(destinationPath, file);
+      const content = await fs.readFile(filePath, "utf-8");
+      const allowedToolsYaml = `allowed-tools: ${options.allowedTools.join(", ")}`;
+      const modifiedContent = content.replace(
+        /^---\n/,
+        `---
+${allowedToolsYaml}
+`
+      );
+      await fs.writeFile(filePath, modifiedContent);
+    }
+  }
   if (options?.commandPrefix) {
     for (const file of files) {
       const oldPath = path2.join(destinationPath, file);
@@ -770,11 +819,26 @@ async function main(args) {
   let scope;
   let commandPrefix;
   let selectedCommands;
+  let selectedAllowedTools;
+  let cachedExistingFiles;
   if (args?.variant && args?.scope && args?.prefix !== void 0) {
     variant = args.variant;
     scope = args.scope;
     commandPrefix = args.prefix;
     selectedCommands = args.commands;
+    if (args.updateExisting) {
+      cachedExistingFiles = await checkExistingFiles(
+        void 0,
+        variant,
+        scope,
+        { commandPrefix: commandPrefix || "" }
+      );
+      selectedCommands = cachedExistingFiles.map((f) => f.filename);
+      if (selectedCommands.length === 0) {
+        log.warn("No existing commands found in target directory");
+        return;
+      }
+    }
   } else {
     variant = await select({
       message: "Select variant",
@@ -799,9 +863,34 @@ async function main(args) {
     if (isCancel(commandPrefix)) {
       return;
     }
-    const groupedCommands = await getCommandsGroupedByCategory(
+    let groupedCommands = await getCommandsGroupedByCategory(
       variant
     );
+    if (args?.updateExisting) {
+      cachedExistingFiles = await checkExistingFiles(
+        void 0,
+        variant,
+        scope,
+        { commandPrefix: commandPrefix || "" }
+      );
+      const existingFilenames = new Set(
+        cachedExistingFiles.map((f) => f.filename)
+      );
+      const filteredGrouped = {};
+      for (const [category, commands] of Object.entries(groupedCommands)) {
+        const filtered = commands.filter(
+          (cmd) => existingFilenames.has(cmd.value)
+        );
+        if (filtered.length > 0) {
+          filteredGrouped[category] = filtered;
+        }
+      }
+      groupedCommands = filteredGrouped;
+      if (Object.keys(groupedCommands).length === 0) {
+        log.warn("No existing commands found in target directory");
+        return;
+      }
+    }
     const enabledCommandValues = Object.values(groupedCommands).flat().filter((cmd) => cmd.selectedByDefault).map((cmd) => cmd.value);
     selectedCommands = await groupMultiselect({
       message: "Select commands to install (Enter to accept all)",
@@ -811,32 +900,85 @@ async function main(args) {
     if (isCancel(selectedCommands)) {
       return;
     }
-  }
-  const existingFiles = await checkExistingFiles(
-    void 0,
-    variant,
-    scope,
-    {
-      commandPrefix,
-      commands: selectedCommands
+    const requestedToolsOptions = await getRequestedToolsOptions(
+      variant
+    );
+    if (requestedToolsOptions.length > 0) {
+      selectedAllowedTools = await multiselect({
+        message: "Select allowed tools for commands (optional)",
+        options: requestedToolsOptions,
+        required: false
+      });
+      if (isCancel(selectedAllowedTools)) {
+        return;
+      }
     }
-  );
+  }
+  const existingFiles = cachedExistingFiles ?? await checkExistingFiles(void 0, variant, scope, {
+    commandPrefix,
+    commands: selectedCommands
+  });
   const skipFiles = [];
-  for (const file of existingFiles) {
-    if (file.isIdentical) {
-      log.info(`${file.filename} is identical, skipping`);
-      skipFiles.push(file.filename);
-      continue;
+  if (!args?.overwrite && !args?.skipOnConflict) {
+    const conflictingFiles = existingFiles.filter((f) => !f.isIdentical);
+    const hasMultipleConflicts = conflictingFiles.length > 1;
+    let overwriteAllSelected = false;
+    let skipAllSelected = false;
+    for (const file of existingFiles) {
+      if (file.isIdentical) {
+        log.info(`${file.filename} is identical, skipping`);
+        skipFiles.push(file.filename);
+        continue;
+      }
+      if (overwriteAllSelected) {
+        continue;
+      }
+      if (skipAllSelected) {
+        skipFiles.push(file.filename);
+        continue;
+      }
+      const stats = getDiffStats(file.existingContent, file.newContent);
+      const diff = formatCompactDiff(file.existingContent, file.newContent);
+      note(diff, `Diff: ${file.filename}`);
+      log.info(`+${stats.added} -${stats.removed}`);
+      if (hasMultipleConflicts) {
+        const choice = await select({
+          message: `Overwrite ${file.filename}?`,
+          options: [
+            { value: "yes", label: "Yes" },
+            { value: "no", label: "No" },
+            { value: "overwrite_all", label: "Overwrite all" },
+            { value: "skip_all", label: "Skip all" }
+          ]
+        });
+        if (isCancel(choice)) {
+          return;
+        }
+        if (choice === "no") {
+          skipFiles.push(file.filename);
+        } else if (choice === "overwrite_all") {
+          overwriteAllSelected = true;
+        } else if (choice === "skip_all") {
+          skipAllSelected = true;
+          skipFiles.push(file.filename);
+        }
+      } else {
+        const shouldOverwrite = await confirm({
+          message: `Overwrite ${file.filename}?`
+        });
+        if (isCancel(shouldOverwrite)) {
+          return;
+        }
+        if (!shouldOverwrite) {
+          skipFiles.push(file.filename);
+        }
+      }
     }
-    const stats = getDiffStats(file.existingContent, file.newContent);
-    const diff = formatCompactDiff(file.existingContent, file.newContent);
-    note(diff, `Diff: ${file.filename}`);
-    log.info(`+${stats.added} -${stats.removed}`);
-    const shouldOverwrite = await confirm({
-      message: `Overwrite ${file.filename}?`
-    });
-    if (!shouldOverwrite) {
-      skipFiles.push(file.filename);
+  } else if (args?.skipOnConflict) {
+    for (const file of existingFiles) {
+      if (!file.isIdentical) {
+        skipFiles.push(file.filename);
+      }
     }
   }
   const result = await generateToDirectory(
@@ -847,7 +989,8 @@ async function main(args) {
       commandPrefix,
       skipTemplateInjection: args?.skipTemplateInjection,
       commands: selectedCommands,
-      skipFiles
+      skipFiles,
+      allowedTools: selectedAllowedTools
     }
   );
   const fullPath = scope === "project" ? `${process.cwd()}/.claude/commands` : `${os2.homedir()}/.claude/commands`;
@@ -860,36 +1003,111 @@ Happy TDD'ing!`
   );
 }
 
-// scripts/bin.ts
-var STRING_ARGS = ["variant", "scope", "prefix"];
-var ARRAY_ARGS = ["commands"];
-var BOOLEAN_FLAGS = [
-  { flag: "--skip-template-injection", key: "skipTemplateInjection" }
+// 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"
+  },
+  {
+    flag: "--scope",
+    key: "scope",
+    type: "string",
+    description: "Installation scope (project, user)",
+    example: "--scope=project"
+  },
+  {
+    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");
+  return lines.join("\n");
+}
+
+// scripts/bin.ts
 function parseArgs(argv) {
   const args = {};
+  const booleanOpts = CLI_OPTIONS.filter((o) => o.type === "boolean");
+  const stringOpts = CLI_OPTIONS.filter((o) => o.type === "string");
+  const arrayOpts = CLI_OPTIONS.filter((o) => o.type === "array");
   for (const arg of argv) {
-    for (const { flag, key } of BOOLEAN_FLAGS) {
-      if (arg === flag) {
-        args[key] = true;
+    for (const opt of booleanOpts) {
+      if (arg === opt.flag) {
+        args[opt.key] = true;
       }
     }
-    for (const key of STRING_ARGS) {
-      const prefix = `--${key}=`;
+    for (const opt of stringOpts) {
+      const prefix = `${opt.flag}=`;
       if (arg.startsWith(prefix)) {
-        args[key] = arg.slice(prefix.length);
+        args[opt.key] = arg.slice(prefix.length);
       }
     }
-    for (const key of ARRAY_ARGS) {
-      const prefix = `--${key}=`;
+    for (const opt of arrayOpts) {
+      const prefix = `${opt.flag}=`;
       if (arg.startsWith(prefix)) {
-        args[key] = arg.slice(prefix.length).split(",");
+        args[opt.key] = arg.slice(prefix.length).split(",");
       }
     }
   }
   return args;
 }
 async function run(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(generateHelpText());
+    return;
+  }
   const args = parseArgs(argv);
   await main(args);
 }

package/downloads/with-beads/busycommit.md

@@ -17,6 +17,22 @@ Create multiple atomic git commits, committing the smallest possible logical uni
 
 Include any of the following info if specified: $ARGUMENTS
 
+## Commit Message Rules
+
+Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+1. **Format**: `type(#issue): description`
+   - Use `#123` for local repo issues
+   - Use `owner/repo#123` for cross-repo issues
+   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+2. **AI Credits**: **NEVER include AI credits in commit messages**
+   - No "Generated with Claude Code"
+   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
+   - Focus on the actual changes made, not conversation history
+
+3. **Content**: Write clear, concise commit messages describing what changed and why
+
 ## Process
 
 1. Run `git status` and `git diff` to review changes