@wbern/claude-instructions 1.9.0 → 1.11.0

package/downloads/without-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
@@ -16,31 +16,37 @@ argument-hint: <branch-name-or-github-issue-url> [optional-base-branch]
 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>
@@ -68,30 +74,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>
@@ -114,12 +131,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>
@@ -138,20 +155,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>
@@ -245,7 +262,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>
@@ -260,4 +277,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>

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

@@ -18,54 +18,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>
@@ -76,28 +93,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>
@@ -108,15 +124,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>
@@ -124,14 +139,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>
@@ -213,17 +227,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -34,6 +34,7 @@
     "test:quick-manual": "pnpm build:cli && node bin/cli.js",
     "generate": "tsx scripts/cli-generator.ts",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "knip": "knip",
@@ -45,13 +46,13 @@
     "@eslint/js": "^9.39.1",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
     "diff": "^8.0.2",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
     "jscpd": "^4.0.5",
     "knip": "^5.70.2",
     "lint-staged": "^16.2.7",
-    "markdown-magic": "^4.0.4",
     "markdownlint-cli": "^0.46.0",
     "picocolors": "^1.1.1",
     "prettier": "^3.7.2",
@@ -59,7 +60,7 @@
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.0",
-    "vitest": "^4.0.8"
+    "vitest": "^4.0.15"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",