@wbern/claude-instructions 1.0.1

package/downloads/with-beads/ask.md

@@ -0,0 +1,134 @@
+---
+allowed-tools: mcp__github__*, Bash(git:*)
+description: Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)
+argument-hint: [optional-pr-title-and-description]
+---
+
+# Ask - Request Review and Approval
+
+## 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
+
+**Ship/Show/Ask Pattern - ASK**
+
+> 💭 **Cursor says**: Fine, SOME things still need traditional PRs. But be intentional about it.
+
+Ask is for complex changes that need team discussion and approval. Examples:
+- Breaking API changes
+- New architecture decisions
+- Significant feature additions
+- Performance trade-offs
+- Security-sensitive changes
+
+## When to Ask
+
+Use **Ask** when:
+- Changes affect multiple systems
+- Breaking changes are needed
+- You need input on approach
+- Security implications exist
+- Performance trade-offs need discussion
+- Uncertain about the best solution
+
+## Workflow
+
+Current branch status:
+!`git status`
+
+Recent commits:
+!`git log --oneline -5`
+
+Arguments: $ARGUMENTS
+
+**This is the traditional Pull Request workflow**, but with explicit intent that review and approval are required.
+
+**Process:**
+
+1. **Ensure Branch is Ready**:
+   !`git status`
+   - Commit all changes
+   - Push to remote: `git push origin [branch-name]`
+
+2. **Create Ask PR**: Create a PR that clearly needs review
+   
+   Title: conventional commits format, prefixed with `[ASK]`
+   
+   Description template:
+   ```markdown
+   ## 🤔 Ask - Review and Approval Needed
+
+   **This is an ASK PR**: These changes need team review and discussion.
+
+   <!--
+     References: [link to relevant issues]
+   -->
+
+   ### What changed
+   [Detailed description of changes]
+
+   ### Why
+   [Rationale and context]
+
+   ### Questions for reviewers
+   - [ ] Question 1
+   - [ ] Question 2
+
+   ### Concerns
+   - Potential concern 1
+   - Potential concern 2
+
+   ### Test Plan
+   - [ ] Unit tests
+   - [ ] Integration tests
+   - [ ] Manual testing steps
+
+   ### Alternatives considered
+   - Alternative 1: [why not chosen]
+   - Alternative 2: [why not chosen]
+   ```
+
+3. **Request Reviewers**: Assign specific reviewers who should weigh in
+
+4. **Add Labels**: 
+   - "needs-review"
+   - "breaking-change" (if applicable)
+   - "security" (if applicable)
+
+5. **Link Issues**: Reference related issues in the description
+
+6. **Monitor Discussion**: Be responsive to reviewer feedback and questions
+
+## Use GitHub MCP Tools
+
+1. Check current branch and ensure it's pushed
+2. Create a well-formatted pull request with [ASK] prefix
+3. Set reviewers
+4. Add appropriate labels
+5. Link related issues from commit messages
+
+## Decision Guide
+
+Use **Ask** when:
+- ✅ Change is complex or risky
+- ✅ Breaking changes involved
+- ✅ Need team input on approach
+- ✅ Multiple solutions possible
+- ✅ Security implications
+
+Use **/show** instead if: confident in approach, just want visibility
+
+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.
+

package/downloads/with-beads/beepboop.md

@@ -0,0 +1,54 @@
+---
+allowed-tools: Read, Grep, Glob
+description: Communicate AI-generated content with transparent attribution
+argument-hint: <task-description>
+---
+
+# 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
+
+### 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.
+
+## Instructions
+
+Arguments: $ARGUMENTS
+
+**IMPORTANT Communication Format:**
+
+1. **Opening**: Begin with "*Beep boop, I am Claude Code 🤖, my user has reviewed and approved the following written by me:*"
+   - Use italics for this line
+   - Clearly establishes AI authorship
+
+2. **Middle**: Perform the requested task (post comment, create review, etc.)
+   - Execute whatever communication task the user requested
+   - Write the actual content that accomplishes the user's goal
+
+3. **Closing**: End with "*Beep boop, Claude Code 🤖 out!*"
+   - Use italics for this line
+   - Provides clear closure
+
+## Purpose
+
+This command ensures transparency about AI usage while maintaining that the user has reviewed and approved the content. It prevents offloading review responsibility to other users while being open about AI assistance.
+
+## Examples
+
+- Posting a GitHub PR review comment
+- Adding a comment to a GitHub issue
+- Responding to feedback with AI-generated explanations
+- Any communication where AI attribution is valuable

package/downloads/with-beads/commit.md

@@ -0,0 +1,47 @@
+---
+allowed-tools: Bash(pnpm test:*), Bash(pnpm lint:*)
+description: Create a git commit following project standards
+argument-hint: [optional-commit-description]
+---
+
+Create a git commit following project standards
+
+Include any of the following info if specified: $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
+
+## 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"
+```

package/downloads/with-beads/cycle.md

@@ -0,0 +1,89 @@
+---
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+description: Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
+argument-hint: <feature or requirement description>
+---
+
+RED+GREEN+REFACTOR (one cycle) PHASE! Apply the below to the info given by user input here:
+
+$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
+
+(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
+
+The foundation of TDD is the Red-Green-Refactor cycle:
+
+1. **Red Phase**: Write ONE failing test that describes desired behavior
+
+   - The test must fail for the RIGHT reason (not syntax/import errors)
+   - Only one test at a time - this is critical for TDD discipline
+   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
+   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
+
+2. **Green Phase**: Write MINIMAL code to make the test pass
+
+   - Implement only what's needed for the current failing test
+   - No anticipatory coding or extra features
+   - Address the specific failure message
+
+3. **Refactor Phase**: Improve code structure while keeping tests green
+   - Only allowed when relevant tests are passing
+   - Requires proof that tests have been run and are green
+   - Applies to BOTH implementation and test code
+   - No refactoring with failing tests - fix them first
+
+### Core Violations
+
+1. **Multiple Test Addition**
+
+   - Adding more than one new test at once
+   - Exception: Initial test file setup or extracting shared test utilities
+
+2. **Over-Implementation**
+
+   - Code that exceeds what's needed to pass the current failing test
+   - Adding untested features, methods, or error handling
+   - Implementing multiple methods when test only requires one
+
+3. **Premature Implementation**
+   - Adding implementation before a test exists and fails properly
+   - Adding implementation without running the test first
+   - Refactoring when tests haven't been run or are failing
+
+### Critical Principle: Incremental Development
+
+Each step in TDD should address ONE specific issue:
+
+- Test fails "not defined" → Create empty stub/class only
+- Test fails "not a function" → Add method stub only
+- Test fails with assertion → Implement minimal logic only
+
+### Optional Pre-Phase: Spike Phase
+
+In rare cases where the problem space, interface, or expected behavior is unclear, a **Spike Phase** may be used **before the Red Phase**.
+This phase is **not part of the regular TDD workflow** and must only be applied under exceptional circumstances.
+
+- The goal of a Spike is **exploration and learning**, not implementation.
+- The code written during a Spike is **disposable** and **must not** be merged or reused directly.
+- Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**.
+- A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior.
+
+### General Information
+
+- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
+- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
+- 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.

package/downloads/with-beads/green.md

@@ -0,0 +1,89 @@
+---
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+description: Execute TDD Green Phase - write minimal implementation to pass the failing test
+argument-hint: <implementation description>
+---
+
+GREEN PHASE! Apply the below to the info given by user input here:
+
+$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
+
+(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
+
+The foundation of TDD is the Red-Green-Refactor cycle:
+
+1. **Red Phase**: Write ONE failing test that describes desired behavior
+
+   - The test must fail for the RIGHT reason (not syntax/import errors)
+   - Only one test at a time - this is critical for TDD discipline
+   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
+   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
+
+2. **Green Phase**: Write MINIMAL code to make the test pass
+
+   - Implement only what's needed for the current failing test
+   - No anticipatory coding or extra features
+   - Address the specific failure message
+
+3. **Refactor Phase**: Improve code structure while keeping tests green
+   - Only allowed when relevant tests are passing
+   - Requires proof that tests have been run and are green
+   - Applies to BOTH implementation and test code
+   - No refactoring with failing tests - fix them first
+
+### Core Violations
+
+1. **Multiple Test Addition**
+
+   - Adding more than one new test at once
+   - Exception: Initial test file setup or extracting shared test utilities
+
+2. **Over-Implementation**
+
+   - Code that exceeds what's needed to pass the current failing test
+   - Adding untested features, methods, or error handling
+   - Implementing multiple methods when test only requires one
+
+3. **Premature Implementation**
+   - Adding implementation before a test exists and fails properly
+   - Adding implementation without running the test first
+   - Refactoring when tests haven't been run or are failing
+
+### Critical Principle: Incremental Development
+
+Each step in TDD should address ONE specific issue:
+
+- Test fails "not defined" → Create empty stub/class only
+- Test fails "not a function" → Add method stub only
+- Test fails with assertion → Implement minimal logic only
+
+### Optional Pre-Phase: Spike Phase
+
+In rare cases where the problem space, interface, or expected behavior is unclear, a **Spike Phase** may be used **before the Red Phase**.
+This phase is **not part of the regular TDD workflow** and must only be applied under exceptional circumstances.
+
+- The goal of a Spike is **exploration and learning**, not implementation.
+- The code written during a Spike is **disposable** and **must not** be merged or reused directly.
+- Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**.
+- A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior.
+
+### General Information
+
+- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
+- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
+- 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.

package/downloads/with-beads/issue.md

@@ -0,0 +1,141 @@
+---
+allowed-tools: mcp__github__issue_read, mcp__github__get_issue, Task
+description: Analyze GitHub issue and create TDD implementation plan
+argument-hint: [optional-issue-number]
+---
+
+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
+
+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
+
+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
+Trying GitHub CLI fallback...
+```
+
+Then try using `gh issue view [ISSUE_NUMBER] --json` as fallback.
+
+3. Analyze and Plan
+
+Summarize the issue and requirements, then:
+
+## 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?
+
+**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.
+
+## TDD Fundamentals
+
+### The TDD Cycle
+
+The foundation of TDD is the Red-Green-Refactor cycle:
+
+1. **Red Phase**: Write ONE failing test that describes desired behavior
+
+   - The test must fail for the RIGHT reason (not syntax/import errors)
+   - Only one test at a time - this is critical for TDD discipline
+   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
+   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
+
+2. **Green Phase**: Write MINIMAL code to make the test pass
+
+   - Implement only what's needed for the current failing test
+   - No anticipatory coding or extra features
+   - Address the specific failure message
+
+3. **Refactor Phase**: Improve code structure while keeping tests green
+   - Only allowed when relevant tests are passing
+   - Requires proof that tests have been run and are green
+   - Applies to BOTH implementation and test code
+   - No refactoring with failing tests - fix them first
+
+### Core Violations
+
+1. **Multiple Test Addition**
+
+   - Adding more than one new test at once
+   - Exception: Initial test file setup or extracting shared test utilities
+
+2. **Over-Implementation**
+
+   - Code that exceeds what's needed to pass the current failing test
+   - Adding untested features, methods, or error handling
+   - Implementing multiple methods when test only requires one
+
+3. **Premature Implementation**
+   - Adding implementation before a test exists and fails properly
+   - Adding implementation without running the test first
+   - Refactoring when tests haven't been run or are failing
+
+### Critical Principle: Incremental Development
+
+Each step in TDD should address ONE specific issue:
+
+- Test fails "not defined" → Create empty stub/class only
+- Test fails "not a function" → Add method stub only
+- Test fails with assertion → Implement minimal logic only
+
+### Optional Pre-Phase: Spike Phase
+
+In rare cases where the problem space, interface, or expected behavior is unclear, a **Spike Phase** may be used **before the Red Phase**.
+This phase is **not part of the regular TDD workflow** and must only be applied under exceptional circumstances.
+
+- The goal of a Spike is **exploration and learning**, not implementation.
+- The code written during a Spike is **disposable** and **must not** be merged or reused directly.
+- Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**.
+- A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior.
+
+### General Information
+
+- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
+- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
+- 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.