@wbern/claude-instructions 2.5.0 → 2.7.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-27-blue)](https://github.com/wbern/claude-instructions#available-commands)
 
 ```
        _==/          i     i          \==_
@@ -69,7 +74,7 @@ Then add a postinstall script to your `package.json`:
     "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
-    "@wbern/claude-instructions": "^2.5.0"
+    "@wbern/claude-instructions": "^2.7.0"
   }
 }
 ```
@@ -197,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
@@ -206,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
@@ -224,6 +231,8 @@ 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
+- `/commitlint-checklist-nodejs` - Audit commit hook automation for Node.js projects
 
 ## Getting Started
 

package/package.json

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

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/commitlint-checklist-nodejs.md

@@ -0,0 +1,72 @@
+---
+description: Audit commit hook automation for Node.js projects
+argument-hint: (no arguments - interactive)
+_hint: Audit commit hooks (Node.js)
+_category: Utilities
+_order: 25
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+# Commit Hook Automation Checklist (Node.js)
+
+Scan the Node.js repository and report what commit automation is in place.
+
+$ARGUMENTS
+
+## Checks to Scan
+
+Scan the repository for these configurations (do not display this list to user):
+
+**🔧 Infrastructure**
+- Husky: `.husky/`, `package.json` → `"prepare": "husky"`
+- Pre-commit hook: `.husky/pre-commit`
+- lint-staged: `lint-staged.config.*`, `.lintstagedrc.*`, or `package.json` lint-staged key
+
+**🧹 Code Quality**
+- Linting: `eslint.config.*`, `biome.json`, `.eslintrc.*`
+- Formatting: `.prettierrc*`, `biome.json`
+- Type checking: `tsconfig.json` + lint-staged runs `tsc --noEmit`
+- Knip: `knip.json` or knip in scripts
+- jscpd: `.jscpd.json` or jscpd in scripts
+
+**🔒 Security**
+- Secret scanning: `.secretlintrc.json`, secretlint in dependencies
+
+**📝 Commits**
+- Conventional commits: `.husky/commit-msg`, `commitlint.config.*`, `@commitlint/*` in deps
+
+**🧪 Testing**
+- Pre-commit tests: lint-staged or pre-commit hook runs test command
+- Coverage thresholds: vitest/jest config with coverage thresholds
+
+## Output Format
+
+Display ONLY this summary format (no tables, no detailed breakdown):
+
+```
+✅ Passing:
+  🔧 Infrastructure: Husky, pre-commit hook, lint-staged
+  🧹 Code Quality: Linting, formatting, type checking, Knip, jscpd
+  🧪 Testing: Pre-commit tests, coverage thresholds
+
+❌ Missing (2):
+  • Secret scanning (secretlint)
+  • Conventional commits (commitlint)
+
+📊 10/12 checks passing
+```
+
+Omit categories with no passing checks from the "Passing" section.
+
+## Follow-up
+
+After the summary, tell the user:
+
+> For working examples of most items above, see [wbern/claude-instructions](https://github.com/wbern/claude-instructions) on GitHub.
+>
+> Would you like help implementing any of the missing checks?

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 -->