@wbern/claude-instructions 1.20.0 → 2.0.0

package/downloads/with-beads/ask.md

@@ -1,144 +0,0 @@
----
-description: Request team review and approval - for complex changes needing discussion
-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
-
-Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
-
-**Ship/Show/Ask Pattern - ASK**
-
-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

@@ -1,47 +0,0 @@
----
-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 is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
-
-## 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/busycommit.md

@@ -1,78 +0,0 @@
----
-description: Create multiple atomic git commits, one logical change at a time
-argument-hint: [optional-commit-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).
-
-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"
-```
-
-## Atomic Commit Approach
-
-Each commit should represent ONE logical change. Do NOT bundle multiple unrelated changes into one commit.
-
-- Identify the smallest atomic units of change
-- For EACH atomic unit: stage only those files/hunks, commit, verify
-- Use `git add -p` to stage partial file changes when a file contains multiple logical changes
-- Repeat until all changes are committed
-- It is OK to create multiple commits without stopping - keep going until `git status` shows clean
-
-## Multi-Commit Example
-
-If a single file contains multiple unrelated changes, use `git add -p` to stage hunks interactively:
-
-```bash
-# Stage only the validation-related hunks from the file
-git add -p src/user-service.ts
-# Select 'y' for validation hunks, 'n' for others
-git commit -m "feat(#123): add email format validation"
-
-# Stage the error handling hunks
-git add -p src/user-service.ts
-git commit -m "fix(#124): handle null user gracefully"
-
-# Stage remaining changes
-git add src/user-service.ts
-git commit -m "refactor: extract user lookup to helper"
-```

package/downloads/with-beads/code-review.md

@@ -1,263 +0,0 @@
----
-description: Code review using dynamic category detection and domain-specific analysis
-argument-hint: (optional) [branch, PR#, or PR URL] - defaults to current branch
----
-
-## 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).
-
-# Code Review
-
-Perform a code review using dynamic category detection.
-
-## Phase 0: Setup & Categorization
-
-### Determine What to Review
-
-Parse the argument to determine the review target:
-
-| Input | Action |
-|-------|--------|
-| No argument | Detect divergence point, confirm scope with user |
-| Branch name | Use specified branch as base |
-| PR number (e.g., `123`) | Fetch PR diff from GitHub |
-| PR URL (e.g., `https://github.com/owner/repo/pull/123`) | Extract PR number and fetch diff |
-
-**For GitHub PRs:**
-
-1. Try GitHub MCP first: `mcp__github__pull_request_read` with `method: "get_diff"`
-2. Fall back to `gh` CLI: `gh pr diff <number>`
-3. If neither works, report error and stop
-
-**For local branches (no argument or branch name provided):**
-
-1. **Get current branch**: `git rev-parse --abbrev-ref HEAD`
-
-2. **Check for uncommitted changes**: `git status --porcelain`
-   - If output is non-empty, note that uncommitted changes exist
-
-3. **Detect divergence point** (skip if branch name was provided as argument):
-   - Get all local branches except current: `git branch --format='%(refname:short)'`
-   - For each branch, find merge-base: `git merge-base HEAD <branch>`
-   - Count commits from merge-base to HEAD: `git rev-list --count <merge-base>..HEAD`
-   - The branch with the **fewest commits back** (closest merge-base) is the likely parent
-   - If no other branches exist, fall back to `main`, `master`, or `develop` if they exist as remote tracking branches
-
-4. **Confirm scope with user** using `AskUserQuestion`:
-
-   **Question 1 - "Review scope"** (header: "Base branch"):
-   - Option A: `From <detected-branch>` — "Review N commits since diverging from <branch>"
-   - Option B: `Different branch` — "Specify another branch to compare against"
-   - Option C: `Uncommitted only` — "Review only staged/unstaged changes, skip committed work"
-
-   **Question 2 - "Include uncommitted?"** (header: "Uncommitted", only ask if uncommitted changes exist AND user didn't pick option C):
-   - Option A: `Yes` — "Include N staged/unstaged files in review"
-   - Option B: `No` — "Review only committed changes"
-
-5. **Collect changed files** based on user selection:
-   - From branch: `git diff --name-only <base>...HEAD`
-   - Uncommitted unstaged: `git diff --name-only`
-   - Uncommitted staged: `git diff --name-only --cached`
-   - Combine and deduplicate the file list
-
-6. **If no changes**: Report "Nothing to review" and stop
-
-### Categorize Files
-
-Check for CLAUDE.md - if it exists, note any project-specific review patterns.
-
-Categorize each changed file into ONE primary category based on these patterns:
-
-| Category | File Patterns |
-|----------|---------------|
-| Frontend/UI | `*.tsx`, `*.jsx`, `components/`, `pages/`, `views/`, `*.vue` |
-| Frontend/Styling | `*.css`, `*.scss`, `*.less`, `styles/`, `*.tailwind*`, `*.styled.*` |
-| Backend/API | `routes/`, `api/`, `controllers/`, `services/`, `*.controller.*`, `*.service.*`, `*.resolver.*` |
-| Backend/Data | `migrations/`, `models/`, `prisma/`, `schema.*`, `*.model.*`, `*.entity.*` |
-| Tooling/Config | `scripts/`, `*.config.*`, `package.json`, `tsconfig.*`, `vite.*`, `webpack.*`, `eslint.*` |
-| CI/CD | `.github/`, `.gitlab-ci.*`, `Dockerfile`, `docker-compose.*`, `*.yml` in CI paths |
-| Tests | `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*` |
-| Docs | `*.md`, `docs/`, `README*`, `CHANGELOG*` |
-
-Output the categorization:
-
-```
-## Categorization
-
-Base branch: <branch>
-Total files changed: <n>
-
-| Category | Files |
-|----------|-------|
-| <category> | <count> |
-...
-```
-
-## Phase 1: Branch Brief
-
-From the diff and recent commit messages (`git log <base>...HEAD --oneline`), infer:
-
-- **Goal**: What this branch accomplishes (1-3 sentences)
-- **Constraints**: Any implied requirements (security, performance, backwards compatibility)
-- **Success checklist**: What must work after this change, what must not break
-
-```
-## Branch Brief
-
-**Goal**: ...
-**Constraints**: ...
-**Checklist**:
-- [ ] ...
-```
-
-## Phase 2: Category Reviews
-
-For each detected category with changes, run a targeted review. Skip categories with no changes.
-
-### Frontend/UI Review Criteria
-
-- Accessibility: ARIA attributes, keyboard navigation, screen reader support
-- Component patterns: Composition, prop drilling, context usage
-- State management: Unnecessary re-renders, stale closures
-- Performance: memo/useMemo/useCallback usage, lazy loading, bundle impact
-
-### Frontend/Styling Review Criteria
-
-- Responsive design: Breakpoints, mobile-first
-- Design system: Token usage, consistent spacing/colors
-- CSS specificity: Overly specific selectors, !important usage
-- Theme support: Dark mode, CSS variables
-
-### Backend/API Review Criteria
-
-- Input validation: Sanitization, type checking, bounds
-- Security: Authentication checks, authorization, injection risks
-- Error handling: Proper status codes, meaningful messages, logging
-- Performance: N+1 queries, missing indexes, pagination
-
-### Backend/Data Review Criteria
-
-- Migration safety: Reversibility, data preservation
-- Data integrity: Constraints, foreign keys, nullability
-- Index usage: Queries have appropriate indexes
-- Backwards compatibility: Existing data still works
-
-### Tooling/Config Review Criteria
-
-- Breaking changes: Does this affect developer workflow?
-- Dependency compatibility: Version conflicts, peer deps
-- Build performance: Added build time, bundle size
-
-### CI/CD Review Criteria
-
-- Secrets exposure: Credentials in logs, env vars
-- Pipeline efficiency: Caching, parallelization
-- Failure handling: Notifications, rollback strategy
-
-### 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 Review Criteria
-
-- Technical accuracy: Code examples work, APIs documented correctly
-- Completeness: All new features documented
-- Clarity: Easy to follow, good examples
-
-**Output format per category:**
-
-```
-## <Category> Review (<n> files)
-
-### file:line - [blocker|risky|nit] Title
-Description of the issue and why it matters.
-Suggested fix or question to investigate.
-
-...
-```
-
-## Phase 3: Cross-Cutting Analysis
-
-After reviewing all categories, check for cross-cutting issues:
-
-- API changed but tests didn't update?
-- New feature but no documentation?
-- Migration added but no rollback tested?
-- Config changed but README not updated?
-- Security-sensitive code without corresponding test?
-
-```
-## Cross-Cutting Issues
-
-- [ ] <issue description>
-...
-```
-
-## Phase 4: Summary
-
-### PR Description (draft)
-
-Provide a ready-to-paste PR description:
-
-```
-## What changed
-- <by category, 1-2 bullets each>
-
-## Why
-- <motivation>
-
-## Testing
-- <how to verify>
-
-## Notes
-- <migration steps, breaking changes, etc.>
-```
-
-### Review Checklist
-
-```
-## Before Merge
-
-### Blockers (must fix)
-- [ ] ...
-
-### Risky (highlight to reviewers)
-- [ ] ...
-
-### Follow-ups (can defer)
-- [ ] ...
-```
-
----
-
-Review target (branch name, PR number, or PR URL - leave empty for current branch): $ARGUMENTS

package/downloads/with-beads/commands-metadata.json

@@ -1,155 +0,0 @@
-{
-  "add-command.md": {
-    "description": "Guide for creating new slash commands",
-    "hint": "Create command",
-    "category": "Utilities",
-    "order": 3
-  },
-  "ask.md": {
-    "description": "Request team review and approval - for complex changes needing discussion",
-    "hint": "Request review",
-    "category": "Ship / Show / Ask",
-    "order": 3,
-    "selectedByDefault": false
-  },
-  "beepboop.md": {
-    "description": "Communicate AI-generated content with transparent attribution",
-    "hint": "AI attribution",
-    "category": "Utilities",
-    "order": 2
-  },
-  "busycommit.md": {
-    "description": "Create multiple atomic git commits, one logical change at a time",
-    "hint": "Atomic commits",
-    "category": "Workflow",
-    "order": 2
-  },
-  "code-review.md": {
-    "description": "Code review using dynamic category detection and domain-specific analysis",
-    "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:*)"
-    ]
-  },
-  "commit.md": {
-    "description": "Create a git commit following project standards",
-    "hint": "Git commit",
-    "category": "Workflow",
-    "order": 1
-  },
-  "cycle.md": {
-    "description": "Execute complete TDD cycle - Red, Green, and Refactor phases in sequence",
-    "hint": "Full TDD cycle",
-    "category": "Test-Driven Development",
-    "order": 5
-  },
-  "gap.md": {
-    "description": "Analyze conversation context for unaddressed items and gaps",
-    "hint": "Find gaps",
-    "category": "Workflow",
-    "order": 11
-  },
-  "green.md": {
-    "description": "Execute TDD Green Phase - write minimal implementation to pass the failing test",
-    "hint": "Make it pass",
-    "category": "Test-Driven Development",
-    "order": 3
-  },
-  "issue.md": {
-    "description": "Analyze GitHub issue and create TDD implementation plan",
-    "hint": "Analyze issue",
-    "category": "Planning",
-    "order": 1
-  },
-  "kata.md": {
-    "description": "Generate a TDD practice challenge with boilerplate test setup",
-    "hint": "Practice kata",
-    "category": "Utilities",
-    "order": 10,
-    "_requested-tools": [
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "WebFetch(domain:api.github.com)"
-    ]
-  },
-  "plan.md": {
-    "description": "Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria",
-    "hint": "Plan feature",
-    "category": "Planning",
-    "order": 2
-  },
-  "pr.md": {
-    "description": "Creates a pull request using GitHub MCP",
-    "hint": "Create PR",
-    "category": "Workflow",
-    "order": 5
-  },
-  "red.md": {
-    "description": "Execute TDD Red Phase - write ONE failing test",
-    "hint": "Failing test",
-    "category": "Test-Driven Development",
-    "order": 2
-  },
-  "refactor.md": {
-    "description": "Execute TDD Refactor Phase - improve code structure while keeping tests green",
-    "hint": "Clean up code",
-    "category": "Test-Driven Development",
-    "order": 4
-  },
-  "ship.md": {
-    "description": "Ship code directly to main - for small, obvious changes that don't need review",
-    "hint": "Direct to main",
-    "category": "Ship / Show / Ask",
-    "order": 1,
-    "selectedByDefault": false
-  },
-  "show.md": {
-    "description": "Show code to team with auto-merge - for changes that should be visible but don't need approval",
-    "hint": "Auto-merge PR",
-    "category": "Ship / Show / Ask",
-    "order": 2,
-    "selectedByDefault": false
-  },
-  "spike.md": {
-    "description": "Execute TDD Spike Phase - exploratory coding to understand problem space before TDD",
-    "hint": "Explore first",
-    "category": "Test-Driven Development",
-    "order": 1
-  },
-  "summarize.md": {
-    "description": "Summarize conversation progress and next steps",
-    "hint": "Summarize chat",
-    "category": "Workflow",
-    "order": 10
-  },
-  "tdd-review.md": {
-    "description": "Review test suite quality against FIRST principles and TDD anti-patterns",
-    "hint": "Review tests",
-    "category": "Test-Driven Development",
-    "order": 45
-  },
-  "tdd.md": {
-    "description": "Remind agent about TDD approach and continue conversation",
-    "hint": "TDD reminder",
-    "category": "Test-Driven Development",
-    "order": 1
-  },
-  "worktree-add.md": {
-    "description": "Add a new git worktree from branch name or issue URL, copy settings, install deps, and open in current IDE",
-    "hint": "Add worktree",
-    "category": "Worktree Management",
-    "order": 1
-  },
-  "worktree-cleanup.md": {
-    "description": "Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees",
-    "hint": "Cleanup worktree",
-    "category": "Worktree Management",
-    "order": 2
-  }
-}