@wbern/claude-instructions 1.0.1

package/README.md

@@ -0,0 +1,411 @@
+# @wbern/claude-instructions
+
+```
+       _==/          i     i          \==_
+     /XX/            |\___/|            \XX\
+   /XXXX\            |XXXXX|            /XXXX\
+  |XXXXXX\_         _XXXXXXX_         _/XXXXXX|
+ XXXXXXXXXXXxxxxxxxXXXXXXXXXXXxxxxxxxXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+ XXXXXX/^^^^"\XXXXXXXXXXXXXXXXXXXXX/^^^^^\XXXXXX
+  |XXX|       \XXX/^^\XXXXX/^^\XXX/       |XXX|
+    \XX\       \X/    \XXX/    \X/       /XX/
+       "\       "      \X/      "       /"
+```
+
+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.
+
+After installation, restart Claude Code if it's currently running.
+
+## Which Command Should I Use?
+
+### Main Workflow
+
+Follow this workflow from planning to shipping:
+
+```mermaid
+flowchart TB
+    Start([Start New Work])
+
+    Start --> Step1[<b>1. PLAN</b>]
+
+    Step1 --> Issue[📋 /issue<br/>Have GitHub issue<br/><i>Requires: GitHub MCP</i>]
+    Step1 --> Plan[📝 /plan<br/>No issue yet<br/><i>Optional: Beads MCP</i>]
+
+    Issue --> Step2[<b>2. CODE with TDD</b>]
+    Plan --> Step2
+
+    Step2 -->|Manual| Red[🔴 /red<br/>Write failing test]
+    Red --> Green[🟢 /green<br/>Make it pass]
+    Green --> Refactor[🔵 /refactor<br/>Clean up code]
+    Refactor --> MoreTests{More tests?}
+
+    Step2 -->|Automated| Cycle[🔄 /cycle<br/>Runs red+green+refactor]
+    Cycle --> MoreTests
+
+    MoreTests -->|Yes| Step2
+    MoreTests -->|No| Step3
+
+    Step3[<b>3. SHIP</b>]
+
+    Step3 --> Commit[📦 /commit<br/>Create commit]
+    Commit --> ShipChoice{How to<br/>merge?}
+
+    ShipChoice -->|Simple change| Ship[🚢 /ship<br/>Direct to main<br/><i>Requires: GitHub MCP</i>]
+    ShipChoice -->|Show team| Show[👀 /show<br/>Auto-merge + notify<br/><i>Requires: GitHub MCP</i>]
+    ShipChoice -->|Needs review| Ask[💬 /ask<br/>Create PR<br/><i>Requires: GitHub MCP</i>]
+
+    Ship --> Done([✅ Done])
+    Show --> Done
+    Ask --> Done
+
+    style Start fill:#e1f5ff
+    style Step1 fill:#fff4e6
+    style Step2 fill:#e8f5e9
+    style Step3 fill:#fce4ec
+    style Done fill:#c8e6c9
+```
+
+### Other Commands
+
+Available anytime during your workflow:
+
+```mermaid
+flowchart TB
+    Utils[<b>UTILITIES</b>]
+    Utils --> Spike[🔬 /spike<br/>Exploratory coding before TDD]
+    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 --> Beepboop[🤖 /beepboop<br/>AI attribution]
+
+    Worktree[<b>WORKTREE MANAGEMENT</b>]
+    Worktree --> WorktreeAdd[➕ /worktree-add<br/>Create new worktree<br/><i>Requires: GitHub MCP</i>]
+    Worktree --> WorktreeCleanup[🧹 /worktree-cleanup<br/>Clean up merged worktrees<br/><i>Requires: GitHub MCP</i>]
+
+    style Utils fill:#fff9c4
+    style Worktree fill:#f3e5f5
+```
+
+## Available Commands
+
+### Planning
+
+- `/issue` - Analyze GitHub issue and create TDD implementation plan
+- `/plan` - Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria
+
+### TDD Cycle
+
+- `/spike` - Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
+- `/red` - Execute TDD Red Phase - write ONE failing test
+- `/green` - Execute TDD Green Phase - write minimal implementation to pass the failing test
+- `/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
+- `/ship` - Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)
+- `/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
+
+### 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-cleanup` - Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees
+
+### Utilities
+
+- `/tdd` - Remind agent about TDD approach and continue conversation
+- `/beepboop` - Communicate AI-generated content with transparent attribution
+- `/add-command` - Guide for creating new slash commands
+
+## Getting Started
+
+### Quick Start: Your First TDD Cycle
+
+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
+
+Claude: I'll write a failing test for email validation.
+[Creates test file with a test that checks email validation]
+[Runs test - shows it failing because function doesn't exist yet]
+```
+
+**2. Make it pass (`/green`)**
+```
+You: /green
+
+Claude: I'll implement the minimal code to pass the test.
+[Creates the email validation function with basic implementation]
+[Runs test - shows it passing]
+```
+
+**3. Refactor for quality (`/refactor`)**
+```
+You: /refactor extract regex pattern to a constant
+
+Claude: I'll refactor while keeping tests green.
+[Extracts magic values, improves code structure]
+[Runs tests - confirms they still pass]
+```
+
+### 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
+/refactor move password verification to separate function
+```
+
+**Committing and creating PRs:**
+```
+/commit
+```
+Claude reviews changes, drafts a commit message following project standards, and creates the commit.
+
+```
+/pr
+```
+Claude analyzes commits, creates a PR with summary and test plan.
+
+### What to Expect
+
+- **`/red`** - Claude writes ONE failing test based on your description
+- **`/green`** - Claude writes minimal implementation to pass the current failing test
+- **`/refactor`** - Claude improves code structure without changing behavior
+- **`/cycle`** - Claude runs all three phases in sequence for a complete feature
+
+The commands enforce TDD discipline: you can't refactor with failing tests, can't write multiple tests at once, and implementation must match test requirements.
+
+## Example Conversations
+
+# Conversation: Solving "Find Closest to Zero" Code Challenge
+
+**Summary:** User works through solving a code challenge: given a list of integers, find the closest to zero. If there is a tie, choose the positive value. (challenge from [cyber-dojo.org](https://cyber-dojo.org))
+
+**Commands:** `/red` `/green` `/refactor`
+**Legend:** 🔴 Red (test fails) | 🟢 Green (test passes) | 🔵 Refactor (cleanup)
+
+---
+
+👤 `/red` single element [1] returns 1
+
+🔴 *writes test*
+```typescript
+expect(closestToZero([1])).toBe(1);
+```
+FAIL: closestToZero is not defined
+
+👤 `/green`
+
+🟢 *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*
+```typescript
+expect(closestToZero([3, 2])).toBe(2);
+```
+FAIL: expected 1 to be 2
+
+👤 `/green`
+
+🟢 *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*
+```typescript
+expect(closestToZero([-3, 2])).toBe(2);
+```
+FAIL: expected -3 to be 2 (regular sort puts -3 first)
+
+👤 `/green`
+
+🟢 *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*
+```typescript
+expect(closestToZero([-2, 2])).toBe(2);
+```
+FAIL: expected -2 to be 2 (returns first when tied)
+
+👤 `/green`
+
+🟢 *adds tie-breaking: prefer positive*
+```typescript
+function closestToZero(nums: number[]): number {
+  return nums.sort((a, b) => {
+    const diff = Math.abs(a) - Math.abs(b);
+    return diff !== 0 ? diff : b - a;
+  })[0];
+}
+```
+✅ 4/4 tests pass
+
+👤 `/refactor` extract helper and use iteration instead of sort
+
+🔵 *extracts helper function for comparison logic*
+```typescript
+function isCloser(candidate: number, current: number): boolean {
+  const candAbs = Math.abs(candidate);
+  const currAbs = Math.abs(current);
+  return candAbs < currAbs || (candAbs === currAbs && candidate > current);
+}
+
+function closestToZero(nums: number[]): number {
+  if (nums.length === 0) return 0;
+  let closest = nums[0];
+  for (const num of nums) {
+    if (isCloser(num, closest)) {
+      closest = num;
+    }
+  }
+  return closest;
+}
+```
+✅ 4/4 tests still pass
+
+👤 `/refactor`
+
+🔵 *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
+  );
+}
+```
+✅ 4/4 tests still pass
+
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, build system, and fragment management.
+
+## Credits
+
+TDD workflow instructions adapted from [TDD Guard](https://github.com/nizos/tdd-guard) by Nizar.

package/bin/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// scripts/cli.ts
+import { select, isCancel, intro, outro } from "@clack/prompts";
+
+// scripts/cli-generator.ts
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+import os from "os";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var VARIANTS = {
+  WITH_BEADS: "with-beads",
+  WITHOUT_BEADS: "without-beads"
+};
+var SCOPES = {
+  PROJECT: "project",
+  USER: "user"
+};
+var DIRECTORIES = {
+  CLAUDE: ".claude",
+  COMMANDS: "commands",
+  DOWNLOADS: "downloads"
+};
+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)" }
+];
+function getDestinationPath(outputPath, scope) {
+  if (outputPath) {
+    return outputPath;
+  }
+  if (scope === SCOPES.PROJECT) {
+    return path.join(process.cwd(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+  }
+  if (scope === SCOPES.USER) {
+    return path.join(os.homedir(), DIRECTORIES.CLAUDE, DIRECTORIES.COMMANDS);
+  }
+  return void 0;
+}
+async function generateToDirectory(outputPath, variant, scope) {
+  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, {});
+  return {
+    success: true,
+    filesGenerated: files.length,
+    variant
+  };
+}
+
+// scripts/cli.ts
+var BATMAN_LOGO = `
+       _==/          i     i          \\==_
+     /XX/            |\\___/|            \\XX\\
+   /XXXX\\            |XXXXX|            /XXXX\\
+  |XXXXXX\\_         _XXXXXXX_         _/XXXXXX|
+ XXXXXXXXXXXxxxxxxxXXXXXXXXXXXxxxxxxxXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
+ XXXXXX/^^^^"\\XXXXXXXXXXXXXXXXXXXXX/^^^^^\\XXXXXX
+  |XXX|       \\XXX/^^\\XXXXX/^^\\XXX/       |XXX|
+    \\XX\\       \\X/    \\XXX/    \\X/       /XX/
+       "\\       "      \\X/      "       /"
+
+            @wbern/claude-instructions
+`;
+async function main() {
+  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;
+  }
+  const result = await generateToDirectory(void 0, variant, scope);
+  outro(`Installed ${result.filesGenerated} commands to .claude/commands`);
+}
+
+// scripts/bin.ts
+main().catch(console.error);

package/downloads/with-beads/add-command.md

@@ -0,0 +1,130 @@
+---
+description: Guide for creating new slash commands
+argument-hint: <command-name> <description>
+---
+
+# Slash Command Creator Guide
+
+## How This Command Works
+The `/add-command` command shows this guide for creating new slash commands. It includes:
+- Command structure and syntax
+- Common patterns and examples
+- Security restrictions and limitations
+- Frontmatter options
+
+**Note for AI**: When creating commands, you CAN use bash tools like `Bash(mkdir:*)`, `Bash(ls:*)`, `Bash(git status:*)` in the `allowed-tools` frontmatter of NEW commands - but ONLY for operations within the current project directory. This command itself doesn't need bash tools since it's just documentation.
+
+## Command Locations
+- **Personal**: `~/.claude/commands/` (available across all projects)
+- **Project**: `.claude/commands/` (shared with team, shows "(project)")
+
+## Basic Structure
+
+```markdown
+---
+allowed-tools: Read, Glob, Grep, Bash(git status:*), Task
+description: Brief description of what this command does
+argument-hint: [required-arg] [optional-arg]
+---
+
+# Command Title
+
+Your command instructions here.
+
+Arguments: $ARGUMENTS
+
+File reference: @path/to/file.js
+
+Bash command output: (exclamation)git status(backticks)
+```
+
+## ⚠️ Security Restrictions
+
+**Bash Commands (exclamation prefix)**: Limited to current working directory only.
+- ✅ Works: `! + backtick + git status + backtick` (in project dir)
+- ❌ Blocked: `! + backtick + ls /outside/project + backtick` (outside project)  
+- ❌ Blocked: `! + backtick + pwd + backtick` (if referencing dirs outside project)
+
+**File References (`@` prefix)**: No directory restrictions.
+- ✅ Works: `@/path/to/system/file.md`
+- ✅ Works: `@../other-project/file.js`
+
+## Common Patterns
+
+### Simple Command
+```bash
+echo "Review this code for bugs and suggest fixes" > ~/.claude/commands/review.md
+```
+
+### Command with Arguments
+```markdown
+Fix issue #$ARGUMENTS following our coding standards
+```
+
+### Command with File References
+```markdown
+Compare @src/old.js with @src/new.js and explain differences
+```
+
+### Command with Bash Output (Project Directory Only)
+```markdown
+---
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*)
+---
+Current status: (!)git status(`)
+Current branch: (!)git branch --show-current(`)
+Recent commits: (!)git log --oneline -5(`)
+
+Create commit for these changes.
+```
+
+**Note**: Only works with commands in the current project directory.
+
+### Namespaced Command
+```bash
+mkdir -p ~/.claude/commands/ai
+echo "Ask GPT-5 about: $ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
+# Creates: /ai:gpt5
+```
+
+## Frontmatter Options
+- `allowed-tools`: Tools this command can use
+  - **Important**: Intrusive tools like `Write`, `Edit`, `NotebookEdit` should NEVER be allowed in commands unless the user explicitly requests them. These tools modify files and should only be used when the command's purpose is to make changes.
+  - ✅ Safe for most commands: `Read`, `Glob`, `Grep`, `Bash(git status:*)`, `Task`, `AskUserQuestion`
+- `description`: Brief description (shows in /help)
+- `argument-hint`: Help text for arguments
+- `model`: Specific model to use
+
+## Best Practices
+
+### Safe Commands (No Security Issues)
+```markdown
+# System prompt editor (file reference only)  
+(@)path/to/system/prompt.md
+
+Edit your system prompt above.
+```
+
+### Project-Specific Commands (Bash OK)
+```markdown
+---
+allowed-tools: Bash(git status:*), Bash(npm list:*)
+---
+Current git status: (!)git status(`)
+Package info: (!)npm list --depth=0(`)
+
+Review project state and suggest next steps.
+```
+
+### Cross-Directory File Access (Use @ not !)
+```markdown
+# Compare config files
+Compare (@)path/to/system.md with (@)project/config.md
+
+Show differences and suggest improvements.
+```
+
+## Usage
+After creating: `/<command-name> [arguments]`
+
+Example: `/review` or `/ai:gpt5 "explain this code"`