@wbern/claude-instructions 2.4.1 → 2.6.0

package/README.md

@@ -1,3 +1,8 @@
+<!--
+  ⚠️ DO NOT EDIT THIS FILE DIRECTLY
+  Edit src/README.md instead - this file is auto-generated by pnpm build
+-->
+
 # @wbern/claude-instructions
 
 [![npm version](https://img.shields.io/npm/v/@wbern/claude-instructions)](https://www.npmjs.com/package/@wbern/claude-instructions)
@@ -9,7 +14,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-23-blue)](https://github.com/wbern/claude-instructions#available-commands)
+[![Commands](https://img.shields.io/badge/commands-26-blue)](https://github.com/wbern/claude-instructions#available-commands)
 
 ```
        _==/          i     i          \==_
@@ -28,7 +33,13 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 **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.
+Claude Code supports [custom slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)—type `/foo` and Claude receives the contents of `foo.md` as instructions (from `.claude/commands/` in your repo or `~/.claude/commands/` in your home directory). This repo provides ready-made commands for Test-Driven Development workflows.
+
+While custom commands themselves is really just a glorified method of copy-paste, the way they can be used to bring stability to software development is what's worth trying out.
+
+Instead of explaining TDD principles each session, type `/red` to write a failing test, `/green` to make it pass, `/refactor` to clean up. The commands guide Claude through each step methodically—you focus on what to build, Claude handles the how.
+
+Also included are commands for commits, PRs, code reviews, and other tasks that come up during day-to-day development.
 
 ## Installation
 
@@ -63,7 +74,7 @@ Then add a postinstall script to your `package.json`:
     "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
-    "@wbern/claude-instructions": "^1.0.0"
+    "@wbern/claude-instructions": "^2.6.0"
   }
 }
 ```
@@ -191,6 +202,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
+- `/simplify` - Reduce code complexity while keeping tests green
 - `/tdd-review` - Review test suite quality against FIRST principles and TDD anti-patterns
 
 ### Workflow
@@ -200,6 +212,7 @@ flowchart TB
 - `/pr` - Creates a pull request using GitHub MCP
 - `/summarize` - Summarize conversation progress and next steps
 - `/gap` - Analyze conversation context for unaddressed items and gaps
+- `/forever` - Run autonomously until stopped or stuck
 - `/code-review` - Code review using dynamic category detection and domain-specific analysis
 
 ### Ship / Show / Ask
@@ -218,6 +231,7 @@ flowchart TB
 - `/beepboop` - Communicate AI-generated content with transparent attribution
 - `/add-command` - Guide for creating new slash commands
 - `/kata` - Generate a TDD practice challenge with boilerplate test setup
+- `/research` - Research a problem in parallel via web docs, web search, codebase exploration, and deep ultrathink
 
 ## Getting Started
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",

package/src/README.md

@@ -29,7 +29,13 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 **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.
+Claude Code supports [custom slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)—type `/foo` and Claude receives the contents of `foo.md` as instructions (from `.claude/commands/` in your repo or `~/.claude/commands/` in your home directory). This repo provides ready-made commands for Test-Driven Development workflows.
+
+While custom commands themselves is really just a glorified method of copy-paste, the way they can be used to bring stability to software development is what's worth trying out.
+
+Instead of explaining TDD principles each session, type `/red` to write a failing test, `/green` to make it pass, `/refactor` to clean up. The commands guide Claude through each step methodically—you focus on what to build, Claude handles the how.
+
+Also included are commands for commits, PRs, code reviews, and other tasks that come up during day-to-day development.
 
 ## Installation
 
@@ -64,7 +70,7 @@ Then add a postinstall script to your `package.json`:
     "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
-    "@wbern/claude-instructions": "^1.0.0"
+    "@wbern/claude-instructions": "^<!-- docs VERSION --><!-- /docs -->"
   }
 }
 ```

package/src/fragments/complexity-signals.md

@@ -0,0 +1,11 @@
+## Code Complexity Signals
+
+Look for these refactoring opportunities:
+
+- [ ] Nesting > 3 levels deep
+- [ ] Functions > 20 lines
+- [ ] Duplicate code blocks
+- [ ] Abstractions with single implementation
+- [ ] "Just in case" parameters or config
+- [ ] Magic values without names
+- [ ] Dead/unused code

package/src/sources/forever.md

@@ -0,0 +1,91 @@
+---
+description: Run autonomously until stopped or stuck
+argument-hint: [optional: initial task or focus area]
+_hint: Autonomous mode
+_category: Workflow
+_order: 20
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+# Forever Mode: $ARGUMENTS
+
+Run autonomously, finding and completing work until interrupted or truly stuck.
+
+## Operating Loop
+
+Execute this cycle continuously:
+
+### 1. Find Work
+
+Check in order until something is found:
+
+1. **Arguments above** - If provided, start there
+2. **Conversation context** - Any unfinished discussion
+3. **Gaps** - Incomplete implementations or missing tests
+4. **Git status** - Uncommitted changes to address
+5. **Think** - If nothing else, consider: What would improve this codebase?
+
+### 2. Execute Work
+
+- Make atomic, committable progress
+- Leave clear trail via commits
+
+### 3. Continue or Pivot
+
+After completing a unit of work:
+
+- If more related work exists - continue
+- If blocked - note blocker, find different work
+- If genuinely nothing to do - report status and wait
+
+**Do not stop unless:**
+
+- User interrupts (Escape)
+- Genuinely no work can be identified
+- A decision requires human judgment (ambiguous requirements, architectural choices)
+
+## Anti-Stuck Tactics
+
+When progress stalls:
+
+| Situation | Action |
+|-----------|--------|
+| Test failures | Make the failing tests pass |
+| Unclear requirements | Make reasonable assumption, document it, proceed |
+| Build errors | Fix incrementally, commit fixes |
+| Context confusion | Re-read recent commits and task tracker to reorient |
+| Repeated failures | Try different approach, or move to different task |
+
+## Work Discovery Heuristics
+
+When thinking about what to do:
+
+- Tests that could be added (coverage gaps)
+- Code that could be simplified
+- Documentation that's missing or stale
+- TODOs or FIXMEs in code
+- Dependencies that could be updated
+- Performance improvements
+- Refactoring opportunities
+
+## Session Continuity
+
+Every few completed tasks:
+
+- Update task tracker with progress notes
+- Commit work in progress
+- Brief self-summary of what's been done
+
+This ensures work survives context limits.
+
+## Communication Style
+
+- Work silently - don't narrate every step
+- Report meaningful completions (commits, closed issues)
+- Surface decisions that need human input
+- Keep responses concise to preserve context

package/src/sources/refactor.md

@@ -23,6 +23,9 @@ Apply this document (specifically the Refactor phase), to the info given by user
 <!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
 <!-- /docs -->
 
+<!-- docs INCLUDE path='src/fragments/complexity-signals.md' -->
+<!-- /docs -->
+
 <!-- docs INCLUDE path='src/fragments/peeping-tom-warning.md' -->
 <!-- /docs -->
 

package/src/sources/research.md

@@ -0,0 +1,83 @@
+---
+description: Research a problem in parallel via web docs, web search, codebase exploration, and deep ultrathink
+argument-hint: <research topic or question>
+_hint: Deep research
+_category: Utilities
+_order: 20
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+# Research: $ARGUMENTS
+
+Research the following problem or question thoroughly, like a senior developer would.
+
+## Step 1: Launch Parallel Research Agents
+
+Use the Task tool to spawn these subagents **in parallel** (all in a single message):
+
+1. **Web Documentation Agent** (subagent_type: general-purpose)
+   - Search official documentation for the topic
+   - Find best practices and recommended patterns
+   - Locate relevant GitHub issues or discussions
+
+2. **Web Search Agent** (subagent_type: general-purpose)
+   - Perform broad web searches for solutions and discussions
+   - Find Stack Overflow answers, blog posts, and tutorials
+   - Note common pitfalls and gotchas
+
+3. **Codebase Explorer Agent** (subagent_type: Explore)
+   - Search the codebase for related patterns
+   - Find existing solutions to similar problems
+   - Identify relevant files, functions, or components
+
+## Step 2: Library Documentation (Optional)
+
+If the research involves specific frameworks or libraries:
+- Use Context7 MCP tools (mcp__context7__resolve-library-id, then get-library-docs)
+- Get up-to-date API references and code examples
+- If Context7 is unavailable, note this in findings so user knows library docs were harder to obtain
+
+## Step 3: Deep Analysis
+
+With all gathered context, perform extended reasoning (ultrathink) to:
+- Analyze the problem from first principles
+- Consider edge cases and trade-offs
+- Synthesize insights across all sources
+- Identify conflicts between sources
+
+## Step 4: Present Findings
+
+Present a structured summary to the user:
+
+### Problem Statement
+Describe the problem and why it matters.
+
+### Key Findings
+Summarize the most relevant solutions and approaches.
+
+### Codebase Patterns
+Document how the current codebase handles similar cases.
+
+### Recommended Approach
+Provide your recommendation based on all research.
+
+### Conflicts
+Highlight where sources disagree and provide assessment of which is more reliable.
+
+### Sources
+List all source links with brief descriptions. This section is required.
+
+## Research Guidelines
+
+- Prioritize official documentation over blog posts
+- Prefer solutions that match existing codebase patterns
+- Note major.minor versions for libraries/frameworks (patch versions only if critical)
+- Flag conflicting information across sources
+- Write concise, actionable content
+- Use active voice throughout
+- **Do not create output files** - present findings directly in conversation unless user explicitly requests a file

package/src/sources/simplify.md

@@ -0,0 +1,64 @@
+---
+description: Reduce code complexity while keeping tests green
+argument-hint: [file, function, or area to simplify]
+_hint: Reduce complexity
+_category: Test-Driven Development
+_order: 16
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+# Simplify: $ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/fallback-arguments.md' -->
+<!-- /docs -->
+
+Reduce complexity while keeping tests green.
+
+## Core Principles
+
+**YAGNI** - Don't build until actually needed. Delete "just in case" code.
+
+**KISS** - Simplest solution that works. Clever is the enemy of clear.
+
+**Rule of Three** - Don't abstract until 3rd occurrence. "Prefer duplication over wrong abstraction" (Sandi Metz).
+
+## When NOT to Simplify
+
+- Essential domain complexity (regulations, business rules)
+- Performance-critical optimized code
+- Concurrency/thread-safety requirements
+- Security-sensitive explicit checks
+
+## Prerequisites
+
+Tests must be green. If failing, use `/green` first.
+
+<!-- docs INCLUDE path='src/fragments/complexity-signals.md' -->
+<!-- /docs -->
+
+## Techniques
+
+| Pattern | Before | After |
+|---------|--------|-------|
+| Guard clause | Nested `if/else` | Early `return` |
+| Named condition | Complex boolean | `const isValid = ...` |
+| Extract constant | `if (x > 3)` | `if (x > MAX_RETRIES)` |
+| Flatten callback | `.then().then()` | `async/await` |
+
+**Also apply:** Consolidate duplicates, inline unnecessary abstractions, delete dead code.
+
+## Validate
+
+1. Tests still green
+2. Code reads more clearly
+3. No behavioral changes
+
+**Simplify** removes complexity locally. **Refactor** improves architecture broadly. Use `/refactor` if changes require structural reorganization.
+
+<!-- docs INCLUDE path='src/fragments/peeping-tom-warning.md' -->
+<!-- /docs -->