@wbern/claude-instructions 1.18.1 → 1.20.0

package/README.md

@@ -9,7 +9,7 @@
 [![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)
-[![Commands](https://img.shields.io/badge/commands-22-blue)](https://github.com/wbern/claude-instructions#available-commands)
+[![Commands](https://img.shields.io/badge/commands-23-blue)](https://github.com/wbern/claude-instructions#available-commands)
 
 ```
        _==/          i     i          \==_
@@ -80,6 +80,8 @@ This ensures commands are regenerated whenever anyone runs `npm install`, `pnpm
 | `--update-existing` | Only update already-installed commands |
 | `--overwrite` | Overwrite conflicting files without prompting |
 | `--skip-on-conflict` | Skip conflicting files without prompting |
+| `--help, -h` | Show help message |
+| `--version, -v` | Show version number |
 
 ## Customizing Commands
 
@@ -214,6 +216,7 @@ flowchart TB
 - `/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
+- `/tdd-review` - Review test suite quality against FIRST principles and TDD anti-patterns
 
 ### Workflow
 
@@ -475,3 +478,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, build system, a
 ## 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/bin/cli.js

@@ -113,6 +113,7 @@ var require_picocolors = __commonJS({
 
 // scripts/bin.ts
 init_esm_shims();
+import { createRequire } from "module";
 
 // scripts/cli.ts
 init_esm_shims();
@@ -790,6 +791,7 @@ function generateHelpText() {
     );
   }
   lines.push("  --help, -h                  Show this help message");
+  lines.push("  --version, -v               Show version number");
   return lines.join("\n");
 }
 
@@ -1119,6 +1121,11 @@ Happy TDD'ing!`
 }
 
 // scripts/bin.ts
+function getVersion() {
+  const require2 = createRequire(import.meta.url);
+  const packageJson = require2("../package.json");
+  return packageJson.version;
+}
 function parseArgs(argv) {
   const args = {};
   const booleanOpts = CLI_OPTIONS.filter((o) => o.type === "boolean");
@@ -1150,6 +1157,10 @@ async function run(argv) {
     console.log(generateHelpText());
     return;
   }
+  if (argv.includes("--version") || argv.includes("-v")) {
+    console.log(getVersion());
+    return;
+  }
   const args = parseArgs(argv);
   await main(args);
 }

package/downloads/with-beads/code-review.md

@@ -163,9 +163,30 @@ For each detected category with changes, run a targeted review. Skip categories
 
 ### Tests Review Criteria
 
-- Coverage: Edge cases, error paths, boundaries
-- Assertion quality: Specific assertions, not just "no error"
-- Flaky patterns: Timing dependencies, order dependencies, shared state
+#### 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
 
 ### Docs Review Criteria
 

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

@@ -128,6 +128,12 @@
     "category": "Workflow",
     "order": 10
   },
+  "tdd-review.md": {
+    "description": "Review test suite quality against FIRST principles and TDD anti-patterns",
+    "hint": "Review tests",
+    "category": "Test-Driven Development",
+    "order": 45
+  },
   "tdd.md": {
     "description": "Remind agent about TDD approach and continue conversation",
     "hint": "TDD reminder",

package/downloads/with-beads/red.md

@@ -93,3 +93,11 @@ 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.
+
+### 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/downloads/with-beads/refactor.md

@@ -92,4 +92,14 @@ This phase is **not part of the regular TDD workflow** and must only be applied
 - 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.
 
+### 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.
+
 1. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase

package/downloads/with-beads/tdd-review.md

@@ -0,0 +1,102 @@
+---
+description: Review test suite quality against FIRST principles and TDD anti-patterns
+argument-hint: [optional test file or directory path]
+---
+
+## 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
+
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
+
+(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)
+
+# Test Quality Review
+
+Analyze test files against FIRST principles and TDD best practices.
+
+## Phase 1: Scope
+
+| Input | Action |
+|-------|--------|
+| No argument | Find all test files in project |
+| File path | Analyze specific test file |
+| Directory | Analyze tests in directory |
+
+Detect test files using common patterns: `*.test.*`, `*.spec.*`, `*.stories.*`, `__tests__/**`
+
+Also check for framework-specific patterns based on the project's languages and tools (e.g., `*_test.go`, `*_test.py`, `Test*.java`, `*.feature` for BDD).
+
+## Phase 2: Analysis
+
+For each test file, check against these criteria:
+
+### Quality Criteria
+
+#### 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
+
+## Phase 3: Report
+
+Output a structured report:
+
+```
+## Test Quality Report
+
+### Summary
+- Files analyzed: N
+- Tests found: N
+- Issues found: N (X blockers, Y warnings)
+
+### By File
+
+#### path/to/file.test.ts
+
+| Line | Issue | Severity | Description |
+|------|-------|----------|-------------|
+| 15 | The Liar | blocker | Test has no assertions |
+| 42 | Slow Poke | warning | Uses setTimeout(500) |
+
+### Recommendations
+- [ ] Fix blockers before merge
+- [ ] Consider refactoring tests with excessive setup
+```
+
+### Severity Levels
+
+- **blocker**: Must fix - test provides false confidence (The Liar, no assertions)
+- **warning**: Should fix - test quality issue (Slow Poke, Excessive Setup)
+- **info**: Consider - style or structure suggestion (AAA pattern)
+
+---
+
+Test path (leave empty for all tests): $ARGUMENTS

package/downloads/without-beads/code-review.md

@@ -161,9 +161,30 @@ For each detected category with changes, run a targeted review. Skip categories
 
 ### Tests Review Criteria
 
-- Coverage: Edge cases, error paths, boundaries
-- Assertion quality: Specific assertions, not just "no error"
-- Flaky patterns: Timing dependencies, order dependencies, shared state
+#### 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
 
 ### Docs Review Criteria
 

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

@@ -128,6 +128,12 @@
     "category": "Workflow",
     "order": 10
   },
+  "tdd-review.md": {
+    "description": "Review test suite quality against FIRST principles and TDD anti-patterns",
+    "hint": "Review tests",
+    "category": "Test-Driven Development",
+    "order": 45
+  },
   "tdd.md": {
     "description": "Remind agent about TDD approach and continue conversation",
     "hint": "TDD reminder",

package/downloads/without-beads/red.md

@@ -88,3 +88,11 @@ 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.
+
+### 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/downloads/without-beads/refactor.md

@@ -87,4 +87,14 @@ This phase is **not part of the regular TDD workflow** and must only be applied
 - 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.
 
+### 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.
+
 1. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase

package/downloads/without-beads/tdd-review.md

@@ -0,0 +1,97 @@
+---
+description: Review test suite quality against FIRST principles and TDD anti-patterns
+argument-hint: [optional test file or directory path]
+---
+
+## 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
+
+(If there was no info above, fallback to the context of the conversation)
+
+# Test Quality Review
+
+Analyze test files against FIRST principles and TDD best practices.
+
+## Phase 1: Scope
+
+| Input | Action |
+|-------|--------|
+| No argument | Find all test files in project |
+| File path | Analyze specific test file |
+| Directory | Analyze tests in directory |
+
+Detect test files using common patterns: `*.test.*`, `*.spec.*`, `*.stories.*`, `__tests__/**`
+
+Also check for framework-specific patterns based on the project's languages and tools (e.g., `*_test.go`, `*_test.py`, `Test*.java`, `*.feature` for BDD).
+
+## Phase 2: Analysis
+
+For each test file, check against these criteria:
+
+### Quality Criteria
+
+#### 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
+
+## Phase 3: Report
+
+Output a structured report:
+
+```
+## Test Quality Report
+
+### Summary
+- Files analyzed: N
+- Tests found: N
+- Issues found: N (X blockers, Y warnings)
+
+### By File
+
+#### path/to/file.test.ts
+
+| Line | Issue | Severity | Description |
+|------|-------|----------|-------------|
+| 15 | The Liar | blocker | Test has no assertions |
+| 42 | Slow Poke | warning | Uses setTimeout(500) |
+
+### Recommendations
+- [ ] Fix blockers before merge
+- [ ] Consider refactoring tests with excessive setup
+```
+
+### Severity Levels
+
+- **blocker**: Must fix - test provides false confidence (The Liar, no assertions)
+- **warning**: Should fix - test quality issue (Slow Poke, Excessive Setup)
+- **info**: Consider - style or structure suggestion (AAA pattern)
+
+---
+
+Test path (leave empty for all tests): $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -53,6 +53,7 @@
     "jscpd": "^4.0.5",
     "knip": "^5.70.2",
     "lint-staged": "^16.2.7",
+    "markdownlint": "^0.40.0",
     "markdownlint-cli": "^0.46.0",
     "picocolors": "^1.1.1",
     "prettier": "^3.7.2",