@wbern/claude-instructions 1.1.0 → 1.3.0

package/README.md

@@ -19,85 +19,13 @@ 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
-
-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.
+The interactive installer lets you choose:
+- **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.
 

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/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";
 
 // scripts/cli-generator.ts
 import fs from "fs-extra";
@@ -23,6 +23,7 @@ var DIRECTORIES = {
   COMMANDS: "commands",
   DOWNLOADS: "downloads"
 };
+var TEMPLATE_SOURCE_FILES = ["CLAUDE.md", "AGENTS.md"];
 var VARIANT_OPTIONS = [
   { value: VARIANTS.WITH_BEADS, label: "With Beads" },
   { value: VARIANTS.WITHOUT_BEADS, label: "Without Beads" }
@@ -31,6 +32,31 @@ var SCOPE_OPTIONS = [
   { value: SCOPES.PROJECT, label: "Project/Repository" },
   { value: SCOPES.USER, label: "User (Global)" }
 ];
+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;
@@ -43,18 +69,77 @@ function getDestinationPath(outputPath, scope) {
   }
   return void 0;
 }
-async function generateToDirectory(outputPath, variant, scope) {
+function extractTemplateBlocks(content) {
+  const matchWithCommands = content.match(/<claude-commands-template\s+commands="([^"]+)">([\s\S]*?)<\/claude-commands-template>/);
+  if (matchWithCommands) {
+    return {
+      content: matchWithCommands[2].trim(),
+      commands: matchWithCommands[1].split(",").map((c) => c.trim())
+    };
+  }
+  const match = content.match(/<claude-commands-template>([\s\S]*?)<\/claude-commands-template>/);
+  if (!match) {
+    return null;
+  }
+  return { content: match[1].trim() };
+}
+async function generateToDirectory(outputPath, variant, scope, options) {
   const sourcePath = path.join(__dirname, "..", DIRECTORIES.DOWNLOADS, variant || VARIANTS.WITH_BEADS);
   const destinationPath = getDestinationPath(outputPath, scope);
   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;
+    for (const filename of TEMPLATE_SOURCE_FILES) {
+      const candidatePath = path.join(process.cwd(), filename);
+      if (await fs.pathExists(candidatePath)) {
+        templateSourcePath = candidatePath;
+        break;
+      }
+    }
+    if (templateSourcePath) {
+      const sourceContent = await fs.readFile(templateSourcePath, "utf-8");
+      const template = extractTemplateBlocks(sourceContent);
+      if (template) {
+        for (const file of files) {
+          const commandName = path.basename(file, ".md");
+          if (template.commands && !template.commands.includes(commandName)) {
+            continue;
+          }
+          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);
+        }
+        templateInjected = true;
+      }
+    }
+  }
   return {
     success: true,
     filesGenerated: files.length,
-    variant
+    variant,
+    templateInjectionSkipped: options?.skipTemplateInjection,
+    templateInjected
   };
 }
 
@@ -75,25 +160,89 @@ 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;
+  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;
+    }
+    scope = await select({
+      message: "Select installation scope",
+      options: [...SCOPE_OPTIONS]
+    });
+    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 scope = await select({
-    message: "Select installation scope",
-    options: [...SCOPE_OPTIONS]
-  });
-  if (isCancel(scope)) {
-    return;
-  }
-  const result = await generateToDirectory(void 0, variant, scope);
+  const result = await generateToDirectory(void 0, variant, scope, { commandPrefix, skipTemplateInjection: args?.skipTemplateInjection, commands: selectedCommands });
   outro(`Installed ${result.filesGenerated} commands to .claude/commands`);
 }
 
 // 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/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/gap.md

@@ -0,0 +1,22 @@
+---
+allowed-tools: mcp__beads__list, mcp__beads__ready
+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
+5. **User requests** - Things the user asked for that weren't fully completed
+6. **TODO comments** - Any TODOs mentioned in conversation
+7. **Error handling gaps** - Missing error cases or edge cases
+8. **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/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/gap.md

@@ -0,0 +1,21 @@
+---
+allowed-tools: mcp__beads__list, mcp__beads__ready
+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
+5. **User requests** - Things the user asked for that weren't fully completed
+6. **TODO comments** - Any TODOs mentioned in conversation
+7. **Error handling gaps** - Missing error cases or edge cases
+8. **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -32,6 +32,7 @@
     "build": "bash scripts/build.sh",
     "build:dev": "bash scripts/build-dev.sh",
     "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",