@wbern/claude-instructions 1.0.1

package/downloads/without-beads/plan.md

@@ -0,0 +1,107 @@
+---
+allowed-tools: Read, Glob, Grep, Task, AskUserQuestion, mcp__github__issue_read, mcp__github__search_issues
+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>
+---
+
+# Plan: PRD-Informed Task Planning for TDD
+
+Create structured implementation plan that bridges product thinking (PRD) with test-driven development.
+
+## 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
+
+## Input
+
+$ARGUMENTS
+
+(If no input provided, check conversation context)
+
+## 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")
+4. **Empty** - use conversation context
+
+### GitHub Issue Integration
+
+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>`
+
+```
+GitHub MCP not configured!
+See: https://github.com/modelcontextprotocol/servers/tree/main/src/github
+Trying GitHub CLI fallback...
+```
+
+**Step 3: Use Issue as Discovery Input**
+- Title → Feature name
+- Description → Problem statement and context
+- Labels → Type/priority hints
+- Comments → Additional requirements and discussion
+- Linked issues → Dependencies
+
+Extract from GitHub issue:
+- Problem statement and context
+- Acceptance criteria (if present)
+- Technical notes (if present)
+- Related issues/dependencies
+
+## 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?
+
+**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
+
+
+## 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)
+
+
+## Integration with Other Commands
+
+- **Before /plan**: Use `/spike` if you need technical exploration first
+- **After /plan**: Use `/red` to start TDD on first task

package/downloads/without-beads/red.md

@@ -0,0 +1,85 @@
+---
+description: Execute TDD Red Phase - write ONE failing test
+---
+
+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
+
+## 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/without-beads/refactor.md

@@ -0,0 +1,87 @@
+---
+allowed-tools: Read, Glob, Grep, Bash(pnpm test:*), Bash(pnpm:*)
+description: Execute TDD Refactor Phase - improve code structure while keeping tests green
+argument-hint: <refactoring description>
+---
+
+Apply this document (specifically the Refactor phase), 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/without-beads/ship.md

@@ -0,0 +1,85 @@
+---
+allowed-tools: mcp__github__*, Bash(git:*)
+description: Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)
+argument-hint: [optional-commit-message]
+---
+
+# Ship - Direct Merge to Main
+
+## 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 - SHIP**
+
+> 🎯 **Cursor says**: It's 2025! Not everything needs a PR. Ship small, obvious changes directly.
+
+Ship is for small, obvious changes that don't need code review. Examples:
+- Typo fixes
+- Formatting changes
+- Documentation updates
+- Obvious bug fixes
+- Dependency updates with passing tests
+
+## Prerequisites
+
+Before shipping directly to main:
+1. All tests must pass
+2. Linter must pass
+3. Changes must be small and low-risk
+4. CI must be green (if configured)
+
+## Workflow
+
+Current branch status:
+!`git status`
+
+Recent commits:
+!`git log --oneline -5`
+
+Arguments: $ARGUMENTS
+
+**Process:**
+
+1. **Verify Change Size**: Check git diff to ensure changes are small and focused
+   !`git diff --stat main`
+
+2. **Run Tests**: Ensure all tests pass
+   !`npm test` or !`yarn test` or appropriate test command for the project
+
+3. **Run Linter**: Ensure code quality checks pass
+   !`npm run lint` or !`yarn lint` or appropriate lint command (if available)
+
+4. **Safety Check**: Confirm with user that this is truly a ship-worthy change:
+   - Is this a small, obvious change?
+   - Do all tests pass?
+   - Is CI green?
+   
+   If ANY of these are "no", suggest using `/show` or `/ask` instead.
+
+5. **Merge to Main**: If all checks pass and user confirms:
+   ```bash
+   git checkout main
+   git pull origin main
+   git merge --ff-only [feature-branch] || git merge [feature-branch]
+   git push origin main
+   ```
+
+6. **Cleanup**: Delete the feature branch
+   ```bash
+   git branch -d [feature-branch]
+   git push origin --delete [feature-branch]
+   ```
+
+7. **Notify**: Show summary of what was shipped
+
+## Safety Rails
+
+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
+
+

package/downloads/without-beads/show.md

@@ -0,0 +1,99 @@
+---
+allowed-tools: mcp__github__*, Bash(git:*)
+description: Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)
+argument-hint: [optional-pr-title-and-description]
+---
+
+# Show - Visible Merge with Optional Feedback
+
+## 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 - SHOW**
+
+> 🚀 **Cursor says**: Not every change needs a traditional review. Show your work, then merge.
+
+Show is for changes that teammates should see, but don't require approval. Examples:
+- Refactoring with test coverage
+- New features with comprehensive tests
+- Performance improvements
+- Non-breaking API changes
+
+## Prerequisites
+
+Before using show:
+1. All tests must pass
+2. Changes should have good test coverage
+3. Changes should be non-breaking or backward compatible
+4. CI must be green
+
+## Workflow
+
+Current branch status:
+!`git status`
+
+Recent commits:
+!`git log --oneline -5`
+
+Arguments: $ARGUMENTS
+
+**Process:**
+
+1. **Verify Quality**: Check that changes meet show criteria
+   - Run tests: !`npm test` or !`yarn test` or appropriate test command
+   - Check coverage is maintained or improved
+   - Verify no breaking changes
+
+2. **Create Show PR**: Create a PR that will auto-merge after a short window
+   - Title: conventional commits format, prefixed with `[SHOW]`
+   - Description: Clear explanation of what changed and why
+   - Add label: "show" or "auto-merge"
+   - Set auto-merge if GitHub setting allows
+
+3. **Configure Auto-Merge**:
+   - If GitHub Actions is configured, set to auto-merge after CI passes
+   - If not, provide instructions to merge after 1-2 hours of visibility
+   - Add notice that feedback is welcome but not required
+
+4. **PR Description Template**:
+   ```markdown
+   ## 🚀 Show - Auto-merging after CI
+
+   **This is a SHOW PR**: Changes are ready to merge but shared for visibility.
+   Feedback welcome but not required. Will auto-merge when CI passes.
+
+   <!--
+     References: [link to relevant issues]
+   -->
+
+   ### What changed
+   [Brief description]
+
+   ### Why
+   [Rationale for change]
+
+   ### Test coverage
+   - [ ] All tests pass
+   - [ ] Coverage maintained/improved
+   - [ ] No breaking changes
+   ```
+
+5. **Monitoring**: Check PR status and auto-merge when ready
+
+## Decision Guide
+
+Use **Show** when:
+- ✅ Tests are comprehensive
+- ✅ Changes are non-breaking
+- ✅ You're confident in the approach
+- ✅ Team should be aware of the change
+
+Use **/ship** instead if: change is tiny and obvious (typo, formatting)
+
+Use **/ask** instead if: change needs discussion, breaks APIs, or you're uncertain
+
+

package/downloads/without-beads/spike.md

@@ -0,0 +1,89 @@
+---
+allowed-tools: Read, Glob, Grep, Task
+description: Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
+argument-hint: <exploration description>
+---
+
+SPIKE 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/without-beads/summarize.md

@@ -0,0 +1,30 @@
+---
+allowed-tools: AskUserQuestion, mcp__beads__list, mcp__beads__stats
+description: Summarize conversation progress and next steps
+---
+
+Create a concise summary of the current conversation suitable for transferring context to a new conversation.
+
+## Summary Structure
+
+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
+
+## Output Format
+
+Keep the summary concise and actionable - suitable for pasting into a new conversation to quickly restore context without needing the full conversation history.
+

package/downloads/without-beads/tdd.md

@@ -0,0 +1,89 @@
+---
+allowed-tools: Read, Glob, Grep, Task
+description: Remind agent about TDD approach and continue conversation
+argument-hint: [optional-response-to-last-message]
+---
+
+# TDD Reminder
+
+## 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
+
+## 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.
+
+## Continue Conversation
+
+User response to the last message: $ARGUMENTS
+
+Please continue with TDD approach based on the above response.