claude-dev-env 1.21.2 → 1.22.1

package/skills/bugteam/_claude_permissions_common.py

@@ -0,0 +1,224 @@
+"""Shared helpers for grant_project_claude_permissions and revoke_project_claude_permissions.
+
+Writes to ~/.claude/settings.json are atomic and permission-preserving: the
+target file's existing POSIX mode is captured, a sibling temp file is
+created via os.open with O_CREAT | O_EXCL and the preserved mode, content
+is written, then os.replace swaps it into place. Output is serialized with
+sort_keys=True for a stable on-disk layout; the first run on a hand-ordered
+settings file produces a one-time re-sort diff, subsequent writes are stable.
+"""
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Any, NoReturn
+
+
+TEXT_FILE_ENCODING: str = "utf-8"
+GLOB_METACHARACTERS_IN_PATH: tuple[str, ...] = (
+    "*",
+    "?",
+    "[",
+    "]",
+    "(",
+    ")",
+    "{",
+    "}",
+    ",",
+)
+
+JSON_INDENT_SPACES: int = 2
+PERMISSION_ALLOW_TOOLS: tuple[str, ...] = ("Edit", "Write", "Read")
+
+DEFAULT_SETTINGS_FILE_MODE: int = 0o600
+ATOMIC_WRITE_TEMPORARY_SUFFIX: str = ".tmp"
+
+AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE: str = (
+    "Trusted local workspace: {project_path}/.claude/** is the user's "
+    "project Claude Code config tree; edits inside are routine"
+)
+
+
+def exit_with_error(message: str) -> NoReturn:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def path_contains_glob_metacharacters(candidate_path: str) -> bool:
+    return any(
+        each_character in candidate_path
+        for each_character in GLOB_METACHARACTERS_IN_PATH
+    )
+
+
+def path_contains_whitespace(candidate_path: str) -> bool:
+    return any(each_character.isspace() for each_character in candidate_path)
+
+
+def get_current_project_path() -> str:
+    normalized_project_path = str(Path.cwd()).replace("\\", "/")
+    if path_contains_glob_metacharacters(normalized_project_path):
+        raise ValueError(
+            f"Current directory path contains glob metacharacters and cannot "
+            f"be used to build permission rules safely: {normalized_project_path}"
+        )
+    if path_contains_whitespace(normalized_project_path):
+        raise ValueError(
+            f"Current directory path contains whitespace and cannot be used "
+            f"to build permission rules safely: {normalized_project_path}"
+        )
+    return normalized_project_path
+
+
+def build_permission_rule(tool_name: str, project_path: str) -> str:
+    return f"{tool_name}({project_path}/.claude/**)"
+
+
+def build_permission_rules(
+    project_path: str, permission_allow_tools: tuple[str, ...]
+) -> list[str]:
+    return [
+        build_permission_rule(each_tool, project_path)
+        for each_tool in permission_allow_tools
+    ]
+
+
+def load_settings(settings_path: Path) -> dict[str, Any]:
+    if not settings_path.exists():
+        return {}
+    parsed_settings: dict[str, Any] = {}
+    try:
+        raw_text = settings_path.read_text(encoding=TEXT_FILE_ENCODING)
+    except OSError as read_error:
+        exit_with_error(f"Failed to read {settings_path}: {read_error}")
+    try:
+        parsed_settings = json.loads(raw_text)
+    except json.JSONDecodeError as decode_error:
+        exit_with_error(
+            f"Refusing to modify {settings_path}: existing file is not valid JSON "
+            f"({decode_error}). Fix or back up the file manually, then re-run."
+        )
+    if not isinstance(parsed_settings, dict):
+        exit_with_error(
+            f"Refusing to modify {settings_path}: existing file's root is "
+            f"{type(parsed_settings).__name__}, not a JSON object. Fix or back up "
+            f"the file manually, then re-run."
+        )
+    return parsed_settings
+
+
+def get_mode_to_preserve(settings_path: Path) -> int:
+    try:
+        stat_result = os.stat(settings_path)
+    except FileNotFoundError:
+        return DEFAULT_SETTINGS_FILE_MODE
+    except OSError as stat_error:
+        exit_with_error(f"Failed to stat {settings_path}: {stat_error}")
+    return stat.S_IMODE(stat_result.st_mode)
+
+
+def write_atomically_with_mode(
+    temporary_path: Path, serialized_content: str, file_mode: int
+) -> None:
+    file_descriptor = os.open(
+        str(temporary_path),
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+        file_mode,
+    )
+    with os.fdopen(file_descriptor, "w", encoding=TEXT_FILE_ENCODING) as writer:
+        writer.write(serialized_content)
+
+
+def save_settings(settings_path: Path, settings: dict[str, Any]) -> None:
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    serialized_settings = json.dumps(
+        settings, indent=JSON_INDENT_SPACES, sort_keys=True
+    )
+    temporary_path = settings_path.with_suffix(
+        settings_path.suffix + ATOMIC_WRITE_TEMPORARY_SUFFIX
+    )
+    mode_to_preserve = get_mode_to_preserve(settings_path)
+    try:
+        try:
+            write_atomically_with_mode(
+                temporary_path, serialized_settings, mode_to_preserve
+            )
+            os.replace(str(temporary_path), str(settings_path))
+        except OSError as os_error:
+            exit_with_error(
+                f"Failed to write settings atomically to {settings_path}: {os_error}"
+            )
+    finally:
+        if temporary_path.exists():
+            try:
+                temporary_path.unlink()
+            except OSError:
+                pass
+
+
+def append_if_missing(target_list: list[str], new_value: str) -> bool:
+    if new_value in target_list:
+        return False
+    target_list.append(new_value)
+    return True
+
+
+def ensure_dict_section(
+    settings: dict[str, Any], section_name: str
+) -> dict[str, Any]:
+    """Return an existing dict section or create an empty one if absent.
+
+    A missing key and an explicit JSON null are treated identically: both
+    produce a fresh empty dict stored back into settings. Any other non-dict
+    value (string, list, number, bool) calls exit_with_error to avoid
+    overwriting user data.
+    """
+    existing_section = settings.get(section_name)
+    if existing_section is None:
+        replacement_section: dict[str, Any] = {}
+        settings[section_name] = replacement_section
+        return replacement_section
+    if not isinstance(existing_section, dict):
+        exit_with_error(
+            f"Refusing to modify settings key {section_name!r}: existing value "
+            f"is {type(existing_section).__name__}, not a JSON object. Fix or "
+            f"remove the key manually, then re-run."
+        )
+    return existing_section
+
+
+def ensure_list_entry(section: dict[str, Any], entry_name: str) -> list[Any]:
+    """Return an existing list entry or create an empty one if absent.
+
+    A missing key and an explicit JSON null are treated identically: both
+    produce a fresh empty list stored back into the section. Any other
+    non-list value (string, dict, number, bool) calls exit_with_error to
+    avoid overwriting user data.
+    """
+    existing_entry = section.get(entry_name)
+    if existing_entry is None:
+        replacement_entry: list[Any] = []
+        section[entry_name] = replacement_entry
+        return replacement_entry
+    if not isinstance(existing_entry, list):
+        exit_with_error(
+            f"Refusing to modify settings entry {entry_name!r}: existing value "
+            f"is {type(existing_entry).__name__}, not a JSON array. Fix or "
+            f"remove the entry manually, then re-run."
+        )
+    return existing_entry
+
+
+def prune_empty_list_then_empty_section(
+    settings: dict[str, Any], section_key: str, list_key: str
+) -> None:
+    section = settings.get(section_key)
+    if not isinstance(section, dict):
+        return
+    list_entry = section.get(list_key)
+    if isinstance(list_entry, list) and len(list_entry) == 0:
+        del section[list_key]
+    if len(section) == 0:
+        del settings[section_key]

package/skills/bugteam/grant_project_claude_permissions.py

@@ -0,0 +1,110 @@
+"""Grant Edit/Write/Read permissions on the current directory's .claude tree.
+
+Run from the project root whose .claude/** you want a Claude Code session
+(including spawned subagents) to edit without prompting. Writes idempotent
+entries into the user-scope settings at ~/.claude/settings.json and prints
+the changes applied. No-op when the entries already exist.
+"""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _claude_permissions_common import (  # noqa: E402
+    append_if_missing,
+    build_permission_rules,
+    ensure_dict_section,
+    ensure_list_entry,
+    exit_with_error,
+    get_current_project_path,
+    load_settings,
+    save_settings,
+    AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE,
+    PERMISSION_ALLOW_TOOLS,
+)
+
+
+CLAUDE_USER_SETTINGS_PATH: Path = Path.home() / ".claude" / "settings.json"
+
+
+def is_valid_project_root(candidate_path: Path) -> bool:
+    git_marker_path = candidate_path / ".git"
+    claude_marker_path = candidate_path / ".claude"
+    return git_marker_path.exists() or claude_marker_path.exists()
+
+
+def add_rules_to_allow_list(settings: dict[str, Any], rules_to_add: list[str]) -> int:
+    permissions_section = ensure_dict_section(settings, "permissions")
+    existing_allow_list = ensure_list_entry(permissions_section, "allow")
+    return sum(
+        1
+        for each_rule in rules_to_add
+        if append_if_missing(existing_allow_list, each_rule)
+    )
+
+
+def add_directory_to_additional_directories(
+    settings: dict[str, Any], directory_path: str
+) -> int:
+    permissions_section = ensure_dict_section(settings, "permissions")
+    existing_directories = ensure_list_entry(
+        permissions_section, "additionalDirectories"
+    )
+    if append_if_missing(existing_directories, directory_path):
+        return 1
+    return 0
+
+
+def add_auto_mode_environment_entry(settings: dict[str, Any], entry_text: str) -> int:
+    auto_mode_section = ensure_dict_section(settings, "autoMode")
+    existing_environment = ensure_list_entry(auto_mode_section, "environment")
+    if append_if_missing(existing_environment, entry_text):
+        return 1
+    return 0
+
+
+def grant_permissions_for_current_directory() -> None:
+    project_root_path = Path.cwd()
+    if not is_valid_project_root(project_root_path):
+        print(
+            f"ERROR: cwd {project_root_path} is not a project root "
+            f"(no .git or .claude). Run from a project root.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    project_path = get_current_project_path()
+    permission_rules = build_permission_rules(project_path, PERMISSION_ALLOW_TOOLS)
+    environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
+        project_path=project_path
+    )
+    settings = load_settings(CLAUDE_USER_SETTINGS_PATH)
+    rules_added_count = add_rules_to_allow_list(settings, permission_rules)
+    directories_added_count = add_directory_to_additional_directories(
+        settings, project_path
+    )
+    environment_entries_added_count = add_auto_mode_environment_entry(
+        settings, environment_entry
+    )
+    total_changes_count = (
+        rules_added_count + directories_added_count + environment_entries_added_count
+    )
+    if total_changes_count == 0:
+        print(f"Project path: {project_path}")
+        print(f"Settings file: {CLAUDE_USER_SETTINGS_PATH}")
+        print("No changes needed; settings file left untouched.")
+        return
+    save_settings(CLAUDE_USER_SETTINGS_PATH, settings)
+    print(f"Project path: {project_path}")
+    print(f"Settings file: {CLAUDE_USER_SETTINGS_PATH}")
+    print(f"Allow rules added: {rules_added_count} of {len(permission_rules)}")
+    print(f"Additional directories added: {directories_added_count}")
+    print(f"Auto-mode environment entries added: {environment_entries_added_count}")
+
+
+if __name__ == "__main__":
+    try:
+        grant_permissions_for_current_directory()
+    except ValueError as path_error:
+        exit_with_error(str(path_error))

package/skills/bugteam/revoke_project_claude_permissions.py

@@ -0,0 +1,136 @@
+"""Revoke the permissions previously granted by grant_project_claude_permissions.
+
+Run from the same project root you previously granted. Removes the matching
+allow rules, the additionalDirectories entry, and the autoMode environment
+entry from ~/.claude/settings.json. Safe to run when no prior grant exists.
+After removals, prunes any newly empty lists and their parent permissions or
+autoMode sections so repeated grant/revoke cycles leave no dead structure.
+"""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _claude_permissions_common import (  # noqa: E402
+    build_permission_rules,
+    exit_with_error,
+    get_current_project_path,
+    load_settings,
+    prune_empty_list_then_empty_section,
+    save_settings,
+    AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE,
+    PERMISSION_ALLOW_TOOLS,
+)
+
+
+CLAUDE_USER_SETTINGS_PATH: Path = Path.home() / ".claude" / "settings.json"
+
+
+def is_valid_project_root(candidate_path: Path) -> bool:
+    git_marker_path = candidate_path / ".git"
+    claude_marker_path = candidate_path / ".claude"
+    return git_marker_path.exists() or claude_marker_path.exists()
+
+
+def remove_values_from_list(target_list: list[str], values_to_remove: set[str]) -> int:
+    original_length = len(target_list)
+    target_list[:] = [
+        each_value for each_value in target_list if each_value not in values_to_remove
+    ]
+    return original_length - len(target_list)
+
+
+def remove_rules_from_allow_list(
+    settings: dict[str, Any], rules_to_remove: list[str]
+) -> int:
+    permissions_section = settings.get("permissions")
+    if not isinstance(permissions_section, dict):
+        return 0
+    existing_allow_list = permissions_section.get("allow")
+    if not isinstance(existing_allow_list, list):
+        return 0
+    return remove_values_from_list(existing_allow_list, set(rules_to_remove))
+
+
+def remove_directory_from_additional_directories(
+    settings: dict[str, Any], directory_path: str
+) -> int:
+    permissions_section = settings.get("permissions")
+    if not isinstance(permissions_section, dict):
+        return 0
+    existing_directories = permissions_section.get("additionalDirectories")
+    if not isinstance(existing_directories, list):
+        return 0
+    return remove_values_from_list(existing_directories, {directory_path})
+
+
+def remove_auto_mode_environment_entry(
+    settings: dict[str, Any], entry_text: str
+) -> int:
+    auto_mode_section = settings.get("autoMode")
+    if not isinstance(auto_mode_section, dict):
+        return 0
+    existing_environment = auto_mode_section.get("environment")
+    if not isinstance(existing_environment, list):
+        return 0
+    return remove_values_from_list(existing_environment, {entry_text})
+
+
+def prune_settings_after_revoke(settings: dict[str, Any]) -> None:
+    prune_empty_list_then_empty_section(settings, "permissions", "allow")
+    prune_empty_list_then_empty_section(
+        settings, "permissions", "additionalDirectories"
+    )
+    prune_empty_list_then_empty_section(settings, "autoMode", "environment")
+
+
+def revoke_permissions_for_current_directory() -> None:
+    project_root_path = Path.cwd()
+    if not is_valid_project_root(project_root_path):
+        print(
+            f"ERROR: cwd {project_root_path} is not a project root "
+            f"(no .git or .claude). Run from a project root.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    project_path = get_current_project_path()
+    permission_rules = build_permission_rules(project_path, PERMISSION_ALLOW_TOOLS)
+    environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
+        project_path=project_path
+    )
+    settings = load_settings(CLAUDE_USER_SETTINGS_PATH)
+    rules_removed_count = remove_rules_from_allow_list(settings, permission_rules)
+    directories_removed_count = remove_directory_from_additional_directories(
+        settings, project_path
+    )
+    environment_entries_removed_count = remove_auto_mode_environment_entry(
+        settings, environment_entry
+    )
+    total_changes_count = (
+        rules_removed_count
+        + directories_removed_count
+        + environment_entries_removed_count
+    )
+    if total_changes_count == 0:
+        print(f"Project path: {project_path}")
+        print(f"Settings file: {CLAUDE_USER_SETTINGS_PATH}")
+        print("No changes to revoke; settings file left untouched.")
+        return
+    prune_settings_after_revoke(settings)
+    save_settings(CLAUDE_USER_SETTINGS_PATH, settings)
+    print(f"Project path: {project_path}")
+    print(f"Settings file: {CLAUDE_USER_SETTINGS_PATH}")
+    print(f"Allow rules removed: {rules_removed_count} of {len(permission_rules)}")
+    print(f"Additional directories removed: {directories_removed_count}")
+    print(
+        f"Auto-mode environment entries removed: {environment_entries_removed_count}"
+    )
+
+
+if __name__ == "__main__":
+    try:
+        revoke_permissions_for_current_directory()
+    except ValueError as path_error:
+        exit_with_error(str(path_error))

package/skills/findbugs/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: findbugs
+description: >-
+  Audits the current branch's pull request as a whole for bugs by spawning the
+  code-quality-agent against the full PR diff with zero conversation context.
+  Returns P0/P1/P2 findings with file:line evidence and a verified-clean
+  coverage list. Read-only — never modifies code. Triggers: '/findbugs',
+  'find bugs in this PR', 'audit the PR', 'bug audit on the branch'.
+---
+
+# Findbugs
+
+**Core principle:** A clean-room bug audit on the entire pull request. The audit agent receives the PR diff and nothing else — no chat history, no prior framing, no implicit "we already looked at this." Independence is the point.
+
+## When this skill applies
+
+User types `/findbugs` or asks for a bug audit on the current branch's PR. Typical moment: PR is up (draft or ready), and the user wants an independent second pair of eyes before merge or before requesting human review.
+
+If the current branch has no associated PR and no diff against the default branch, say so and stop. Do not invent scope.
+
+## The Process
+
+### Step 1: Resolve PR scope
+
+Determine the audit target in this order:
+
+1. **Open PR for current branch.** Run `gh pr view --json number,baseRefName,headRefName,url` from the working directory. If a PR exists, capture its number, base ref, head ref, and URL.
+2. **No PR but a remote default branch exists.** Diff against the default branch's merge-base: `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`. Treat this as the audit scope.
+3. **Neither.** Respond exactly: `No PR or upstream diff found. Push the branch or open a PR first.` and stop.
+
+### Step 2: Capture the full PR diff
+
+Resolve the temp diff path **once, Claude-side**, before invoking any shell command. Use Python's `tempfile.gettempdir()` which honors `TMPDIR`, `TEMP`, and `TMP` in the platform-correct order and falls back to `C:\Users\<user>\AppData\Local\Temp` on Windows or `/tmp` on Unix. Avoid hand-rolled env var chains. The lookup works on macOS, Linux, Windows cmd.exe, and PowerShell:
+
+```
+import tempfile
+diff_temp_path = Path(tempfile.gettempdir()) / f"findbugs-pr-{os.getpid()}.patch"
+```
+
+`os.getpid()` supplies the per-invocation suffix that prevents collisions with parallel `/findbugs` runs (a UUID or timestamp is equally acceptable). Capture the resolved absolute path as `<diff_temp_path>` and pass that **literal** path to every shell command that follows. Shell-side parameter expansion (`${TMPDIR:-/tmp}`, `$$`, `%TEMP%`) is forbidden because cmd.exe and PowerShell do not honor it.
+
+When a PR exists: `gh pr diff <number> -R <owner>/<repo> > "<diff_temp_path>"`.
+
+When falling back to merge-base diff: `git diff <merge-base>...HEAD > "<diff_temp_path>"`.
+
+The audit's authoritative scope is this single diff file. Do not inject extra files, related history, or "files Claude edited this session" — those introduce anchoring bias.
+
+### Step 3: Spawn the code-quality-agent — clean room
+
+Call the Agent tool with:
+
+- `subagent_type: code-quality-agent`
+- `model: sonnet`
+- `description: "PR bug audit"`
+- `run_in_background: false` — the user invoked `/findbugs` to get a result on this turn
+
+**The agent prompt must be self-contained and context-free.** Specifically:
+
+- **No references to the orchestrator's conversation.** Forbidden phrases: "as we discussed," "the earlier issue," "given our prior work," "the bug from last turn," "you previously identified."
+- **No hints about expected outcomes.** Do not pre-stage findings, do not suggest where bugs probably are, do not name files as "the suspicious one." The agent forms its own hypotheses.
+- **No instructions to favor or skip particular categories** beyond the standard category list. No "skip the typing stuff" or "focus on the clipboard logic" — those bias the audit.
+- **Minimal background.** Identify the repo, branch, base branch, and PR URL only. Do not summarize what the PR does.
+
+The XML prompt skeleton:
+
+```xml
+<context>
+  <repo>owner/repo</repo>
+  <branch>head ref</branch>
+  <base_branch>base ref</base_branch>
+  <pr_url>url or "none"</pr_url>
+</context>
+
+<scope>
+  <diff_path><diff_temp_path> (absolute scoped temp path from Step 2)</diff_path>
+  <scope_rule>Audit only lines added or modified in the diff. Pre-existing code on untouched lines is out of scope.</scope_rule>
+</scope>
+
+<bug_categories>
+  Investigate each explicitly:
+  A. API contract verification (signatures, return types, async/await correctness)
+  B. Selector / query / engine compatibility
+  C. Resource cleanup and lifecycle (file handles, connections, processes, locks)
+  D. Variable scoping, ordering, and unbound references
+  E. Dead code and unused imports
+  F. Silent failures (catch-all excepts, unconditional success returns, missing error propagation)
+  G. Off-by-one, bounds, and integer overflow
+  H. Security boundaries (injection, path traversal, auth bypass, secret leakage)
+  I. Concurrency hazards (race conditions, missing awaits, shared mutable state)
+  J. Magic values and configuration drift
+</bug_categories>
+
+<constraints>
+  Read-only. Report findings only. Do not modify code, do not propose
+  full diffs, do not commit, do not push. Cite file:line for every claim.
+  When the diff alone does not provide enough context to confirm or deny
+  a bug, list it under "Open questions" rather than asserting.
+</constraints>
+
+<output_format>
+  P0 = will not run / data corruption
+  P1 = regression or silent failure
+  P2 = dead code, minor smell
+
+  ## Summary
+  Total: N (P0=N, P1=N, P2=N)
+
+  ## Findings
+  ### [P_] short title
+  File: file/path:line
+  Category: A-J
+  Issue: 2-3 sentence description with concrete trace
+  Evidence: code excerpt or grep result
+
+  ## Verified clean
+  Per category investigated, name the evidence and the conclusion.
+
+  ## Open questions
+  Anything ambiguous from the diff alone.
+</output_format>
+```
+
+### Step 4: Surface findings, then clean up
+
+When the agent returns, report concisely:
+
+- One-line totals: `N P0 / N P1 / N P2 — K categories cleared`
+- Each finding's `file:line`, category, and one-sentence description
+- The cleared categories so the user can see coverage breadth
+- Any open questions the agent could not resolve from the diff alone
+
+Offer the next step without auto-executing it: `Want me to spawn clean-coder to fix the P0/P1 findings?`
+
+Delete the scoped temp diff at `<diff_temp_path>` after the audit completes (or moves to a fix flow). Temporary diff files do not belong in the working tree.
+
+Do not paste the full agent transcript or the XML prompt unless the user asks.
+
+## Output Format
+
+```
+N P0 / N P1 / N P2 — K categories cleared
+
+P1 — short title
+  file/path.py:NN — one-sentence description (category: <name>)
+
+P2 — short title
+  file/path.py:NN — one-sentence description (category: <name>)
+
+Verified clean: <category>, <category>, <category>
+
+Open questions:
+  <if any>
+
+Want me to spawn clean-coder to fix the P0/P1 findings?
+```
+
+## Constraints
+
+- **Read-only.** The skill never edits code, never pushes, never commits.
+- **Foreground spawn.** The user is waiting for the result on this turn.
+- **PR-scoped, not session-scoped.** The audit covers the entire PR diff regardless of which files were edited in this conversation.
+- **Clean-room prompt.** The agent's prompt is self-contained — no references to chat history, no anchoring hints, no expected outcomes.
+- **No clean-coder auto-spawn.** Always ask before fixing.
+- **Trust the agent's verdict.** Pass through P0/P1/P2 categorizations as the agent assigned them; do not re-rank.
+- **Temp file cleanup.** Delete the scoped `<diff_temp_path>` when the audit ends.
+
+## Examples
+
+<example>
+User: `/findbugs`
+Claude: [resolves PR #42 from current branch, fetches full diff, spawns code-quality-agent foreground with self-contained prompt, returns]
+
+`1 P0 / 2 P1 / 0 P2 — 7 categories cleared`
+
+`P0 — race condition on shared cache write`
+`  src/cache.py:88 — concurrent writers can both pass the existence check before either writes (category: concurrency)`
+
+`P1 — silent paste failure`
+`  utils/clipboard.py:33 — validated_paste returns success without verifying the post-paste state (category: silent failure)`
+
+`P1 — unbound variable on early-exception path`
+`  src/processor.py:283 — scheduling_log referenced after try/finally where it may be unbound (category: scoping)`
+
+`Verified clean: API contract, selector compatibility, resource cleanup, dead code, off-by-one, security boundaries, magic values`
+
+`Open questions: none`
+
+`Want me to spawn clean-coder to fix the P0 + P1s?`
+</example>
+
+<example>
+User: `/findbugs`
+Claude: `No PR or upstream diff found. Push the branch or open a PR first.`
+</example>
+
+<example>
+User: `/findbugs` (branch with no PR but commits ahead of main)
+Claude: [falls back to `git diff origin/main...HEAD`, runs audit on that diff scope]
+</example>
+
+## Why this design
+
+Anchoring bias is the failure mode of context-rich audits. An agent that inherits "we just fixed three bugs in clipboard_utils.py" subconsciously scopes its hunt around clipboard_utils.py and pattern-matches on the same bug shapes. A clean-room audit on the full PR diff treats every file equally, considers every category, and surfaces things the orchestrator session never looked at. The diff is the contract; everything else is noise.