@wbern/claude-instructions 1.7.0 → 1.8.0

package/README.md

@@ -106,6 +106,7 @@ 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)
 

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

@@ -3,10 +3,22 @@ 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
@@ -15,6 +27,7 @@ The `/add-command` command shows this guide for creating new slash commands. It
 **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)")
 
@@ -41,33 +54,40 @@ 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:*)
@@ -82,7 +102,9 @@ 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
@@ -90,6 +112,7 @@ echo "Ask GPT-5 about: ＄ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
 ```
 
 ## 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`
@@ -100,6 +123,7 @@ echo "Ask GPT-5 about: ＄ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
 ## Best Practices
 
 ### Safe Commands (No Security Issues)
+
 ```markdown
 # System prompt editor (file reference only)  
 (@)path/to/system/prompt.md
@@ -108,6 +132,7 @@ Edit your system prompt above.
 ```
 
 ### Project-Specific Commands (Bash OK)
+
 ```markdown
 ---
 allowed-tools: Bash(git status:*), Bash(npm list:*)
@@ -119,6 +144,7 @@ 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
@@ -127,6 +153,7 @@ Show differences and suggest improvements.
 ```
 
 ## Usage
+
 After creating: `/<command-name> [arguments]`
 
 Example: `/review` or `/ai:gpt5 "explain this code"`

package/downloads/with-beads/ask.md

@@ -9,10 +9,13 @@ argument-hint: [optional-pr-title-and-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).
+
 **Ship/Show/Ask Pattern - ASK**
 
 > 💭 **Cursor says**: Fine, SOME things still need traditional PRs. But be intentional about it.
@@ -136,8 +139,9 @@ Use **/ship** instead if: change is tiny, obvious, and safe
 ### 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.
+See <https://github.com/steveyegge/beads> for more information.

package/downloads/with-beads/beepboop.md

@@ -11,18 +11,12 @@ Execute the user's requested task (e.g., posting PR comments, GitHub issue comme
 ## 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 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.
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
 
 ## Instructions
 

package/downloads/with-beads/busycommit.md

@@ -4,12 +4,19 @@ description: Create multiple atomic git commits, one logical change at a time
 argument-hint: [optional-commit-description]
 ---
 
-Create multiple atomic git commits, committing the smallest possible logical unit at a time
+## General Guidelines
 
-Include any of the following info if specified: $ARGUMENTS
+### 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).
 
+Create multiple atomic git commits, committing the smallest possible logical unit at a time
+
+Include any of the following info if specified: $ARGUMENTS
 
 ## Process
 

package/downloads/with-beads/commit.md

@@ -4,12 +4,19 @@ description: Create a git commit following project standards
 argument-hint: [optional-commit-description]
 ---
 
-Create a git commit following project standards
+## General Guidelines
 
-Include any of the following info if specified: $ARGUMENTS
+### 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).
 
+Create a git commit following project standards
+
+Include any of the following info if specified: $ARGUMENTS
 
 ## Process
 

package/downloads/with-beads/cycle.md

@@ -11,11 +11,15 @@ $ARGUMENTS
 ## 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)
 

package/downloads/with-beads/gap.md

@@ -1,17 +1,29 @@
 ---
 description: Analyze conversation context for unaddressed items and gaps
+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
+
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
+
 Analyze the current conversation context and identify things that have not yet been addressed. Look for:
 
 1. **Incomplete implementations** - Code that was started but not finished
 2. **Unused variables/results** - Values that were captured but never used
 3. **Missing tests** - Functionality without test coverage
-      4. **Open issues** - Beads issues that are still open or in progress
-      4. **User requests** - Things the user asked for that weren't fully completed
-5. **TODO comments** - Any TODOs mentioned in conversation
-6. **Error handling gaps** - Missing error cases or edge cases
-7. **Documentation gaps** - Undocumented APIs or features
+4. **Open issues** - Beads issues that are still open or in progress
+5. **User requests** - Things the user asked for that weren't fully completed
+6. **TODO comments** - Any TODOs mentioned in conversation
+7. **Error handling gaps** - Missing error cases or edge cases
+8. **Documentation gaps** - Undocumented APIs or features
+9. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase
 
 Present findings as a prioritized list with:
 

package/downloads/with-beads/green.md

@@ -11,11 +11,15 @@ $ARGUMENTS
 ## 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)
 

package/downloads/with-beads/issue.md

@@ -9,10 +9,13 @@ Analyze GitHub issue and create TDD implementation plan.
 ## 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).
+
 Process:
 
 1. Get Issue Number
@@ -22,11 +25,12 @@ Process:
 - Or from this bullet point with custom info: $ARGUMENTS
 - If not found: ask user
 
-2. Fetch Issue
+1. Fetch Issue
 
 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
@@ -35,7 +39,7 @@ Trying GitHub CLI fallback...
 
 Then try using `gh issue view [ISSUE_NUMBER] --json` as fallback.
 
-3. Analyze and Plan
+1. Analyze and Plan
 
 Summarize the issue and requirements, then:
 
@@ -44,32 +48,37 @@ Summarize the issue and requirements, then:
 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
 
 ### 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.
+See <https://github.com/steveyegge/beads> for more information.
 
 ## TDD Fundamentals
 

package/downloads/with-beads/plan.md

@@ -11,10 +11,13 @@ Create structured implementation plan that bridges product thinking (PRD) with t
 ## 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).
+
 ## Input
 
 $ARGUMENTS
@@ -25,6 +28,7 @@ $ARGUMENTS
 ## Input Processing
 
 The input can be one of:
+
 1. **GitHub Issue URL** (e.g., `https://github.com/owner/repo/issues/123`)
 2. **GitHub Issue Number** (e.g., `#123` or `123`)
 3. **Feature Description** (e.g., "Add user authentication")
@@ -35,12 +39,14 @@ The input can be one of:
 If input looks like a GitHub issue:
 
 **Step 1: Extract Issue Number**
+
 - From URL: extract owner/repo/number
 - From number: try to infer repo from git remote
 - From branch name: check patterns like `issue-123`, `123-feature`, `feature/123`
 
 **Step 2: Fetch Issue**
 Try GitHub MCP first:
+
 - If available: use `mcp__github__issue_read` to fetch issue details
 - If not available: show message and try `gh issue view <number>`
 
@@ -51,6 +57,7 @@ Trying GitHub CLI fallback...
 ```
 
 **Step 3: Use Issue as Discovery Input**
+
 - Title → Feature name
 - Description → Problem statement and context
 - Labels → Type/priority hints
@@ -58,6 +65,7 @@ Trying GitHub CLI fallback...
 - Linked issues → Dependencies
 
 Extract from GitHub issue:
+
 - Problem statement and context
 - Acceptance criteria (if present)
 - Technical notes (if present)
@@ -70,21 +78,25 @@ Extract from GitHub issue:
 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
 
@@ -104,27 +116,32 @@ bd create "Task title" \
 **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
 ```
@@ -132,6 +149,7 @@ 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
@@ -141,11 +159,13 @@ After creating issues, verify:
 ## Key Principles
 
 **From PRD World:**
+
 - Start with user problems, not solutions
 - Define success criteria upfront
 - Understand constraints and scope
 
 **From TDD World:**
+
 - Make acceptance criteria test-ready
 - Break work into small, testable pieces
 - Each task should map to test(s)
@@ -153,11 +173,12 @@ After creating issues, verify:
 ### 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.
+See <https://github.com/steveyegge/beads> for more information.
 
 ## Integration with Other Commands
 

package/downloads/with-beads/red.md

@@ -1,21 +1,28 @@
 ---
 allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Red Phase - write ONE failing test
+argument-hint: [optional additional info]
 ---
 
 RED PHASE! Apply the below to the info given by user input here:
 
 $ARGUMENTS
 
-(If there was no info above, use info from the current context of conversation. If there was not enough info, ask for it.)
-
 ## 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)
+
 ## TDD Fundamentals
 
 ### The TDD Cycle

package/downloads/with-beads/refactor.md

@@ -9,11 +9,15 @@ Apply this document (specifically the Refactor phase), to the info given by user
 ## 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)
 
@@ -88,3 +92,5 @@ 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.
+
+1. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase

package/downloads/with-beads/ship.md

@@ -9,10 +9,13 @@ argument-hint: [optional-commit-message]
 ## 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).
+
 **Ship/Show/Ask Pattern - SHIP**
 
 > 🎯 **Cursor says**: It's 2025! Not everything needs a PR. Ship small, obvious changes directly.
@@ -90,8 +93,9 @@ If tests fail, linter fails, or changes are large/complex, STOP and suggest:
 ### 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.
+See <https://github.com/steveyegge/beads> for more information.

package/downloads/with-beads/show.md

@@ -9,10 +9,13 @@ argument-hint: [optional-pr-title-and-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).
+
 **Ship/Show/Ask Pattern - SHOW**
 
 > 🚀 **Cursor says**: Not every change needs a traditional review. Show your work, then merge.
@@ -106,8 +109,9 @@ Use **/ask** instead if: change needs discussion, breaks APIs, or you're uncerta
 ### 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.
+See <https://github.com/steveyegge/beads> for more information.

package/downloads/with-beads/spike.md

@@ -11,11 +11,15 @@ $ARGUMENTS
 ## 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)
 

package/downloads/with-beads/summarize.md

@@ -1,8 +1,19 @@
 ---
 allowed-tools: AskUserQuestion
 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
+
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
+
 Create a concise summary of the current conversation suitable for transferring context to a new conversation.
 
 Additional info: $ARGUMENTS
@@ -12,16 +23,19 @@ Additional info: $ARGUMENTS
 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
@@ -33,6 +47,7 @@ Keep the summary concise and actionable - suitable for pasting into a new conver
 ## 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