@wbern/claude-instructions 1.9.0 → 1.11.0

package/downloads/with-beads/worktree-cleanup.md

@@ -20,54 +20,71 @@ Clean up merged worktrees by finding the oldest merged branch, consolidating set
 Additional info: $ARGUMENTS
 
 <current_state>
-Current branch: !git branch --show-current`
-Current worktrees: !git worktree list`
+Current branch: `git branch --show-current`
+Current worktrees: `git worktree list`
 </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</description>
+<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 PR verification</purpose>
 </step_0>
 
   <step_1>
-    <description>Verify we're in main branch</description>
-    <check_command>git branch --show-current</check_command>
-    <required_branch>main</required_branch>
-    <error_if_not_main>Exit with error message: "This command must be run from the main branch"</error_if_not_main>
-    <purpose>Ensure we're consolidating to the main worktree</purpose>
+    <description>Determine default branch and verify we're on it</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>
+    <check_current_branch>git branch --show-current</check_current_branch>
+    <verify>Current branch must equal $DEFAULT_BRANCH</verify>
+    <error_if_not_default>Exit with error: "This command must be run from the default branch ($DEFAULT_BRANCH)"</error_if_not_default>
+    <purpose>Ensure we're consolidating to the default branch worktree</purpose>
   </step_1>
 
   <step_2>
     <description>Get list of all worktrees</description>
     <command>git worktree list --porcelain</command>
     <parse_output>Extract worktree paths and branch names</parse_output>
-    <exclude_main>Filter out the main worktree from cleanup candidates</exclude_main>
+    <exclude_default>Filter out the default branch worktree from cleanup candidates</exclude_default>
     <purpose>Identify all worktrees that could potentially be cleaned up</purpose>
   </step_2>
 
   <step_3>
     <description>Find oldest worktree by directory age</description>
     <get_worktree_ages>
-      <command_macos>git worktree list | grep -v "main" | awk '{print $1}' | while read path; do /usr/bin/stat -f "%Sm|%N" -t "%Y-%m-%d %H:%M:%S" "$path" 2>/dev/null; done | sort</command_macos>
-      <command_linux>git worktree list | grep -v "main" | awk '{print $1}' | xargs stat -c "%y|%n" | sort</command_linux>
+      <detect_platform>uname -s (returns "Darwin" for macOS, "Linux" for Linux)</detect_platform>
+      <command_macos>git worktree list | grep -v "\[$DEFAULT_BRANCH\]" | awk '{print $1}' > /tmp/worktrees-$$.txt && while IFS= read -r path; do echo "$(/usr/bin/stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$path" 2>/dev/null)|$path"; done < /tmp/worktrees-$$.txt | sort; rm -f /tmp/worktrees-$$.txt</command_macos>
+      <command_linux>git worktree list | grep -v "\[$DEFAULT_BRANCH\]" | awk '{print $1}' > /tmp/worktrees-$$.txt && while IFS= read -r path; do echo "$(stat -c '%y' "$path" 2>/dev/null | cut -d. -f1)|$path"; done < /tmp/worktrees-$$.txt | sort; rm -f /tmp/worktrees-$$.txt</command_linux>
       <purpose>List all worktrees sorted by directory modification time (oldest first)</purpose>
-      <note>Use full path /usr/bin/stat on macOS, regular stat on Linux.</note>
+      <critical_notes>
+        - Replace $DEFAULT_BRANCH with value from step_1 (e.g., "main" or "master")
+        - grep "\[branch\]" matches branch name in brackets, not paths containing the word
+        - Temp file approach avoids subshell parsing issues with piped while-loops
+        - /usr/bin/stat on macOS avoids homebrew stat conflicts
+      </critical_notes>
+      <expected_output_format>YYYY-MM-DD HH:MM|/full/path/to/worktree (oldest first)</expected_output_format>
     </get_worktree_ages>
     <filter_recent>
       <exclude_new>For worktrees created within the last 24 hours, let user know that this worktree might not be worth cleaning</exclude_new>
@@ -78,28 +95,27 @@ Current worktrees: !git worktree list`
       <important_note>DO NOT use "git branch --merged" to check merge status - it's unreliable</important_note>
       <proceed_to_pr_check>Move directly to step 4 to verify PR merge status instead</proceed_to_pr_check>
     </select_oldest>
-    <purpose>Identify oldest worktree candidate - actual merge verification happens via GitHub PR in next step</purpose>
+    <purpose>Identify oldest worktree candidate - actual merge verification happens via PR/MR in next step</purpose>
   </step_3>
 
   <step_4>
-    <description>Verify GitHub PR merge status (primary merge verification)</description>
+    <description>Verify PR/MR merge status (primary merge verification)</description>
     <determine_repo>
       <check_remote>git remote get-url origin</check_remote>
-      <parse_repo>Extract owner/repo from GitHub URL</parse_repo>
-      <fallback>Use project repository from git remote (owner/repo format)</fallback>
+      <parse_repo>Extract owner/repo from remote URL</parse_repo>
     </determine_repo>
     <search_pr>
-      <tool>mcp__github__search_pull_requests</tool>
-      <query>repo:owner/repo head:{branch_name} base:main</query>
-      <purpose>Find PR for this branch targeting main</purpose>
+      <tool>Use $GIT_HOST_TOOL from step_0 (e.g., mcp__github__search_pull_requests, mcp__gitlab__*, or gh CLI)</tool>
+      <query>Find PRs/MRs where head={branch_name} and base=$DEFAULT_BRANCH</query>
+      <purpose>Find PR/MR for this branch targeting default branch</purpose>
       <important>This is the PRIMARY way to verify if a branch was merged - NOT git commands</important>
     </search_pr>
     <verify_pr_merged>
       <if_pr_found>
-        <get_pr_details>Use mcp__github__pull_request_read to get full PR info</get_pr_details>
-        <confirm_merged>Verify PR state is "closed" AND merged_at is not null AND base is "main"</confirm_merged>
-        <extract_issue_number>Look for issue references in PR title/body (e.g., #14533, owner/repo#14533)</extract_issue_number>
-        <if_merged>Proceed with cleanup - this branch was definitively merged to main</if_merged>
+        <get_pr_details>Use $GIT_HOST_TOOL to get full PR/MR info</get_pr_details>
+        <confirm_merged>Verify PR/MR state is "closed"/"merged" AND merged_at is not null AND base is "$DEFAULT_BRANCH"</confirm_merged>
+        <extract_issue_number>Look for issue references in PR title/body (e.g., #123, owner/repo#123)</extract_issue_number>
+        <if_merged>Proceed with cleanup - this branch was definitively merged to default branch</if_merged>
         <if_not_merged>
           <skip_worktree>This worktree is NOT merged - continue to next oldest worktree</skip_worktree>
           <repeat_from_step_3>Go back and find the next oldest worktree to check</repeat_from_step_3>
@@ -110,15 +126,14 @@ Current worktrees: !git worktree list`
         <continue_to_next>Continue checking next oldest worktree</continue_to_next>
       </if_no_pr>
     </verify_pr_merged>
-    <purpose>Use GitHub PR status as the authoritative source for merge verification instead of unreliable git commands</purpose>
+    <purpose>Use PR/MR status as the authoritative source for merge verification instead of unreliable git commands</purpose>
   </step_4>
 
   <step_4_5>
-    <description>Check and close related GitHub issue</description>
+    <description>Check and close related issue</description>
     <if_issue_found>
       <get_issue_details>
-        <tool>mcp__github__issue_read</tool>
-        <method>get</method>
+        <tool>Use $GIT_HOST_TOOL to read issue details</tool>
         <extract_repo>From issue reference (main-repo vs cross-repo)</extract_repo>
       </get_issue_details>
       <check_issue_state>
@@ -126,14 +141,13 @@ Current worktrees: !git worktree list`
           <ask_close>Ask user: "Related issue #{number} is still open. Should I close it? (y/N)"</ask_close>
           <if_yes_close>
             <add_closing_comment>
-              <tool>mcp__github__add_issue_comment</tool>
-              <body_template>Closing this issue as branch {branch_name} was merged to main on {merge_date} via PR #{pr_number}.</body_template>
-              <get_merge_date>Extract merge date from PR details</get_merge_date>
-              <get_pr_number>Use PR number from search results</get_pr_number>
+              <tool>Use $GIT_HOST_TOOL to add comment</tool>
+              <body_template>Closing this issue as branch {branch_name} was merged to {default_branch} on {merge_date} via PR/MR #{pr_number}.</body_template>
+              <get_merge_date>Extract merge date from PR/MR details</get_merge_date>
+              <get_pr_number>Use PR/MR number from search results</get_pr_number>
             </add_closing_comment>
             <close_issue>
-              <tool>mcp__github__issue_write</tool>
-              <method>update</method>
+              <tool>Use $GIT_HOST_TOOL to close issue</tool>
               <state>closed</state>
               <state_reason>completed</state_reason>
             </close_issue>
@@ -215,17 +229,22 @@ Current worktrees: !git worktree list`
 
 <important_notes>
 
-- Uses GitHub PR merge status as the ONLY reliable way to verify if a branch was merged
+- Uses PR/MR merge status as the ONLY reliable way to verify if a branch was merged
 - DOES NOT use "git branch --merged" command as it's unreliable for merge verification
-- Only processes branches with PRs that were definitively merged to main
-- Skips worktrees without merged PRs and continues to next oldest candidate
-- Checks and optionally closes related GitHub issues
+- Only processes branches with PRs/MRs that were definitively merged to default branch
+- Skips worktrees without merged PRs/MRs and continues to next oldest candidate
+- Checks and optionally closes related issues
 - Prioritizes oldest worktrees by directory age first for systematic cleanup
 - Warns about very recent worktrees (created within 24 hours) to avoid cleaning active work
 - Preserves useful development settings before deletion
 - Requires explicit confirmation before any destructive actions
 - Handles locked worktrees automatically
 - Processes one worktree at a time to maintain control
-- Must be run from main branch for safety
-- Works with standard GitHub repository URLs (owner/repo format)
+- Must be run from default branch for safety
+
+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 (GitHub, GitLab, etc.)
 </important_notes>

package/downloads/without-beads/busycommit.md

@@ -15,6 +15,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/without-beads/code-review.md

@@ -0,0 +1,246 @@
+---
+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
+
+# 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/without-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/without-beads/commit.md

@@ -15,6 +15,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/without-beads/gap.md

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