@wbern/claude-instructions 1.21.0 → 2.0.0

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

@@ -1,22 +1,21 @@
 ---
 description: Guide for creating new slash commands
 argument-hint: <command-name> <description>
+_hint: Create command
+_category: Utilities
+_order: 3
 ---
 
-## 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 -->
 
 # 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
@@ -25,7 +24,6 @@ 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)")
 
@@ -52,40 +50,34 @@ 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.
-
+<!-- docs INCLUDE path='src/fragments/fullwidth-dollar-note.md' -->
+<!-- /docs -->
 ```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:*)
@@ -100,9 +92,8 @@ 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.
-
+<!-- docs INCLUDE path='src/fragments/fullwidth-dollar-note.md' -->
+<!-- /docs -->
 ```bash
 mkdir -p ~/.claude/commands/ai
 echo "Ask GPT-5 about: ＄ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
@@ -110,7 +101,6 @@ 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`
@@ -121,7 +111,6 @@ 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
@@ -130,7 +119,6 @@ Edit your system prompt above.
 ```
 
 ### Project-Specific Commands (Bash OK)
-
 ```markdown
 ---
 allowed-tools: Bash(git status:*), Bash(npm list:*)
@@ -142,7 +130,6 @@ 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
@@ -151,7 +138,6 @@ Show differences and suggest improvements.
 ```
 
 ## Usage
-
 After creating: `/<command-name> [arguments]`
 
 Example: `/review` or `/ai:gpt5 "explain this code"`

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

@@ -1,17 +1,19 @@
 ---
 description: Request team review and approval - for complex changes needing discussion
 argument-hint: [optional-pr-title-and-description]
+_hint: Request review
+_category: Ship / Show / Ask
+_order: 3
+_selectedByDefault: false
 ---
 
 # Ask - Request Review and Approval
 
-## 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 - ASK**
 
@@ -130,3 +132,6 @@ Use **Ask** when:
 Use **/show** instead if: confident in approach, just want visibility
 
 Use **/ship** instead if: change is tiny, obvious, and safe
+
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->

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

@@ -1,19 +1,20 @@
 ---
 description: Communicate AI-generated content with transparent attribution
 argument-hint: <task-description>
+_hint: AI attribution
+_category: Utilities
+_order: 2
 ---
 
 # AI-Attributed Communication Command
 
 Execute the user's requested task (e.g., posting PR comments, GitHub issue comments, or other communications through various MCPs), but frame the output with clear AI attribution.
 
-## 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 -->
 
 ## Instructions
 

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

@@ -1,50 +1,23 @@
 ---
 description: Create multiple atomic git commits, one logical change at a time
 argument-hint: [optional-commit-description]
+_hint: Atomic commits
+_category: Workflow
+_order: 2
 ---
 
-## 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 multiple atomic git commits, committing the smallest possible logical unit at a time
 
 Include any of the following info if specified: $ARGUMENTS
 
-## Commit Message Rules
-
-Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
-
-1. **Format**: `type(#issue): description`
-   - Use `#123` for local repo issues
-   - Use `owner/repo#123` for cross-repo issues
-   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
-
-2. **AI Credits**: **NEVER include AI credits in commit messages**
-   - No "Generated with Claude Code"
-   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
-   - Focus on the actual changes made, not conversation history
-
-3. **Content**: Write clear, concise commit messages describing what changed and why
-
-## Process
-
-1. Run `git status` and `git diff` to review changes
-2. Run `git log --oneline -5` to see recent commit style
-3. Stage relevant files with `git add`
-4. Create commit with descriptive message
-5. Verify with `git status`
-
-## Example
-
-```bash
-git add <files>
-git commit -m "feat(#123): add validation to user input form"
-```
+<!-- docs INCLUDE path='src/fragments/commit-process.md' -->
+<!-- /docs -->
 
 ## Atomic Commit Approach
 

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

@@ -1,15 +1,23 @@
 ---
 description: Code review using dynamic category detection and domain-specific analysis
 argument-hint: (optional) [branch, PR#, or PR URL] - defaults to current branch
+_hint: Review code
+_category: Workflow
+_order: 35
+_requested-tools:
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git rev-parse:*)
+  - Bash(git merge-base:*)
+  - Bash(git branch:*)
 ---
 
-## 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 -->
 
 # Code Review
 
@@ -161,30 +169,8 @@ For each detected category with changes, run a targeted review. Skip categories
 
 ### Tests Review 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 -->
 
 ### Docs Review Criteria
 

package/src/sources/commit.md

@@ -0,0 +1,20 @@
+---
+description: Create a git commit following project standards
+argument-hint: [optional-commit-description]
+_hint: Git commit
+_category: Workflow
+_order: 1
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+Create a git commit following project standards
+
+Include any of the following info if specified: $ARGUMENTS
+
+<!-- docs INCLUDE path='src/fragments/commit-process.md' -->
+<!-- /docs -->

package/src/sources/cycle.md

@@ -0,0 +1,23 @@
+---
+description: Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
+argument-hint: <feature or requirement description>
+_hint: Full TDD cycle
+_category: Test-Driven Development
+_order: 5
+---
+
+RED+GREEN+REFACTOR (one cycle) 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/{downloads/without-beads → src/sources}/gap.md

@@ -1,27 +1,30 @@
 ---
 description: Analyze conversation context for unaddressed items and gaps
 argument-hint: [optional additional info]
+_hint: Find gaps
+_category: Workflow
+_order: 11
 ---
 
-## 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 -->
 
 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
-
+<!-- docs INCLUDE path='src/fragments/gap-beads.md' featureFlag='beads' -->
+<!-- /docs -->
 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
-8. **Consistency check** - Look for inconsistent patterns, naming conventions, or structure across the codebase
+<!-- docs INCLUDE path='src/fragments/consistency-check.md' -->
+<!-- /docs -->
 
 Present findings as a prioritized list with:
 

package/src/sources/green.md

@@ -0,0 +1,23 @@
+---
+description: Execute TDD Green Phase - write minimal implementation to pass the failing test
+argument-hint: <implementation description>
+_hint: Make it pass
+_category: Test-Driven Development
+_order: 3
+---
+
+GREEN 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/issue.md

@@ -0,0 +1,42 @@
+---
+description: Analyze GitHub issue and create TDD implementation plan
+argument-hint: [optional-issue-number]
+_hint: Analyze issue
+_category: Planning
+_order: 1
+---
+
+Analyze GitHub issue and create TDD implementation plan.
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+Process:
+
+1. Get Issue Number
+
+- Either from branch name use that issue number
+  - Patterns: issue-123, 123-feature, feature/123, fix/123
+- Or from this bullet point with custom info: $ARGUMENTS
+- If not found: ask user
+
+2. Fetch Issue
+
+<!-- docs INCLUDE path='src/fragments/github-issue-fetch.md' -->
+<!-- /docs -->
+
+3. Analyze and Plan
+
+Summarize the issue and requirements, then:
+
+<!-- docs INCLUDE path='src/fragments/discovery-phase.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/tdd-fundamentals.md' -->
+<!-- /docs -->

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

@@ -1,23 +1,26 @@
 ---
 description: Generate a TDD practice challenge with boilerplate test setup
 argument-hint: (no arguments - interactive)
+_hint: Practice kata
+_category: Utilities
+_order: 10
+_requested-tools:
+  - WebFetch(domain:raw.githubusercontent.com)
+  - WebFetch(domain:api.github.com)
 ---
 
 # Kata: TDD Practice Challenge Generator
 
 Generate a complete TDD practice setup:
-
 - `CHALLENGE.md` - Problem description
 - Test file with first test placeholder
 - Implementation file with empty function
 
-## General Guidelines
-
-### Output Style
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /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
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
 
 ## Input
 
@@ -312,11 +315,9 @@ Use conversational AskUserQuestion flow. User can skip to suggestions at any poi
 # Kata: {$SELECTED_KATA}
 
 ## Difficulty
-
 {$DIFFICULTY_STARS based on category}
 
 ## Problem
-
 {$KATA_CONTENT from readme.txt}
 
 ## TDD Approach

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

@@ -1,30 +1,31 @@
 ---
 description: Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria
 argument-hint: <feature/requirement description or GitHub issue URL/number>
+_hint: Plan feature
+_category: Planning
+_order: 2
 ---
 
 # Plan: PRD-Informed Task Planning for TDD
 
 Create structured implementation plan that bridges product thinking (PRD) with test-driven development.
 
-## 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 -->
 
 ## Input
 
 $ARGUMENTS
 
-(If no input provided, check conversation context)
+(If no input provided, check conversation context<!-- docs INCLUDE path='src/fragments/plan-beads-context-hint.md' featureFlag='beads' -->
+<!-- /docs -->)
 
 ## 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,14 +36,12 @@ 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>`
 
@@ -53,7 +52,6 @@ Trying GitHub CLI fallback...
 ```
 
 **Step 3: Use Issue as Discovery Input**
-
 - Title → Feature name
 - Description → Problem statement and context
 - Labels → Type/priority hints
@@ -61,7 +59,6 @@ Trying GitHub CLI fallback...
 - Linked issues → Dependencies
 
 Extract from GitHub issue:
-
 - Problem statement and context
 - Acceptance criteria (if present)
 - Technical notes (if present)
@@ -69,48 +66,30 @@ Extract from GitHub issue:
 
 ## Process
 
-## Discovery Phase
-
-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?
+<!-- docs INCLUDE path='src/fragments/discovery-phase.md' -->
+<!-- /docs -->
 
-**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
+<!-- docs INCLUDE path='src/fragments/plan-beads-details.md' featureFlag='beads' -->
+<!-- /docs -->
 
 ## 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)
 
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->
+
 ## Integration with Other Commands
 
 - **Before /plan**: Use `/spike` if you need technical exploration first
 - **After /plan**: Use `/red` to start TDD on first task
+<!-- docs INCLUDE path='src/fragments/plan-beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->

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

@@ -1,17 +1,18 @@
 ---
 description: Creates a pull request using GitHub MCP
 argument-hint: [optional-pr-title-and-description]
+_hint: Create PR
+_category: Workflow
+_order: 5
 ---
 
 # Create Pull Request
 
-## 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 pull request for the current branch using GitHub MCP tools.
 
@@ -68,3 +69,6 @@ Arguments: $ARGUMENTS
 2. Create a well-formatted pull request with proper title and description
 3. Set the base branch (default: main)
 4. Include relevant issue references if found in commit messages
+
+<!-- docs INCLUDE path='src/fragments/beads-integration.md' featureFlag='beads' -->
+<!-- /docs -->