@wbern/claude-instructions 1.2.0 → 1.4.0

package/README.md

@@ -19,85 +19,14 @@ TDD workflow commands for Claude Code CLI.
 
 ## Installation
 
-### Quick Install (Recommended)
-
 ```bash
 npx @wbern/claude-instructions
 ```
 
-This interactive installer lets you choose your variant and installation scope.
-
-### Manual Installation
-
-#### Without Beads Integration (Recommended for Beginners)
-
-Standalone TDD workflow commands without dependencies.
-
-**User-level (global - available in all projects):**
-```bash
-# Clone the repository
-git clone https://github.com/wbern/claude-instructions.git /tmp/claude-instructions
-
-# Copy commands to your user directory
-cp /tmp/claude-instructions/downloads/without-beads/*.md ~/.claude/commands/
-
-# Clean up
-rm -rf /tmp/claude-instructions
-```
-
-**Project-level (current repository only):**
-```bash
-# Clone the repository
-git clone https://github.com/wbern/claude-instructions.git /tmp/claude-instructions
-
-# Create commands directory and copy files
-mkdir -p .claude/commands
-cp /tmp/claude-instructions/downloads/without-beads/*.md .claude/commands/
-
-# Clean up
-rm -rf /tmp/claude-instructions
-```
-
-#### With Beads Integration
+The interactive installer lets you choose:
 
-Supports [Beads MCP](https://github.com/steveyegge/beads) integration for issue tracking and workflow management, installed separately.
-
-**Choose this if you:**
-- Are comfortable with TDD workflows
-- Need issue tracking and workflow management
-- Work in a team environment
-- Want integrated project planning with `/plan`
-
-**User-level (global - available in all projects):**
-```bash
-# Clone the repository
-git clone https://github.com/wbern/claude-instructions.git /tmp/claude-instructions
-
-# Copy commands to your user directory
-cp /tmp/claude-instructions/downloads/with-beads/*.md ~/.claude/commands/
-
-# Clean up
-rm -rf /tmp/claude-instructions
-```
-
-**Project-level (current repository only):**
-```bash
-# Clone the repository
-git clone https://github.com/wbern/claude-instructions.git /tmp/claude-instructions
-
-# Create commands directory and copy files
-mkdir -p .claude/commands
-cp /tmp/claude-instructions/downloads/with-beads/*.md .claude/commands/
-
-# Clean up
-rm -rf /tmp/claude-instructions
-```
-
-**Requirements:**
-- Install [Beads MCP](https://github.com/steveyegge/beads) for full functionality
-- Configure Beads in your project with `bd init`
-
-**Note:** User-level installation makes commands available globally in all your projects. Project-level installation only makes them available in the current repository.
+- **Variant**: With or without [Beads MCP](https://github.com/steveyegge/beads) integration
+- **Scope**: User-level (global) or project-level installation
 
 After installation, restart Claude Code if it's currently running.
 
@@ -161,6 +90,7 @@ flowchart TB
     Utils --> TDD[📚 /tdd<br/>Remind agent about TDD]
     Utils --> AddCommand[➕ /add-command<br/>Create custom commands]
     Utils --> Summarize[📄 /summarize<br/>Summarize conversation<br/><i>Optional: Beads MCP</i>]
+    Utils --> Gap[🔍 /gap<br/>Find unaddressed items<br/><i>Optional: Beads MCP</i>]
     Utils --> Beepboop[🤖 /beepboop<br/>AI attribution]
 
     Worktree[<b>WORKTREE MANAGEMENT</b>]
@@ -193,6 +123,7 @@ flowchart TB
 - `/show` - Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)
 - `/ask` - Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)
 - `/summarize` - Summarize conversation progress and next steps
+- `/gap` - Analyze conversation context for unaddressed items and gaps
 
 ### Worktree Management
 
@@ -212,6 +143,7 @@ flowchart TB
 Here's a simple example to get you started with the TDD workflow:
 
 **1. Write a failing test (`/red`)**
+
 ```
 You: /red add a function that validates email addresses
 
@@ -221,6 +153,7 @@ Claude: I'll write a failing test for email validation.
 ```
 
 **2. Make it pass (`/green`)**
+
 ```
 You: /green
 
@@ -230,6 +163,7 @@ Claude: I'll implement the minimal code to pass the test.
 ```
 
 **3. Refactor for quality (`/refactor`)**
+
 ```
 You: /refactor extract regex pattern to a constant
 
@@ -241,18 +175,23 @@ Claude: I'll refactor while keeping tests green.
 ### Complete Workflow Example
 
 **Starting from a GitHub issue:**
+
 ```
 /issue 123
 ```
+
 Claude analyzes the GitHub issue and creates a TDD implementation plan showing what tests to write.
 
 **Running a full TDD cycle:**
+
 ```
 /cycle implement user authentication with password hashing
 ```
+
 Claude executes the complete red-green-refactor cycle: writes a failing test, implements it, then refactors.
 
 **Individual phases for more control:**
+
 ```
 /red test that users can't login with wrong password
 /green
@@ -260,14 +199,17 @@ Claude executes the complete red-green-refactor cycle: writes a failing test, im
 ```
 
 **Committing and creating PRs:**
+
 ```
 /commit
 ```
+
 Claude reviews changes, drafts a commit message following project standards, and creates the commit.
 
 ```
-/pr
+/ask
 ```
+
 Claude analyzes commits, creates a PR with summary and test plan.
 
 ### What to Expect
@@ -292,69 +234,84 @@ The commands enforce TDD discipline: you can't refactor with failing tests, can'
 
 👤 `/red` single element [1] returns 1
 
-🔴 *writes test*
+🔴 _writes test_
+
 ```typescript
 expect(closestToZero([1])).toBe(1);
 ```
+
 FAIL: closestToZero is not defined
 
 👤 `/green`
 
-🟢 *returns hardcoded 1*
+🟢 _returns hardcoded 1_
+
 ```typescript
 function closestToZero(nums: number[]): number {
   return 1; // minimal - only need to pass current test
 }
 ```
+
 ✅ Test passes
 
 👤 `/red` two numbers [3, 2] returns 2
 
-🔴 *writes test*
+🔴 _writes test_
+
 ```typescript
 expect(closestToZero([3, 2])).toBe(2);
 ```
+
 FAIL: expected 1 to be 2
 
 👤 `/green`
 
-🟢 *sorts and returns first*
+🟢 _sorts and returns first_
+
 ```typescript
 function closestToZero(nums: number[]): number {
   return nums.sort((a, b) => a - b)[0]; // minimal
 }
 ```
+
 ✅ 2/2 tests pass
 
 👤 `/red` with negative [-3, 2] returns 2
 
-🔴 *writes test*
+🔴 _writes test_
+
 ```typescript
 expect(closestToZero([-3, 2])).toBe(2);
 ```
+
 FAIL: expected -3 to be 2 (regular sort puts -3 first)
 
 👤 `/green`
 
-🟢 *sorts by absolute value*
+🟢 _sorts by absolute value_
+
 ```typescript
 function closestToZero(nums: number[]): number {
   return nums.sort((a, b) => Math.abs(a) - Math.abs(b))[0];
 }
 ```
+
 ✅ 3/3 tests pass
 
 👤 `/red` exact tie [-2, 2] returns positive 2
 
-🔴 *writes test*
+🔴 _writes test_
+
 ```typescript
 expect(closestToZero([-2, 2])).toBe(2);
 ```
+
 FAIL: expected -2 to be 2 (returns first when tied)
 
 👤 `/green`
 
-🟢 *adds tie-breaking: prefer positive*
+🟢 _adds tie-breaking: prefer positive_
+
 ```typescript
 function closestToZero(nums: number[]): number {
   return nums.sort((a, b) => {
@@ -363,11 +320,13 @@ function closestToZero(nums: number[]): number {
   })[0];
 }
 ```
+
 ✅ 4/4 tests pass
 
 👤 `/refactor` extract helper and use iteration instead of sort
 
-🔵 *extracts helper function for comparison logic*
+🔵 _extracts helper function for comparison logic_
+
 ```typescript
 function isCloser(candidate: number, current: number): boolean {
   const candAbs = Math.abs(candidate);
@@ -386,21 +345,23 @@ function closestToZero(nums: number[]): number {
   return closest;
 }
 ```
+
 ✅ 4/4 tests still pass
 
 👤 `/refactor`
 
-🔵 *uses reduce for more functional style*
+🔵 _uses reduce for more functional style_
+
 ```typescript
 function closestToZero(nums: number[]): number {
   if (nums.length === 0) return 0;
   return nums.reduce((closest, num) =>
-    isCloser(num, closest) ? num : closest
+    isCloser(num, closest) ? num : closest,
   );
 }
 ```
-✅ 4/4 tests still pass
 
+✅ 4/4 tests still pass
 
 ## Contributing
 

package/bin/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // scripts/cli.ts
-import { select, isCancel, intro, outro } from "@clack/prompts";
+import { select, text, groupMultiselect, isCancel, intro, outro } from "@clack/prompts";
+import os2 from "os";
 
 // scripts/cli-generator.ts
 import fs from "fs-extra";
@@ -24,14 +25,55 @@ var DIRECTORIES = {
   DOWNLOADS: "downloads"
 };
 var TEMPLATE_SOURCE_FILES = ["CLAUDE.md", "AGENTS.md"];
+var ELLIPSIS = "...";
+function truncatePathFromLeft(pathStr, maxLength) {
+  if (pathStr.length <= maxLength) {
+    return pathStr;
+  }
+  const truncated = pathStr.slice(-(maxLength - ELLIPSIS.length));
+  const firstSlash = truncated.indexOf("/");
+  if (firstSlash > 0) {
+    return ELLIPSIS + truncated.slice(firstSlash);
+  }
+  return ELLIPSIS + truncated;
+}
 var VARIANT_OPTIONS = [
-  { value: VARIANTS.WITH_BEADS, label: "With Beads" },
-  { value: VARIANTS.WITHOUT_BEADS, label: "Without Beads" }
-];
-var SCOPE_OPTIONS = [
-  { value: SCOPES.PROJECT, label: "Project/Repository" },
-  { value: SCOPES.USER, label: "User (Global)" }
+  { value: VARIANTS.WITH_BEADS, label: "With Beads", hint: "Includes Beads task tracking" },
+  { value: VARIANTS.WITHOUT_BEADS, label: "Without Beads", hint: "Standard commands only" }
 ];
+function getScopeOptions(terminalWidth = 80) {
+  const projectPath = path.join(process.cwd(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+  const userPath = path.join(os.homedir(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+  return [
+    { value: SCOPES.PROJECT, label: "Project/Repository", hint: truncatePathFromLeft(projectPath, terminalWidth) },
+    { value: SCOPES.USER, label: "User (Global)", hint: truncatePathFromLeft(userPath, terminalWidth) }
+  ];
+}
+async function getCommandsGroupedByCategory(variant) {
+  const sourcePath = path.join(__dirname, "..", DIRECTORIES.DOWNLOADS, variant || VARIANTS.WITH_BEADS);
+  const metadataPath = path.join(sourcePath, "commands-metadata.json");
+  const metadataContent = await fs.readFile(metadataPath, "utf-8");
+  const metadata = JSON.parse(metadataContent);
+  const grouped = {};
+  for (const [filename, data] of Object.entries(metadata)) {
+    const category = data.category;
+    if (!grouped[category]) {
+      grouped[category] = [];
+    }
+    grouped[category].push({
+      value: filename,
+      label: filename
+    });
+  }
+  for (const category of Object.keys(grouped)) {
+    grouped[category].sort((a, b) => {
+      const orderA = metadata[a.value].order;
+      const orderB = metadata[b.value].order;
+      return orderA - orderB;
+    });
+  }
+  return grouped;
+}
 function getDestinationPath(outputPath, scope) {
   if (outputPath) {
     return outputPath;
@@ -64,8 +106,23 @@ async function generateToDirectory(outputPath, variant, scope, options) {
   if (!destinationPath) {
     throw new Error("Either outputPath or scope must be provided");
   }
-  const files = await fs.readdir(sourcePath);
-  await fs.copy(sourcePath, destinationPath, {});
+  const allFiles = await fs.readdir(sourcePath);
+  const files = options?.commands ? allFiles.filter((f) => options.commands.includes(f)) : allFiles;
+  if (options?.commands) {
+    await fs.ensureDir(destinationPath);
+    for (const file of files) {
+      await fs.copy(path.join(sourcePath, file), path.join(destinationPath, file));
+    }
+  } else {
+    await fs.copy(sourcePath, destinationPath, {});
+  }
+  if (options?.commandPrefix) {
+    for (const file of files) {
+      const oldPath = path.join(destinationPath, file);
+      const newPath = path.join(destinationPath, options.commandPrefix + file);
+      await fs.rename(oldPath, newPath);
+    }
+  }
   let templateInjected = false;
   if (!options?.skipTemplateInjection) {
     let templateSourcePath = null;
@@ -85,7 +142,8 @@ async function generateToDirectory(outputPath, variant, scope, options) {
           if (template.commands && !template.commands.includes(commandName)) {
             continue;
           }
-          const filePath = path.join(destinationPath, file);
+          const actualFileName = options?.commandPrefix ? options.commandPrefix + file : file;
+          const filePath = path.join(destinationPath, actualFileName);
           const content = await fs.readFile(filePath, "utf-8");
           await fs.writeFile(filePath, content + "\n\n" + template.content);
         }
@@ -119,25 +177,96 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
             @wbern/claude-instructions
 `;
-async function main() {
+async function main(args) {
   intro(BATMAN_LOGO);
-  const variant = await select({
-    message: "Select variant",
-    options: [...VARIANT_OPTIONS]
-  });
-  if (isCancel(variant)) {
-    return;
-  }
-  const scope = await select({
-    message: "Select installation scope",
-    options: [...SCOPE_OPTIONS]
-  });
-  if (isCancel(scope)) {
-    return;
+  let variant;
+  let scope;
+  let commandPrefix;
+  let selectedCommands;
+  if (args?.variant && args?.scope && args?.prefix !== void 0) {
+    variant = args.variant;
+    scope = args.scope;
+    commandPrefix = args.prefix;
+    selectedCommands = args.commands;
+  } else {
+    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({
+      message: "Select installation scope",
+      options: getScopeOptions(terminalWidth - uiOverhead)
+    });
+    if (isCancel(scope)) {
+      return;
+    }
+    commandPrefix = await text({
+      message: "Command prefix (optional)",
+      placeholder: "e.g. my-"
+    });
+    if (isCancel(commandPrefix)) {
+      return;
+    }
+    const groupedCommands = await getCommandsGroupedByCategory(variant);
+    const allCommandValues = Object.values(groupedCommands).flat().map((cmd) => cmd.value);
+    selectedCommands = await groupMultiselect({
+      message: "Select commands to install (Enter to accept all)",
+      options: groupedCommands,
+      initialValues: allCommandValues
+    });
+    if (isCancel(selectedCommands)) {
+      return;
+    }
   }
-  const result = await generateToDirectory(void 0, variant, scope);
-  outro(`Installed ${result.filesGenerated} commands to .claude/commands`);
+  const result = await generateToDirectory(void 0, variant, scope, { commandPrefix, skipTemplateInjection: args?.skipTemplateInjection, commands: selectedCommands });
+  const fullPath = scope === "project" ? `${process.cwd()}/.claude/commands` : `${os2.homedir()}/.claude/commands`;
+  outro(`Installed ${result.filesGenerated} commands to ${fullPath}
+
+If Claude Code is already running, restart it to pick up the new commands.
+
+Happy TDD'ing!`);
 }
 
 // scripts/bin.ts
-main().catch(console.error);
+var STRING_ARGS = ["variant", "scope", "prefix"];
+var ARRAY_ARGS = ["commands"];
+var BOOLEAN_FLAGS = [
+  { flag: "--skip-template-injection", key: "skipTemplateInjection" }
+];
+function parseArgs(argv) {
+  const args = {};
+  for (const arg of argv) {
+    for (const { flag, key } of BOOLEAN_FLAGS) {
+      if (arg === flag) {
+        args[key] = true;
+      }
+    }
+    for (const key of STRING_ARGS) {
+      const prefix = `--${key}=`;
+      if (arg.startsWith(prefix)) {
+        args[key] = arg.slice(prefix.length);
+      }
+    }
+    for (const key of ARRAY_ARGS) {
+      const prefix = `--${key}=`;
+      if (arg.startsWith(prefix)) {
+        args[key] = arg.slice(prefix.length).split(",");
+      }
+    }
+  }
+  return args;
+}
+async function run(argv) {
+  const args = parseArgs(argv);
+  await main(args);
+}
+run(process.argv.slice(2)).catch(console.error);
+export {
+  parseArgs,
+  run
+};

package/downloads/with-beads/ask.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
 description: Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)
 argument-hint: [optional-pr-title-and-description]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-pr-title-and-description]
 > 💭 **Cursor says**: Fine, SOME things still need traditional PRs. But be intentional about it.
 
 Ask is for complex changes that need team discussion and approval. Examples:
+
 - Breaking API changes
 - New architecture decisions
 - Significant feature additions
@@ -27,6 +28,7 @@ Ask is for complex changes that need team discussion and approval. Examples:
 ## When to Ask
 
 Use **Ask** when:
+
 - Changes affect multiple systems
 - Breaking changes are needed
 - You need input on approach
@@ -54,10 +56,11 @@ Arguments: $ARGUMENTS
    - Push to remote: `git push origin [branch-name]`
 
 2. **Create Ask PR**: Create a PR that clearly needs review
-   
+
    Title: conventional commits format, prefixed with `[ASK]`
-   
+
    Description template:
+
    ```markdown
    ## 🤔 Ask - Review and Approval Needed
 
@@ -68,32 +71,38 @@ Arguments: $ARGUMENTS
    -->
 
    ### What changed
+
    [Detailed description of changes]
 
    ### Why
+
    [Rationale and context]
 
    ### Questions for reviewers
+
    - [ ] Question 1
    - [ ] Question 2
 
    ### Concerns
+
    - Potential concern 1
    - Potential concern 2
 
    ### Test Plan
+
    - [ ] Unit tests
    - [ ] Integration tests
    - [ ] Manual testing steps
 
    ### Alternatives considered
+
    - Alternative 1: [why not chosen]
    - Alternative 2: [why not chosen]
    ```
 
 3. **Request Reviewers**: Assign specific reviewers who should weigh in
 
-4. **Add Labels**: 
+4. **Add Labels**:
    - "needs-review"
    - "breaking-change" (if applicable)
    - "security" (if applicable)
@@ -113,6 +122,7 @@ Arguments: $ARGUMENTS
 ## Decision Guide
 
 Use **Ask** when:
+
 - ✅ Change is complex or risky
 - ✅ Breaking changes involved
 - ✅ Need team input on approach
@@ -131,4 +141,3 @@ Use Beads MCP to:
 - Track dependencies with `bd dep add`
 
 See https://github.com/steveyegge/beads for more information.
-

package/downloads/with-beads/commands-metadata.json

@@ -0,0 +1,92 @@
+{
+  "add-command.md": {
+    "description": "Guide for creating new slash commands",
+    "category": "Utilities",
+    "order": 3
+  },
+  "ask.md": {
+    "description": "Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)",
+    "category": "Workflow",
+    "order": 4
+  },
+  "beepboop.md": {
+    "description": "Communicate AI-generated content with transparent attribution",
+    "category": "Utilities",
+    "order": 2
+  },
+  "commit.md": {
+    "description": "Create a git commit following project standards",
+    "category": "Workflow",
+    "order": 1
+  },
+  "cycle.md": {
+    "description": "Execute complete TDD cycle - Red, Green, and Refactor phases in sequence",
+    "category": "TDD Cycle",
+    "order": 5
+  },
+  "gap.md": {
+    "description": "Analyze conversation context for unaddressed items and gaps",
+    "category": "Workflow",
+    "order": 11
+  },
+  "green.md": {
+    "description": "Execute TDD Green Phase - write minimal implementation to pass the failing test",
+    "category": "TDD Cycle",
+    "order": 3
+  },
+  "issue.md": {
+    "description": "Analyze GitHub issue and create TDD implementation plan",
+    "category": "Planning",
+    "order": 1
+  },
+  "plan.md": {
+    "description": "Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria",
+    "category": "Planning",
+    "order": 2
+  },
+  "red.md": {
+    "description": "Execute TDD Red Phase - write ONE failing test",
+    "category": "TDD Cycle",
+    "order": 2
+  },
+  "refactor.md": {
+    "description": "Execute TDD Refactor Phase - improve code structure while keeping tests green",
+    "category": "TDD Cycle",
+    "order": 4
+  },
+  "ship.md": {
+    "description": "Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)",
+    "category": "Workflow",
+    "order": 2
+  },
+  "show.md": {
+    "description": "Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)",
+    "category": "Workflow",
+    "order": 3
+  },
+  "spike.md": {
+    "description": "Execute TDD Spike Phase - exploratory coding to understand problem space before TDD",
+    "category": "TDD Cycle",
+    "order": 1
+  },
+  "summarize.md": {
+    "description": "Summarize conversation progress and next steps",
+    "category": "Workflow",
+    "order": 10
+  },
+  "tdd.md": {
+    "description": "Remind agent about TDD approach and continue conversation",
+    "category": "Utilities",
+    "order": 1
+  },
+  "worktree-add.md": {
+    "description": "Add a new git worktree from branch name or GitHub issue URL, copy settings, install deps, and open in current IDE",
+    "category": "Worktree Management",
+    "order": 1
+  },
+  "worktree-cleanup.md": {
+    "description": "Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees",
+    "category": "Worktree Management",
+    "order": 2
+  }
+}

package/downloads/with-beads/cycle.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
 argument-hint: <feature or requirement description>
 ---

package/downloads/with-beads/gap.md

@@ -0,0 +1,22 @@
+---
+description: Analyze conversation context for unaddressed items and gaps
+---
+
+Analyze the current conversation context and identify things that have not yet been addressed. Look for:
+
+1. **Incomplete implementations** - Code that was started but not finished
+2. **Unused variables/results** - Values that were captured but never used
+3. **Missing tests** - Functionality without test coverage
+      4. **Open issues** - Beads issues that are still open or in progress
+      4. **User requests** - Things the user asked for that weren't fully completed
+5. **TODO comments** - Any TODOs mentioned in conversation
+6. **Error handling gaps** - Missing error cases or edge cases
+7. **Documentation gaps** - Undocumented APIs or features
+
+Present findings as a prioritized list with:
+
+- What the gap is
+- Why it matters
+- Suggested next action
+
+If there are no gaps, confirm that everything discussed has been addressed.

package/downloads/with-beads/green.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Green Phase - write minimal implementation to pass the failing test
 argument-hint: <implementation description>
 ---

package/downloads/with-beads/red.md

@@ -1,4 +1,5 @@
 ---
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Red Phase - write ONE failing test
 ---
 

package/downloads/with-beads/refactor.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Refactor Phase - improve code structure while keeping tests green
 argument-hint: <refactoring description>
 ---

package/downloads/with-beads/ship.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: Bash(git status:*), Bash(git log:*), Bash(git diff:*), Bash(git checkout:*), Bash(git pull:*), Bash(git merge:*), Bash(git push:*), Bash(git branch:*)
 description: Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)
 argument-hint: [optional-commit-message]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-commit-message]
 > 🎯 **Cursor says**: It's 2025! Not everything needs a PR. Ship small, obvious changes directly.
 
 Ship is for small, obvious changes that don't need code review. Examples:
+
 - Typo fixes
 - Formatting changes
 - Documentation updates
@@ -27,6 +28,7 @@ Ship is for small, obvious changes that don't need code review. Examples:
 ## Prerequisites
 
 Before shipping directly to main:
+
 1. All tests must pass
 2. Linter must pass
 3. Changes must be small and low-risk
@@ -57,10 +59,11 @@ Arguments: $ARGUMENTS
    - Is this a small, obvious change?
    - Do all tests pass?
    - Is CI green?
-   
+
    If ANY of these are "no", suggest using `/show` or `/ask` instead.
 
 5. **Merge to Main**: If all checks pass and user confirms:
+
    ```bash
    git checkout main
    git pull origin main
@@ -69,6 +72,7 @@ Arguments: $ARGUMENTS
    ```
 
 6. **Cleanup**: Delete the feature branch
+
    ```bash
    git branch -d [feature-branch]
    git push origin --delete [feature-branch]
@@ -79,6 +83,7 @@ Arguments: $ARGUMENTS
 ## Safety Rails
 
 If tests fail, linter fails, or changes are large/complex, STOP and suggest:
+
 - Use `/show` for changes that should be seen but don't need approval
 - Use `/ask` (traditional PR) for complex changes needing discussion
 
@@ -90,4 +95,3 @@ Use Beads MCP to:
 - Track dependencies with `bd dep add`
 
 See https://github.com/steveyegge/beads for more information.
-

package/downloads/with-beads/show.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
 description: Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)
 argument-hint: [optional-pr-title-and-description]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-pr-title-and-description]
 > 🚀 **Cursor says**: Not every change needs a traditional review. Show your work, then merge.
 
 Show is for changes that teammates should see, but don't require approval. Examples:
+
 - Refactoring with test coverage
 - New features with comprehensive tests
 - Performance improvements
@@ -26,6 +27,7 @@ Show is for changes that teammates should see, but don't require approval. Examp
 ## Prerequisites
 
 Before using show:
+
 1. All tests must pass
 2. Changes should have good test coverage
 3. Changes should be non-breaking or backward compatible
@@ -60,6 +62,7 @@ Arguments: $ARGUMENTS
    - Add notice that feedback is welcome but not required
 
 4. **PR Description Template**:
+
    ```markdown
    ## 🚀 Show - Auto-merging after CI
 
@@ -71,12 +74,15 @@ Arguments: $ARGUMENTS
    -->
 
    ### What changed
+
    [Brief description]
 
    ### Why
+
    [Rationale for change]
 
    ### Test coverage
+
    - [ ] All tests pass
    - [ ] Coverage maintained/improved
    - [ ] No breaking changes
@@ -87,6 +93,7 @@ Arguments: $ARGUMENTS
 ## Decision Guide
 
 Use **Show** when:
+
 - ✅ Tests are comprehensive
 - ✅ Changes are non-breaking
 - ✅ You're confident in the approach
@@ -104,4 +111,3 @@ Use Beads MCP to:
 - Track dependencies with `bd dep add`
 
 See https://github.com/steveyegge/beads for more information.
-

package/downloads/with-beads/summarize.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: AskUserQuestion, mcp__beads__list, mcp__beads__stats
+allowed-tools: AskUserQuestion
 description: Summarize conversation progress and next steps
 ---
 

package/downloads/without-beads/ask.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
 description: Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)
 argument-hint: [optional-pr-title-and-description]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-pr-title-and-description]
 > 💭 **Cursor says**: Fine, SOME things still need traditional PRs. But be intentional about it.
 
 Ask is for complex changes that need team discussion and approval. Examples:
+
 - Breaking API changes
 - New architecture decisions
 - Significant feature additions
@@ -27,6 +28,7 @@ Ask is for complex changes that need team discussion and approval. Examples:
 ## When to Ask
 
 Use **Ask** when:
+
 - Changes affect multiple systems
 - Breaking changes are needed
 - You need input on approach
@@ -54,10 +56,11 @@ Arguments: $ARGUMENTS
    - Push to remote: `git push origin [branch-name]`
 
 2. **Create Ask PR**: Create a PR that clearly needs review
-   
+
    Title: conventional commits format, prefixed with `[ASK]`
-   
+
    Description template:
+
    ```markdown
    ## 🤔 Ask - Review and Approval Needed
 
@@ -68,32 +71,38 @@ Arguments: $ARGUMENTS
    -->
 
    ### What changed
+
    [Detailed description of changes]
 
    ### Why
+
    [Rationale and context]
 
    ### Questions for reviewers
+
    - [ ] Question 1
    - [ ] Question 2
 
    ### Concerns
+
    - Potential concern 1
    - Potential concern 2
 
    ### Test Plan
+
    - [ ] Unit tests
    - [ ] Integration tests
    - [ ] Manual testing steps
 
    ### Alternatives considered
+
    - Alternative 1: [why not chosen]
    - Alternative 2: [why not chosen]
    ```
 
 3. **Request Reviewers**: Assign specific reviewers who should weigh in
 
-4. **Add Labels**: 
+4. **Add Labels**:
    - "needs-review"
    - "breaking-change" (if applicable)
    - "security" (if applicable)
@@ -113,6 +122,7 @@ Arguments: $ARGUMENTS
 ## Decision Guide
 
 Use **Ask** when:
+
 - ✅ Change is complex or risky
 - ✅ Breaking changes involved
 - ✅ Need team input on approach
@@ -123,4 +133,3 @@ Use **/show** instead if: confident in approach, just want visibility
 
 Use **/ship** instead if: change is tiny, obvious, and safe
 
-

package/downloads/without-beads/commands-metadata.json

@@ -0,0 +1,92 @@
+{
+  "add-command.md": {
+    "description": "Guide for creating new slash commands",
+    "category": "Utilities",
+    "order": 3
+  },
+  "ask.md": {
+    "description": "Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)",
+    "category": "Workflow",
+    "order": 4
+  },
+  "beepboop.md": {
+    "description": "Communicate AI-generated content with transparent attribution",
+    "category": "Utilities",
+    "order": 2
+  },
+  "commit.md": {
+    "description": "Create a git commit following project standards",
+    "category": "Workflow",
+    "order": 1
+  },
+  "cycle.md": {
+    "description": "Execute complete TDD cycle - Red, Green, and Refactor phases in sequence",
+    "category": "TDD Cycle",
+    "order": 5
+  },
+  "gap.md": {
+    "description": "Analyze conversation context for unaddressed items and gaps",
+    "category": "Workflow",
+    "order": 11
+  },
+  "green.md": {
+    "description": "Execute TDD Green Phase - write minimal implementation to pass the failing test",
+    "category": "TDD Cycle",
+    "order": 3
+  },
+  "issue.md": {
+    "description": "Analyze GitHub issue and create TDD implementation plan",
+    "category": "Planning",
+    "order": 1
+  },
+  "plan.md": {
+    "description": "Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria",
+    "category": "Planning",
+    "order": 2
+  },
+  "red.md": {
+    "description": "Execute TDD Red Phase - write ONE failing test",
+    "category": "TDD Cycle",
+    "order": 2
+  },
+  "refactor.md": {
+    "description": "Execute TDD Refactor Phase - improve code structure while keeping tests green",
+    "category": "TDD Cycle",
+    "order": 4
+  },
+  "ship.md": {
+    "description": "Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)",
+    "category": "Workflow",
+    "order": 2
+  },
+  "show.md": {
+    "description": "Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)",
+    "category": "Workflow",
+    "order": 3
+  },
+  "spike.md": {
+    "description": "Execute TDD Spike Phase - exploratory coding to understand problem space before TDD",
+    "category": "TDD Cycle",
+    "order": 1
+  },
+  "summarize.md": {
+    "description": "Summarize conversation progress and next steps",
+    "category": "Workflow",
+    "order": 10
+  },
+  "tdd.md": {
+    "description": "Remind agent about TDD approach and continue conversation",
+    "category": "Utilities",
+    "order": 1
+  },
+  "worktree-add.md": {
+    "description": "Add a new git worktree from branch name or GitHub issue URL, copy settings, install deps, and open in current IDE",
+    "category": "Worktree Management",
+    "order": 1
+  },
+  "worktree-cleanup.md": {
+    "description": "Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees",
+    "category": "Worktree Management",
+    "order": 2
+  }
+}

package/downloads/without-beads/cycle.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
 argument-hint: <feature or requirement description>
 ---

package/downloads/without-beads/gap.md

@@ -0,0 +1,21 @@
+---
+description: Analyze conversation context for unaddressed items and gaps
+---
+
+Analyze the current conversation context and identify things that have not yet been addressed. Look for:
+
+1. **Incomplete implementations** - Code that was started but not finished
+2. **Unused variables/results** - Values that were captured but never used
+3. **Missing tests** - Functionality without test coverage
+      4. **User requests** - Things the user asked for that weren't fully completed
+5. **TODO comments** - Any TODOs mentioned in conversation
+6. **Error handling gaps** - Missing error cases or edge cases
+7. **Documentation gaps** - Undocumented APIs or features
+
+Present findings as a prioritized list with:
+
+- What the gap is
+- Why it matters
+- Suggested next action
+
+If there are no gaps, confirm that everything discussed has been addressed.

package/downloads/without-beads/green.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Green Phase - write minimal implementation to pass the failing test
 argument-hint: <implementation description>
 ---

package/downloads/without-beads/red.md

@@ -1,4 +1,5 @@
 ---
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Red Phase - write ONE failing test
 ---
 

package/downloads/without-beads/refactor.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Refactor Phase - improve code structure while keeping tests green
 argument-hint: <refactoring description>
 ---

package/downloads/without-beads/ship.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: Bash(git status:*), Bash(git log:*), Bash(git diff:*), Bash(git checkout:*), Bash(git pull:*), Bash(git merge:*), Bash(git push:*), Bash(git branch:*)
 description: Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)
 argument-hint: [optional-commit-message]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-commit-message]
 > 🎯 **Cursor says**: It's 2025! Not everything needs a PR. Ship small, obvious changes directly.
 
 Ship is for small, obvious changes that don't need code review. Examples:
+
 - Typo fixes
 - Formatting changes
 - Documentation updates
@@ -27,6 +28,7 @@ Ship is for small, obvious changes that don't need code review. Examples:
 ## Prerequisites
 
 Before shipping directly to main:
+
 1. All tests must pass
 2. Linter must pass
 3. Changes must be small and low-risk
@@ -57,10 +59,11 @@ Arguments: $ARGUMENTS
    - Is this a small, obvious change?
    - Do all tests pass?
    - Is CI green?
-   
+
    If ANY of these are "no", suggest using `/show` or `/ask` instead.
 
 5. **Merge to Main**: If all checks pass and user confirms:
+
    ```bash
    git checkout main
    git pull origin main
@@ -69,6 +72,7 @@ Arguments: $ARGUMENTS
    ```
 
 6. **Cleanup**: Delete the feature branch
+
    ```bash
    git branch -d [feature-branch]
    git push origin --delete [feature-branch]
@@ -79,7 +83,7 @@ Arguments: $ARGUMENTS
 ## Safety Rails
 
 If tests fail, linter fails, or changes are large/complex, STOP and suggest:
+
 - Use `/show` for changes that should be seen but don't need approval
 - Use `/ask` (traditional PR) for complex changes needing discussion
 
-

package/downloads/without-beads/show.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: mcp__github__*, Bash(git:*)
+allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
 description: Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)
 argument-hint: [optional-pr-title-and-description]
 ---
@@ -18,6 +18,7 @@ argument-hint: [optional-pr-title-and-description]
 > 🚀 **Cursor says**: Not every change needs a traditional review. Show your work, then merge.
 
 Show is for changes that teammates should see, but don't require approval. Examples:
+
 - Refactoring with test coverage
 - New features with comprehensive tests
 - Performance improvements
@@ -26,6 +27,7 @@ Show is for changes that teammates should see, but don't require approval. Examp
 ## Prerequisites
 
 Before using show:
+
 1. All tests must pass
 2. Changes should have good test coverage
 3. Changes should be non-breaking or backward compatible
@@ -60,6 +62,7 @@ Arguments: $ARGUMENTS
    - Add notice that feedback is welcome but not required
 
 4. **PR Description Template**:
+
    ```markdown
    ## 🚀 Show - Auto-merging after CI
 
@@ -71,12 +74,15 @@ Arguments: $ARGUMENTS
    -->
 
    ### What changed
+
    [Brief description]
 
    ### Why
+
    [Rationale for change]
 
    ### Test coverage
+
    - [ ] All tests pass
    - [ ] Coverage maintained/improved
    - [ ] No breaking changes
@@ -87,6 +93,7 @@ Arguments: $ARGUMENTS
 ## Decision Guide
 
 Use **Show** when:
+
 - ✅ Tests are comprehensive
 - ✅ Changes are non-breaking
 - ✅ You're confident in the approach
@@ -96,4 +103,3 @@ Use **/ship** instead if: change is tiny and obvious (typo, formatting)
 
 Use **/ask** instead if: change needs discussion, breaks APIs, or you're uncertain
 
-

package/downloads/without-beads/summarize.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: AskUserQuestion, mcp__beads__list, mcp__beads__stats
+allowed-tools: AskUserQuestion
 description: Summarize conversation progress and next steps
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -28,25 +28,33 @@
   "license": "MIT",
   "scripts": {
     "clean": "rm -rf downloads",
-    "clean:dev": "rm -rf .claude/commands",
-    "build": "bash scripts/build.sh",
-    "build:dev": "bash scripts/build-dev.sh",
+    "build": "tsx scripts/build.ts",
     "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",
     "generate": "tsx scripts/cli-generator.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "knip": "knip",
+    "duplication-check": "jscpd",
     "prepublishOnly": "bash scripts/check-publish.sh && pnpm build && pnpm build:cli",
     "prepare": "husky"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
     "husky": "^9.1.7",
+    "jscpd": "^4.0.5",
+    "knip": "^5.70.2",
+    "lint-staged": "^16.2.7",
     "markdown-magic": "^4.0.4",
+    "prettier": "^3.7.2",
     "tsup": "^8.5.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
     "vitest": "^4.0.8"
   },
   "dependencies": {