@wbern/claude-instructions 1.8.1 → 1.10.0

package/downloads/with-beads/ask.md

@@ -1,6 +1,5 @@
 ---
-allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
-description: Request team review and approval - for complex changes needing discussion (OK fine, traditional PRs still have their place - Cursor)
+description: Request team review and approval - for complex changes needing discussion
 argument-hint: [optional-pr-title-and-description]
 ---
 
@@ -18,8 +17,6 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 
 **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

package/downloads/with-beads/beepboop.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Grep, Glob
 description: Communicate AI-generated content with transparent attribution
 argument-hint: <task-description>
 ---

package/downloads/with-beads/busycommit.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Bash(pnpm test:*), Bash(pnpm lint:*)
 description: Create multiple atomic git commits, one logical change at a time
 argument-hint: [optional-commit-description]
 ---
@@ -18,6 +17,22 @@ Create multiple atomic git commits, committing the smallest possible logical uni
 
 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

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

@@ -0,0 +1,248 @@
+---
+description: Code review using dynamic category detection and domain-specific analysis
+argument-hint: (optional) [branch, PR#, or PR URL] - defaults to current branch
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git rev-parse:*)
+  - Bash(git merge-base:*)
+  - Bash(git 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
+
+- Coverage: Edge cases, error paths, boundaries
+- Assertion quality: Specific assertions, not just "no error"
+- Flaky patterns: Timing dependencies, order dependencies, shared state
+
+### 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,96 +1,138 @@
 {
   "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 (OK fine, traditional PRs still have their place - Cursor)",
-    "category": "Workflow",
-    "order": 4
+    "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",
-    "category": "TDD Cycle",
+    "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",
-    "category": "TDD Cycle",
+    "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
   },
   "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",
-    "category": "TDD Cycle",
+    "hint": "Failing test",
+    "category": "Test-Driven Development",
     "order": 2
   },
   "refactor.md": {
     "description": "Execute TDD Refactor Phase - improve code structure while keeping tests green",
-    "category": "TDD Cycle",
+    "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 (Cursor's modern alternative to PRs)",
-    "category": "Workflow",
-    "order": 2
+    "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 (Cursor's modern workflow)",
-    "category": "Workflow",
-    "order": 3
+    "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",
-    "category": "TDD Cycle",
+    "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.md": {
     "description": "Remind agent about TDD approach and continue conversation",
-    "category": "Utilities",
+    "hint": "TDD reminder",
+    "category": "Test-Driven Development",
     "order": 1
   },
   "worktree-add.md": {
     "description": "Add a new git worktree from branch name or GitHub 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
   }

package/downloads/with-beads/commit.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Bash(pnpm test:*), Bash(pnpm lint:*)
 description: Create a git commit following project standards
 argument-hint: [optional-commit-description]
 ---
@@ -18,6 +17,22 @@ Create a git commit following project standards
 
 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

package/downloads/with-beads/cycle.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
 argument-hint: <feature or requirement description>
 ---

package/downloads/with-beads/gap.md

@@ -19,6 +19,7 @@ Analyze the current conversation context and identify things that have not yet b
 2. **Unused variables/results** - Values that were captured but never used
 3. **Missing tests** - Functionality without test coverage
 4. **Open issues** - Beads issues that are still open or in progress
+
 5. **User requests** - Things the user asked for that weren't fully completed
 6. **TODO comments** - Any TODOs mentioned in conversation
 7. **Error handling gaps** - Missing error cases or edge cases

package/downloads/with-beads/green.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Green Phase - write minimal implementation to pass the failing test
 argument-hint: <implementation description>
 ---

package/downloads/with-beads/issue.md

@@ -1,5 +1,4 @@
 ---
-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]
 ---

package/downloads/with-beads/plan.md

@@ -1,5 +1,4 @@
 ---
-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>
 ---
@@ -22,8 +21,7 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 
 $ARGUMENTS
 
-(If no input provided, check conversation context or run `bd ready` to see existing work
-)
+(If no input provided, check conversation context or run `bd ready` to see existing work)
 
 ## Input Processing
 

package/downloads/with-beads/pr.md

@@ -0,0 +1,82 @@
+---
+description: Creates a pull request using GitHub MCP
+argument-hint: [optional-pr-title-and-description]
+---
+
+# Create Pull Request
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
+
+Create a pull request for the current branch using GitHub MCP tools.
+
+## Workflow
+
+Current branch status:
+!`git status`
+
+Recent commits:
+!`git log --oneline -5`
+
+Arguments: $ARGUMENTS
+
+**Process:**
+
+1. **Ensure Branch is Ready**:
+   !`git status`
+   - Commit all changes
+   - Push to remote: `git push origin [branch-name]`
+
+2. **Create PR**: Create a well-formatted pull request
+
+   Title: conventional commits format, like `feat(#123): add user authentication`
+
+   Description template:
+
+   ```markdown
+   <!--
+     Are there any relevant issues / PRs / mailing lists discussions?
+     Please reference them here.
+   -->
+
+   ## References
+
+   - [links to github issues referenced in commit messages]
+
+   ## Summary
+
+   [Brief description of changes]
+
+   ## Test Plan
+
+   - [ ] Tests pass
+   - [ ] Manual testing completed
+   ```
+
+3. **Set Base Branch**: Default to main unless specified otherwise
+
+4. **Link Issues**: Reference related issues found in commit messages
+
+## Use GitHub MCP Tools
+
+1. Check current branch and ensure it's pushed
+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
+
+### 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/red.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Red Phase - write ONE failing test
 argument-hint: [optional additional info]
 ---

package/downloads/with-beads/refactor.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Glob, Grep, Bash(pnpm test:*)
 description: Execute TDD Refactor Phase - improve code structure while keeping tests green
 argument-hint: <refactoring description>
 ---

package/downloads/with-beads/ship.md

@@ -1,6 +1,5 @@
 ---
-allowed-tools: Bash(git status:*), Bash(git log:*), Bash(git diff:*), Bash(git checkout:*), Bash(git pull:*), Bash(git merge:*), Bash(git push:*), Bash(git branch:*)
-description: Ship code directly to main - for small, obvious changes that don't need review (Cursor's modern alternative to PRs)
+description: Ship code directly to main - for small, obvious changes that don't need review
 argument-hint: [optional-commit-message]
 ---
 
@@ -18,8 +17,6 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 
 **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

package/downloads/with-beads/show.md

@@ -1,6 +1,5 @@
 ---
-allowed-tools: mcp__github__create_pull_request, mcp__github__update_pull_request, Bash(git status:*), Bash(git log:*), Bash(git push:*), Bash(git branch:*)
-description: Show code to team with auto-merge - for changes that should be visible but don't need approval (Cursor's modern workflow)
+description: Show code to team with auto-merge - for changes that should be visible but don't need approval
 argument-hint: [optional-pr-title-and-description]
 ---
 
@@ -18,8 +17,6 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 
 **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

package/downloads/with-beads/spike.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: Read, Glob, Grep, Task
 description: Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
 argument-hint: <exploration description>
 ---

package/downloads/with-beads/summarize.md

@@ -1,5 +1,4 @@
 ---
-allowed-tools: AskUserQuestion
 description: Summarize conversation progress and next steps
 argument-hint: [optional additional info]
 ---