@wbern/claude-instructions 1.21.0 → 2.1.0

package/src/sources/red.md

@@ -0,0 +1,26 @@
+---
+description: Execute TDD Red Phase - write ONE failing test
+argument-hint: [optional additional info]
+_hint: Failing test
+_category: Test-Driven Development
+_order: 2
+---
+
+RED PHASE! Apply the below to the info given by user input here:
+
+$ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/fallback-arguments-beads.md' featureFlag='beads' elsePath='src/fragments/fallback-arguments.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/aaa-pattern.md' -->
+<!-- /docs -->

package/src/sources/refactor.md

@@ -0,0 +1,27 @@
+---
+description: Execute TDD Refactor Phase - improve code structure while keeping tests green
+argument-hint: <refactoring description>
+_hint: Clean up code
+_category: Test-Driven Development
+_order: 4
+---
+
+Apply this document (specifically the Refactor phase), to the info given by user input here: $ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/fallback-arguments-beads.md' featureFlag='beads' elsePath='src/fragments/fallback-arguments.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/peeping-tom-warning.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/consistency-check.md' -->
+<!-- /docs -->

package/{downloads/without-beads → src/sources}/ship.md

@@ -1,17 +1,19 @@
 ---
 description: Ship code directly to main - for small, obvious changes that don't need review
 argument-hint: [optional-commit-message]
+_hint: Direct to main
+_category: Ship / Show / Ask
+_order: 1
+_selectedByDefault: false
 ---
 
 # Ship - Direct Merge to Main
 
-## General Guidelines
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
 
-### 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
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
 **Ship/Show/Ask Pattern - SHIP**
 
@@ -84,3 +86,6 @@ If tests fail, linter fails, or changes are large/complex, STOP and suggest:
 
 - Use `/show` for changes that should be seen but don't need approval
 - Use `/ask` (traditional PR) for complex changes needing discussion
+
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->

package/{downloads/without-beads → src/sources}/show.md

@@ -1,17 +1,19 @@
 ---
 description: Show code to team with auto-merge - for changes that should be visible but don't need approval
 argument-hint: [optional-pr-title-and-description]
+_hint: Auto-merge PR
+_category: Ship / Show / Ask
+_order: 2
+_selectedByDefault: false
 ---
 
 # Show - Visible Merge with Optional Feedback
 
-## General Guidelines
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
 
-### 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
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
 **Ship/Show/Ask Pattern - SHOW**
 
@@ -100,3 +102,6 @@ Use **Show** when:
 Use **/ship** instead if: change is tiny and obvious (typo, formatting)
 
 Use **/ask** instead if: change needs discussion, breaks APIs, or you're uncertain
+
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->

package/src/sources/spike.md

@@ -0,0 +1,23 @@
+---
+description: Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
+argument-hint: <exploration description>
+_hint: Explore first
+_category: Test-Driven Development
+_order: 1
+---
+
+SPIKE PHASE! Apply the below to the info given by user input here:
+
+$ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/fallback-arguments-beads.md' featureFlag='beads' elsePath='src/fragments/fallback-arguments.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+<!-- /docs -->

package/src/sources/summarize.md

@@ -0,0 +1,23 @@
+---
+description: Summarize conversation progress and next steps
+argument-hint: [optional additional info]
+_hint: Summarize chat
+_category: Workflow
+_order: 10
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+Create a concise summary of the current conversation suitable for transferring context to a new conversation.
+
+Additional info: $ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/summarize-structure.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/summarize-beads.md' featureFlag='beads' -->
+<!-- /docs -->

package/{downloads/without-beads → src/sources}/tdd-review.md

@@ -1,17 +1,19 @@
 ---
 description: Review test suite quality against FIRST principles and TDD anti-patterns
 argument-hint: [optional test file or directory path]
+_hint: Review tests
+_category: Test-Driven Development
+_order: 45
 ---
 
-## General Guidelines
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
 
-### Output Style
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
-- **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)
+<!-- docs INCLUDE path='src/fragments/fallback-arguments-beads.md' featureFlag='beads' elsePath='src/fragments/fallback-arguments.md' -->
+<!-- /docs -->
 
 # Test Quality Review
 
@@ -35,30 +37,8 @@ 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
+<!-- docs INCLUDE path='src/fragments/test-quality-criteria.md' -->
+<!-- /docs -->
 
 ## Phase 3: Report
 

package/src/sources/tdd.md

@@ -0,0 +1,24 @@
+---
+description: Remind agent about TDD approach and continue conversation
+argument-hint: [optional-response-to-last-message]
+_hint: TDD reminder
+_category: Test-Driven Development
+_order: 1
+---
+
+# TDD Reminder
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+<!-- /docs -->
+
+## Continue Conversation
+
+User response to the last message: $ARGUMENTS
+
+Please continue with TDD approach based on the above response.

package/{downloads/without-beads → src/sources}/worktree-add.md

@@ -1,17 +1,18 @@
 ---
 description: Add a new git worktree from branch name or issue URL, copy settings, install deps, and open in current IDE
 argument-hint: <branch-name-or-issue-url> [optional-base-branch]
+_hint: Add worktree
+_category: Worktree Management
+_order: 1
 ---
 
 # Git Worktree Setup
 
-## General Guidelines
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
 
-### 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
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
 Create a new git worktree for branch: $ARGUMENTS
 
@@ -45,26 +46,8 @@ Uncommitted changes: `git status --short`
 <step_0b>
   <description>Detect git hosting provider and available tools (only needed if argument is an issue URL)</description>
   <condition>Only run this step if first argument looks like a git hosting URL</condition>
-<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>
-
+<!-- docs INCLUDE path='src/fragments/git-host-detection.md' -->
+<!-- /docs -->
   <purpose>Detect git hosting provider and select appropriate tool for issue lookup</purpose>
 </step_0b>
 
@@ -116,9 +99,9 @@ Uncommitted changes: `git status --short`
       <bitbucket>Check if argument contains "bitbucket.org" and "/issues/"</bitbucket>
     </url_detection>
     <url_parsing>
-      <github_pattern><https://github.com/{owner}/{repo}/issues/{issue_number}></github_pattern>
-      <gitlab_pattern><https://gitlab.com/{owner}/{repo}/-/issues/{issue_number}></gitlab_pattern>
-      <bitbucket_pattern><https://bitbucket.org/{owner}/{repo}/issues/{issue_number}></bitbucket_pattern>
+      <github_pattern>https://github.com/{owner}/{repo}/issues/{issue_number}</github_pattern>
+      <gitlab_pattern>https://gitlab.com/{owner}/{repo}/-/issues/{issue_number}</gitlab_pattern>
+      <bitbucket_pattern>https://bitbucket.org/{owner}/{repo}/issues/{issue_number}</bitbucket_pattern>
       <extract>owner, repo, issue_number from URL</extract>
     </url_parsing>
     <fetch_issue_details>
@@ -263,7 +246,7 @@ Uncommitted changes: `git status --short`
       - packages/*/.env.local
       - (any other .env.local files found)
     </common_locations>
-    <copy_command>find . -name ".env.local" -type f -exec sh -c 'mkdir -p "$(dirname "${parent_path}/${branch_name}/$1")" && cp "$1" "${parent_path}/${branch_name}/$1"'_ {} \;</copy_command>
+    <copy_command>find . -name ".env.local" -type f -exec sh -c 'mkdir -p "$(dirname "${parent_path}/${branch_name}/$1")" && cp "$1" "${parent_path}/${branch_name}/$1"' _ {} \;</copy_command>
     <purpose>Preserve local environment configurations for development</purpose>
     <note>Only copies files that exist; ignores missing ones</note>
   </step_9>
@@ -347,7 +330,6 @@ EOF</create_file_command>
 - New branches are automatically pushed with `-u` to set up remote tracking
 
 Limitations:
-
 - Assumes remote is named "origin" (most common convention)
 - Supports macOS and Linux only (no Windows support)
 - Requires MCP server or CLI for git hosting provider when using issue URLs (GitHub, GitLab, etc.)

package/{downloads/without-beads → src/sources}/worktree-cleanup.md

@@ -1,17 +1,18 @@
 ---
 description: Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees
 argument-hint: (no arguments)
+_hint: Cleanup worktree
+_category: Worktree Management
+_order: 2
 ---
 
 # Worktree Cleanup
 
-## General Guidelines
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
 
-### 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
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
 Clean up merged worktrees by finding the oldest merged branch, consolidating settings, and removing stale worktrees.
 
@@ -25,26 +26,8 @@ Current worktrees: `git worktree list`
 <execution_steps>
 <step_0>
   <description>Detect git hosting provider and available tools</description>
-<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>
-
+<!-- docs INCLUDE path='src/fragments/git-host-detection.md' -->
+<!-- /docs -->
   <purpose>Detect git hosting provider and select appropriate tool for PR verification</purpose>
 </step_0>
 
@@ -241,7 +224,6 @@ Current worktrees: `git worktree list`
 - Must be run from default branch for safety
 
 Limitations:
-
 - Assumes remote is named "origin" (most common convention)
 - Supports macOS and Linux only (no Windows support)
 - Requires MCP server or CLI for git hosting provider (GitHub, GitLab, etc.)

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

@@ -1,159 +0,0 @@
----
-description: Guide for creating new slash commands
-argument-hint: <command-name> <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
-
-Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
-
-# 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
-
-**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.
-
-```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
-
-**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.
-
-```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"`