@wbern/claude-instructions 1.9.0 → 1.11.0

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

@@ -24,6 +24,20 @@
     "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",
@@ -111,7 +125,7 @@
     "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",
+    "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

package/downloads/with-beads/commit.md

@@ -17,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/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/plan.md

@@ -21,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/worktree-add.md

@@ -1,6 +1,6 @@
 ---
-description: Add a new git worktree from branch name or GitHub issue URL, copy settings, install deps, and open in current IDE
-argument-hint: <branch-name-or-github-issue-url> [optional-base-branch]
+description: Add a new git worktree from branch name or issue URL, copy settings, install deps, and open in current IDE
+argument-hint: <branch-name-or-issue-url> [optional-base-branch]
 ---
 
 # Git Worktree Setup
@@ -18,31 +18,37 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 Create a new git worktree for branch: $ARGUMENTS
 
 <current_state>
-Current branch: !git branch --show-current`
-Current worktrees: !git worktree list`
-Remote branches: !git branch -r`
-Uncommitted changes: !git status --short`
+Current branch: `git branch --show-current`
+Current worktrees: `git worktree list`
+Remote branches: `git branch -r`
+Uncommitted changes: `git status --short`
 </current_state>
 
 <execution_steps>
 <step_0>
-  <description>Validate MCP dependencies</description>
-  <check_github_mcp>
-    <requirement>GitHub MCP server must be configured</requirement>
-    <fallback>If unavailable, use `gh` CLI commands</fallback>
-    <validation>
-      - Try listing available MCP resources
-      - If GitHub MCP not found, switch to CLI fallback
-      - Inform user about MCP configuration if needed
-    </validation>
-  </check_github_mcp>
-  <error_handling>
-    If MCP validation fails:
-    - Show clear error message
-    - Provide setup instructions
-    - Fallback to CLI if possible
-  </error_handling>
-  <purpose>Ensure required MCP dependencies are available before proceeding</purpose>
+  <description>Detect git hosting provider and available tools (only needed if argument is an issue URL)</description>
+  <condition>Only run this step if first argument looks like a git hosting URL</condition>
+<detect_provider>
+  <check_remote_url>git remote get-url origin</check_remote_url>
+  <identify_host>
+    - github.com → GitHub
+    - gitlab.com → GitLab
+    - bitbucket.org → Bitbucket
+    - Other → Ask user
+  </identify_host>
+</detect_provider>
+<check_available_tools>
+  <list_mcp_servers>Check which git-hosting MCP servers are available (github, gitlab, etc.)</list_mcp_servers>
+  <check_cli>Check if gh/glab CLI is available as fallback</check_cli>
+</check_available_tools>
+<select_tool>
+  <if_single_mcp>If only one relevant MCP available, confirm with user</if_single_mcp>
+  <if_multiple>Let user choose which tool to use</if_multiple>
+  <if_told_earlier>If user specified tool earlier in conversation, use that without asking again</if_told_earlier>
+  <store_as>$GIT_HOST_TOOL (e.g., "github_mcp", "gitlab_mcp", "gh_cli")</store_as>
+</select_tool>
+
+  <purpose>Detect git hosting provider and select appropriate tool for issue lookup</purpose>
 </step_0>
 
   <step_1>
@@ -70,30 +76,41 @@ Uncommitted changes: !git status --short`
   </step_1>
 
   <step_2>
-    <description>Parse the arguments</description>
+    <description>Determine default branch and parse arguments</description>
+    <find_default_branch>
+      <command>git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'</command>
+      <fallback>git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' '</fallback>
+      <store_as>$DEFAULT_BRANCH (typically "main" or "master")</store_as>
+    </find_default_branch>
     <input>The user-provided arguments</input>
-    <expected_format>branch-name-or-github-url [optional-base-branch]</expected_format>
+    <expected_format>branch-name-or-issue-url [optional-base-branch]</expected_format>
     <example>fix/issue-123-main-content-area-visually-clipped main</example>
-    <example_github_url><https://github.com/owner/project/issues/123> main</example_github_url>
-    <default_base_branch>main (if not specified)</default_base_branch>
-  </step_1>
+    <example_issue_url>https://github.com/owner/project/issues/123 main</example_issue_url>
+    <base_branch>Use provided base branch, or $DEFAULT_BRANCH if not specified</base_branch>
+  </step_2>
 
   <step_2_5>
-    <description>Handle GitHub issue URLs</description>
-    <condition>If first argument matches GitHub issue URL pattern</condition>
-    <url_detection>Check if argument contains "github.com" and "/issues/"</url_detection>
+    <description>Handle issue URLs from git hosting provider</description>
+    <condition>If first argument matches issue URL pattern (detected in step_0)</condition>
+    <url_detection>
+      <github>Check if argument contains "github.com" and "/issues/"</github>
+      <gitlab>Check if argument contains "gitlab.com" and "/-/issues/"</gitlab>
+      <bitbucket>Check if argument contains "bitbucket.org" and "/issues/"</bitbucket>
+    </url_detection>
     <url_parsing>
-      <pattern>https://github.com/{owner}/{repo}/issues/{issue_number}</pattern>
+      <github_pattern><https://github.com/{owner}/{repo}/issues/{issue_number}></github_pattern>
+      <gitlab_pattern><https://gitlab.com/{owner}/{repo}/-/issues/{issue_number}></gitlab_pattern>
+      <bitbucket_pattern><https://bitbucket.org/{owner}/{repo}/issues/{issue_number}></bitbucket_pattern>
       <extract>owner, repo, issue_number from URL</extract>
     </url_parsing>
     <fetch_issue_details>
-      <tool>mcp__github__issue_read</tool>
-      <method>get</method>
+      <tool>Use $GIT_HOST_TOOL from step_0</tool>
+      <method>get issue details</method>
       <parameters>owner, repo, issue_number</parameters>
     </fetch_issue_details>
     <generate_branch_name>
       <determine_type>Analyze issue title/labels to determine type (feat/fix/refactor/chore)</determine_type>
-      <format>{type}/{repo}-{issue_number}-{kebab-case-title}</format>
+      <format>{type}/issue-{issue_number}-{kebab-case-title}</format>
       <kebab_case>Convert title to lowercase, replace spaces/special chars with hyphens</kebab_case>
       <sanitization>
         <rule>Always use lowercase for branch names</rule>
@@ -116,12 +133,12 @@ Uncommitted changes: !git status --short`
       <title>"Fix duplicate items in list view"</title>
       <generated>fix/issue-456-duplicate-items-in-list-view</generated>
     </examples>
-  </step_1_5>
+  </step_2_5>
 
   <step_3>
     <description>Add all files and stash uncommitted changes if any exist</description>
     <condition>If output is not empty (has uncommitted changes)</condition>
-    <command>git add -A && git stash push -m "Worktree switch: Moving changes to ${branch_name}"</chained_command>
+    <command>git add -A && git stash push -m "Worktree switch: Moving changes to ${branch_name}"</command>
     <purpose>Preserve work in progress before switching worktrees</purpose>
     <note>Remember stash was created for later restoration</note>
   </step_3>
@@ -140,20 +157,20 @@ Uncommitted changes: !git status --short`
   <step_5>
     <description>Fetch latest changes from remote</description>
     <command>git fetch origin</command>
-    <purpose>Ensure we have the latest remote branches and main branch state</purpose>
-    <note>This ensures new worktrees are created from the most recent main branch</note>
-  </step_6>
+    <purpose>Ensure we have the latest remote branches and default branch state</purpose>
+    <note>This ensures new worktrees are created from the most recent default branch</note>
+  </step_5>
 
-  <step_7>
+  <step_6>
     <description>Check if branch exists on remote</description>
     <command>git branch -r | grep "origin/${branch_name}"</command>
     <decision>
       <if_exists>Branch exists on remote - will checkout existing branch</if_exists>
       <if_not_exists>Branch does not exist - will create new branch from base</if_not_exists>
     </decision>
-  </step_5>
+  </step_6>
 
-  <step_6>
+  <step_7>
     <description>Create the worktree</description>
     <option_a_new_branch>
       <condition>Remote branch does NOT exist</condition>
@@ -247,7 +264,7 @@ EOF</create_file_command>
     </ide_specific_behavior>
     <purpose>Launch development environment for the new worktree using detected IDE</purpose>
     <confirmation_message>Opening worktree in ${ide_name}</confirmation_message>
-  </step_11>
+  </step_13>
 </execution_steps>
 
 <important_notes>
@@ -262,4 +279,11 @@ EOF</create_file_command>
 - Uncommitted changes are automatically stashed and moved to the new worktree
 - Your work-in-progress seamlessly transfers to the new branch
 - IDE detection fallback: checks available editors and uses priority order
+
+Limitations:
+
+- Assumes remote is named "origin" (most common convention)
+- Supports macOS and Linux only (no Windows support)
+- Requires MCP server or CLI for git hosting provider when using issue URLs (GitHub, GitLab, etc.)
+- Dependency install command is pnpm (modify for npm/yarn if needed)
 </important_notes>