@wbern/claude-instructions 1.20.0 → 2.0.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.20.0",
+  "version": "2.0.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
   "files": [
     "bin",
-    "downloads"
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -27,7 +27,6 @@
   "author": "wbern",
   "license": "MIT",
   "scripts": {
-    "clean": "rm -rf downloads",
     "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",

package/src/README.md

@@ -0,0 +1,279 @@
+# @wbern/claude-instructions
+
+[![npm version](https://img.shields.io/npm/v/@wbern/claude-instructions)](https://www.npmjs.com/package/@wbern/claude-instructions)
+[![npm downloads](https://img.shields.io/npm/dm/@wbern/claude-instructions)](https://www.npmjs.com/package/@wbern/claude-instructions)
+[![CI](https://github.com/wbern/claude-instructions/actions/workflows/release.yml/badge.svg)](https://github.com/wbern/claude-instructions/actions/workflows/release.yml)
+[![codecov](https://codecov.io/gh/wbern/claude-instructions/graph/badge.svg)](https://codecov.io/gh/wbern/claude-instructions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[![Made with Claude Code](https://img.shields.io/badge/Made%20with-Claude%20Code-blueviolet)](https://claude.ai/code)
+[![Contributors](https://img.shields.io/github/contributors/wbern/claude-instructions)](https://github.com/wbern/claude-instructions/graphs/contributors)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/wbern/claude-instructions/pulls)
+<!-- docs COMMANDS_BADGE -->
+<!-- /docs -->
+
+```
+       _==/          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.**
+
+Test-Driven Development (TDD) gives you structure and confidence—a discipline proven by decades of practitioners from Extreme Programming to modern teams. These commands let Claude do the typing while you do the thinking.
+
+## Installation
+
+```bash
+npx @wbern/claude-instructions
+
+// or
+
+pnpm dlx @wbern/claude-instructions
+```
+
+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.
+
+### Adding to Your Repository
+
+To automatically regenerate commands when teammates install dependencies, add it as a dev dependency with a postinstall script:
+
+```bash
+npm install --save-dev @wbern/claude-instructions
+```
+
+Then add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx @wbern/claude-instructions --variant=without-beads --scope=project --prefix="
+  },
+  "devDependencies": {
+    "@wbern/claude-instructions": "^1.0.0"
+  }
+}
+```
+
+This ensures commands are regenerated whenever anyone runs `npm install`, `pnpm install`, or `yarn install`.
+
+**CLI Options:**
+
+<!-- docs CLI_OPTIONS -->
+<!-- /docs -->
+
+## Customizing Commands
+
+You can inject project-specific instructions into generated commands by adding a `<claude-commands-template>` block to your `CLAUDE.md` or `AGENTS.md` file.
+
+### Basic Usage
+
+Add this to your project's `CLAUDE.md`:
+
+```markdown
+# My Project
+
+Other instructions here...
+
+<claude-commands-template>
+## Project-Specific Rules
+
+- Always use pnpm instead of npm
+- Run tests with `pnpm test`
+</claude-commands-template>
+```
+
+When you run `npx @wbern/claude-instructions`, the template content is appended to all generated commands.
+
+### Targeting Specific Commands
+
+Use the `commands` attribute to inject content only into specific commands:
+
+```markdown
+<claude-commands-template commands="commit,ask">
+## Git Conventions
+
+- Use conventional commits format
+- Reference issue numbers in commits
+</claude-commands-template>
+```
+
+This injects the content only into `commit.md` and `ask.md`.
+
+### File Priority
+
+The generator looks for template blocks in this order:
+1. `CLAUDE.md` (checked first)
+2. `AGENTS.md` (fallback)
+
+Only the first file found is used.
+
+## Which Command Should I Use?
+
+### Main Workflow
+
+This is the core TDD workflow. Additional utility commands (worktrees, spikes, etc.) are listed in [Available Commands](#available-commands) below.
+
+```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
+```
+
+## Available Commands
+
+<!-- docs COMMANDS_LIST -->
+<!-- /docs -->
+
+## 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.
+
+```
+/ask
+```
+
+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
+
+<!-- docs EXAMPLE_CONVERSATIONS -->
+<!-- /docs -->
+
+## 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.
+
+FIRST principles and test quality criteria from [TDD Manifesto](https://tddmanifesto.com/).
+
+Example kata from [Cyber-Dojo](https://cyber-dojo.org/).

package/src/fragments/aaa-pattern.md

@@ -0,0 +1,7 @@
+### Test Structure (AAA Pattern)
+
+Structure each test with clear phases:
+
+- **Arrange**: Set up test data and preconditions (keep minimal)
+- **Act**: Execute the single action being tested
+- **Assert**: Verify the expected outcome with specific assertions

package/src/fragments/beads-awareness.md

@@ -0,0 +1 @@
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).

package/src/fragments/beads-integration.md

@@ -0,0 +1,8 @@
+### Beads Integration
+
+Use Beads MCP to:
+- Track work with `bd ready` to find next task
+- Create issues with `bd create "description"`
+- Track dependencies with `bd dep add`
+
+See https://github.com/steveyegge/beads for more information.

package/{downloads/without-beads/commit.md → src/fragments/commit-process.md}

@@ -1,20 +1,3 @@
----
-description: Create a git commit following project standards
-argument-hint: [optional-commit-description]
----
-
-## General Guidelines
-
-### Output Style
-
-- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
-- Write natural, descriptive code without meta-commentary about the development process
-- The code should speak for itself - TDD is the process, not the product
-
-Create a git commit following project standards
-
-Include any of the following info if specified: $ARGUMENTS
-
 ## Commit Message Rules
 
 Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.

package/src/fragments/consistency-check.md

@@ -0,0 +1 @@
+8. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase

package/src/fragments/discovery-phase.md

@@ -0,0 +1,22 @@
+## Discovery Phase
+
+Understand the requirement by asking (use AskUserQuestion if needed):
+
+**Problem Statement**
+- What problem does this solve?
+- Who experiences this problem?
+- What's the current pain point?
+
+**Desired Outcome**
+- What should happen after this is built?
+- How will users interact with it?
+- What does success look like?
+
+**Scope & Constraints**
+- What's in scope vs. out of scope?
+- Any technical constraints?
+- Dependencies on other systems/features?
+
+**Context Check**
+- Search codebase for related features/modules
+- Check for existing test files that might be relevant

package/src/fragments/fallback-arguments-beads.md

@@ -0,0 +1,3 @@
+(If there was no info above, fallback to:
+1. Context of the conversation, if there's an immediate thing
+2. `bd ready` to see what to work on next and start from there)

package/src/fragments/fallback-arguments.md

@@ -0,0 +1 @@
+(If there was no info above, fallback to the context of the conversation)

package/src/fragments/fullwidth-dollar-note.md

@@ -0,0 +1 @@
+**Note for AI**: The example below uses a fullwidth dollar sign (＄, U+FF04) to prevent interpolation in this documentation. When creating actual commands, use the regular `$` character.

package/src/fragments/gap-beads.md

@@ -0,0 +1 @@
+4. **Open issues** - Beads issues that are still open or in progress

package/src/fragments/git-host-detection.md

@@ -0,0 +1,19 @@
+<detect_provider>
+  <check_remote_url>git remote get-url origin</check_remote_url>
+  <identify_host>
+    - github.com → GitHub
+    - gitlab.com → GitLab
+    - bitbucket.org → Bitbucket
+    - Other → Ask user
+  </identify_host>
+</detect_provider>
+<check_available_tools>
+  <list_mcp_servers>Check which git-hosting MCP servers are available (github, gitlab, etc.)</list_mcp_servers>
+  <check_cli>Check if gh/glab CLI is available as fallback</check_cli>
+</check_available_tools>
+<select_tool>
+  <if_single_mcp>If only one relevant MCP available, confirm with user</if_single_mcp>
+  <if_multiple>Let user choose which tool to use</if_multiple>
+  <if_told_earlier>If user specified tool earlier in conversation, use that without asking again</if_told_earlier>
+  <store_as>$GIT_HOST_TOOL (e.g., "github_mcp", "gitlab_mcp", "gh_cli")</store_as>
+</select_tool>

package/src/fragments/github-issue-fetch.md

@@ -0,0 +1,10 @@
+Try to fetch the issue using GitHub MCP (mcp__github__issue_read tool).
+
+If GitHub MCP is not configured, show:
+```
+GitHub MCP not configured!
+See: https://github.com/modelcontextprotocol/servers/tree/main/src/github
+Trying GitHub CLI fallback...
+```
+
+Then try using `gh issue view [ISSUE_NUMBER] --json` as fallback.

package/src/fragments/peeping-tom-warning.md

@@ -0,0 +1,9 @@
+### Watch for Brittle Tests
+
+When refactoring implementation, watch for **Peeping Tom** tests that:
+
+- Test private methods or internal state directly
+- Assert on implementation details rather than behavior
+- Break on any refactoring even when behavior is preserved
+
+If tests fail after a pure refactoring (no behavior change), consider whether the tests are testing implementation rather than behavior.

package/src/fragments/plan-beads-context-hint.md

@@ -0,0 +1 @@
+ or run `bd ready` to see existing work

package/src/fragments/plan-beads-details.md

@@ -0,0 +1,49 @@
+### Create Beads Issues
+
+For each task, create a bd issue with:
+
+```bash
+bd create "Task title" \
+  --type [feature|bug|task|chore] \
+  --priority [1-3] \
+  --description "Context and what needs to be built" \
+  --design "Technical approach, architecture notes" \
+  --acceptance "Given-When-Then acceptance criteria"
+```
+
+**Issue Structure Best Practices:**
+
+**Title**: Action-oriented, specific
+- ✅ "Add JWT token validation middleware"
+- ❌ "Authentication stuff"
+
+**Description**: Provide context
+- Why this task exists
+- How it fits into the larger feature
+- Links to related issues/docs
+
+**Design**: Technical approach
+- Key interfaces/types needed
+- Algorithm or approach
+- Libraries or patterns to use
+- Known gotchas or considerations
+
+**Acceptance Criteria**: Test-ready scenarios
+- Given-When-Then format
+- Concrete, verifiable conditions
+- Cover main case + edge cases
+- Map 1:1 to future tests
+
+**Dependencies**: Link related issues
+```bash
+bd dep add ISSUE-123 ISSUE-456 --type blocks
+```
+
+### Validation
+
+After creating issues, verify:
+- ✅ Each issue has clear acceptance criteria
+- ✅ Dependencies are mapped (use `bd dep add`)
+- ✅ Issues are ordered by implementation sequence
+- ✅ First few issues are ready to start (`bd ready` shows them)
+- ✅ Each issue is small enough for TDD (if too big, break down more)

package/src/fragments/plan-beads-integration.md

@@ -0,0 +1,2 @@
+- **During work**: Use `bd update` to add notes/findings back to issues
+- **When stuck**: Check `bd show ISSUE-ID` to review acceptance criteria

package/src/fragments/summarize-beads.md

@@ -0,0 +1,8 @@
+## Beads Integration
+
+If Beads MCP is available, check for task tracking status and ask if the user wants to:
+1. Review current task status
+2. Update task states based on conversation progress
+3. Include Beads context in the summary
+
+Use AskUserQuestion to confirm Beads integration preferences.

package/{downloads/without-beads/summarize.md → src/fragments/summarize-structure.md}

@@ -1,38 +1,18 @@
----
-description: Summarize conversation progress and next steps
-argument-hint: [optional additional info]
----
-
-## General Guidelines
-
-### Output Style
-
-- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
-- Write natural, descriptive code without meta-commentary about the development process
-- The code should speak for itself - TDD is the process, not the product
-
-Create a concise summary of the current conversation suitable for transferring context to a new conversation.
-
-Additional info: $ARGUMENTS
-
 ## Summary Structure
 
 Provide a summary with these sections:
 
 ### What We Did
-
 - Key accomplishments and changes made
 - Important decisions or discoveries
 - Files created, modified, or analyzed
 
 ### What We're Doing Next
-
 - Immediate next steps
 - Pending tasks or work in progress
 - Goals or objectives to continue
 
 ### Blockers & User Input Needed
-
 - Any issues requiring user intervention
 - Decisions that need to be made
 - Missing information or clarifications needed

package/{downloads/without-beads/tdd.md → src/fragments/tdd-fundamentals.md}

@@ -1,18 +1,3 @@
----
-description: Remind agent about TDD approach and continue conversation
-argument-hint: [optional-response-to-last-message]
----
-
-# TDD Reminder
-
-## General Guidelines
-
-### Output Style
-
-- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
-- Write natural, descriptive code without meta-commentary about the development process
-- The code should speak for itself - TDD is the process, not the product
-
 ## TDD Fundamentals
 
 ### The TDD Cycle
@@ -84,9 +69,3 @@ This phase is **not part of the regular TDD workflow** and must only be applied
 - In the refactor phase, it is perfectly fine to refactor both test and implementation code. That said, completely new functionality is not allowed. Types, clean up, abstractions, and helpers are allowed as long as they do not introduce new behavior.
 - Adding types, interfaces, or a constant in order to replace magic values is perfectly fine during refactoring.
 - Provide the agent with helpful directions so that they do not get stuck when blocking them.
-
-## Continue Conversation
-
-User response to the last message: $ARGUMENTS
-
-Please continue with TDD approach based on the above response.

package/src/fragments/test-quality-criteria.md

@@ -0,0 +1,24 @@
+#### FIRST Principles
+
+| Principle | What to Check |
+|-----------|---------------|
+| **Fast** | Tests complete quickly, no I/O, no network calls, no sleep()/setTimeout delays |
+| **Independent** | No shared mutable state, no execution order dependencies between tests |
+| **Repeatable** | No Date.now(), no Math.random() without seeding, no external service dependencies |
+| **Self-validating** | Meaningful assertions that verify behavior, no manual verification needed |
+
+#### TDD Anti-patterns
+
+| Anti-pattern | Detection Signals |
+|--------------|-------------------|
+| **The Liar** | `expect(true).toBe(true)`, empty test bodies, tests with no assertions |
+| **Excessive Setup** | >20 lines of arrange code, >5 mocks, deep nested object construction |
+| **The One** | >5 assertions testing unrelated behaviors in a single test |
+| **The Peeping Tom** | Testing private methods, asserting on internal state, tests that break on any refactor |
+| **The Slow Poke** | Real database/network calls, file I/O, hard-coded timeouts |
+
+#### Test Structure (AAA Pattern)
+
+- **Arrange**: Clear setup with minimal fixtures
+- **Act**: Single action being tested
+- **Assert**: Specific, behavior-focused assertions

package/src/fragments/universal-guidelines.md

@@ -0,0 +1,6 @@
+## General Guidelines
+
+### Output Style
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product