Enforce worktrees, PR dedup checks, and targeted testing in agent workflow

CLAUDE.md now leads with three mandatory rules that every agent sees
immediately: use worktrees (never work in the main checkout), check for
existing PRs before starting work, and only run relevant tests. The old
"run the full suite" command and casual worktree mention are removed.

coordinator_guide.md adds explicit `gh pr list` checks in Step 2, a
dedicated "Existing PRs" section (#4) in the prompt file template, and
stronger worktree language in the setup instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: TimDettmers

CLAUDE.md

@@ -1,25 +1,39 @@
-# Coordinating agent work on GitHub issues
+# MANDATORY: Use git worktrees for all branch work
 
-To analyze open issues, generate prompts, and launch parallel worker agents, follow `agents/coordinator_guide.md`. This uses the GitHub issue tools in `~/git/lab_tools/github/` — see `agents/github_tools_guide.md` for the bitsandbytes-specific reference.
+NEVER work on a fix or feature branch inside the main `~/git/bitsandbytes` checkout. Always create a worktree first:
+
+```bash
+cd ~/git/bitsandbytes
+git worktree add ~/git/bnb-fix-<NUMBER> -b fix/issue-<NUMBER>
+cd ~/git/bnb-fix-<NUMBER>
+```
+
+This keeps the main checkout clean and allows parallel sessions. If you are already inside a worktree directory, you do not need to create another one. Full guide: `agents/worktree_guide.md`
 
-# Parallel sessions
+# MANDATORY: Check for existing PRs before starting work
 
-To work on multiple branches at once, use git worktrees:
+Before working on any issue, check whether a PR already exists:
 
 ```bash
-git worktree add ../bitsandbytes-<branch-name> -b <branch-name>
-cd ../bitsandbytes-<branch-name>
-claude
+gh pr list --search "issue-number OR keyword" --state open
 ```
 
-Full guide: `agents/worktree_guide.md`
+If a PR exists, review and build on it instead of starting from scratch. Do not create duplicate work.
 
-# Testing
+# Testing: only run relevant tests
 
-Run the test suite with 4 parallel workers (optimal for any machine):
+Do NOT run the full test suite — it takes 10+ minutes. Instead, run only the tests that cover the code you changed:
 
 ```bash
-pytest tests/ -v --tb=short -n 4
+pytest tests/test_relevant_file.py -v --tb=short -k "relevant_test_name"
 ```
 
-Best practices, benchmark data, and known architecture-specific issues: `agents/testing_guide.md`
+The full suite will be run separately. Best practices and known issues: `agents/testing_guide.md`
+
+# Coordinating agent work on GitHub issues
+
+To analyze open issues, generate prompts, and launch parallel worker agents, follow `agents/coordinator_guide.md`. This uses the GitHub issue tools in `~/git/lab_tools/github/` — see `agents/github_tools_guide.md` for the bitsandbytes-specific reference.
+
+# Issue maintenance and triage
+
+To identify and close stale, duplicate, or resolved issues: `agents/issue_maintenance_guide.md`. Common closeable patterns (old CUDA setup, Windows pre-support, third-party app issues, etc.) are cataloged in `agents/issue_patterns.md`.

agents/coordinator_guide.md

@@ -49,6 +49,10 @@ For each candidate issue, gather full context. This step is critical — the qua
 # Full issue with all comments
 python3 ~/git/lab_tools/github/query_issues.py show <NUMBER>
 
+# Check for existing open PRs that already address this issue
+gh pr list --search "<NUMBER>" --state open
+gh pr list --search "keyword from issue" --state open
+
 # Find related/duplicate issues (with body previews and last comments)
 python3 ~/git/lab_tools/github/query_issues.py related <NUMBER> -v
 
@@ -61,11 +65,13 @@ python3 ~/git/lab_tools/github/query_issues.py search "specific error text"
 
 For each promising related issue that shows up, run `show` on it to get the full context. Don't stop at the `related` output — read the full body and comments of related issues, especially closed ones where the resolution may be documented.
 
+**IMPORTANT: Check for existing PRs.** If `gh pr list` or the cross-references in the `show` output reveal an open PR that already addresses the issue, do NOT generate a prompt that duplicates that work. Either skip the issue or generate a prompt that tells the worker to review/test/complete the existing PR instead.
+
 For each issue, determine:
 
 1. **What is the root cause?** Read the full body, comments, and tracebacks.
 2. **Has this been fixed before?** Check related closed issues for prior fixes.
-3. **Is there an existing PR?** Check cross-references in the `show` output.
+3. **Is there an existing PR?** Check cross-references in the `show` output AND run `gh pr list --search` to find PRs that may not be cross-referenced. If a PR exists, the worker should review it rather than start from scratch.
 4. **What files need to change?** Look for code pointers in the issue body and comments. If possible, read the actual source files in the bitsandbytes repo to verify.
 5. **How do we verify the fix?** Is there a reproduction script? What tests apply?
 6. **What patterns or context from other issues are relevant?** Maybe three other issues report the same error with different trigger conditions. Maybe a closed issue's fix didn't fully address the problem. This broader context is valuable for the worker agent.
@@ -94,12 +100,12 @@ Write each prompt file using the Write tool. The file name should be `issue-<NUM
 
 Every prompt file should have these sections:
 
-**1. Setup instructions.** The exact commands to create a worktree, plus a pointer to build/test docs:
+**1. Setup instructions.** The exact commands to create a worktree, plus a pointer to build/test docs. **The worktree step is mandatory — the worker agent must NOT work directly in `~/git/bitsandbytes`.**
 
 ```markdown
 ## Setup
 
-Create your working environment by running these commands:
+IMPORTANT: You MUST create a worktree. Do NOT work in ~/git/bitsandbytes directly.
 
     cd ~/git/bitsandbytes
     git worktree add ~/git/bnb-fix-<NUMBER> -b fix/issue-<NUMBER>
@@ -113,17 +119,18 @@ project before making changes so you can verify your setup works.
 
 **3. Related issues — full context.** For each related issue that you identified during your deep-dive, include the full `show` output or a thorough excerpt. For closed issues, the comments often contain the resolution — make sure those are included. Explain how each related issue connects to the target issue.
 
-**4. Additional context from your analysis.** This is where you include everything else you discovered:
+**4. Existing PRs.** If any open PRs already address (or partially address) this issue, list them with their PR number, branch, and a summary of what they change. Tell the worker agent to review the existing PR first and build on it rather than starting from scratch. If no existing PRs were found, state that explicitly so the worker knows it checked.
+
+**5. Additional context from your analysis.** This is where you include everything else you discovered:
 
 - Patterns across multiple issues (e.g. "Issues #933, #966, #1190, #1394, and #1434 all report the same CUDA Setup failure with different CUDA versions — the root cause appears to be X")
 - Relevant technical details from maintainer comments on other issues
 - Source code observations if you read the bitsandbytes source
-- Information about existing PRs — what they change, whether they look correct
 - Anything else the worker agent should know
 
-**5. Your recommended approach.** What you think the fix should look like. Be specific — name files, functions, line numbers. Frame it as guidance, not commands — the worker agent may find things you didn't and should use its own judgment. Include which specific test file(s) or test function(s) the agent should run to verify its fix — not the full suite.
+**6. Your recommended approach.** What you think the fix should look like. Be specific — name files, functions, line numbers. Frame it as guidance, not commands — the worker agent may find things you didn't and should use its own judgment. Include which specific test file(s) or test function(s) the agent should run to verify its fix — not the full suite.
 
-**6. Completion workflow.** Every prompt file must include this section verbatim, with the issue number filled in:
+**7. Completion workflow.** Every prompt file must include this section verbatim, with the issue number filled in:
 
 ```markdown
 ## When You Are Done
@@ -178,7 +185,7 @@ push, and create the PR — but note the failures in the PR description
 and explain what you tried. Do not silently abandon work.
 ```
 
-**7. What NOT to do.** If there are traps, scope boundaries, or things that look tempting but are wrong, list them explicitly. For example: "Don't change the 8bit_blockwise dispatch — only the 32bit dispatch is affected."
+**8. What NOT to do.** If there are traps, scope boundaries, or things that look tempting but are wrong, list them explicitly. For example: "Don't change the 8bit_blockwise dispatch — only the 32bit dispatch is affected."
 
 ### Example Prompt File