claude-dev-env 1.39.0 → 1.40.0

package/docs/PR_DESCRIPTION_GUIDE.md

@@ -1,95 +1,158 @@
-# GitHub PR Summary Writing Guide for AI
+# PR Description Guide
 
-Use this guide when writing pull request descriptions. Follow these best practices to create clear, professional, and reviewable PR summaries.
+This guide describes the PR-body shape that the `pr-description-writer` agent produces and that the `pr_description_enforcer` PreToolUse hook validates against. The style mirrors merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal`.
 
-## Required Sections
+## Three shapes, picked from the diff
 
-### What (Changes)
+Pick the shape from the size and risk of the change, not from a template.
 
-- Concise statement of what was changed
-- What files or systems were modified
-- What functionality was added, removed, or improved
-- Keep to 2-3 sentences maximum
+| Signal | Shape |
+|---|---|
+| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** -- one declarative sentence, no headers |
+| Behavior change, bug fix, small feature; under ~15 files | **Standard** -- intro paragraph + `## Changes` + `## Test plan` (or `## Validation`) |
+| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** -- intro + `## Problem` + `## Fix` (or `## Changes`) + `## Verification` + extra sections as needed |
 
-### Why (Problem/Context)
+Prefer the smaller shape when in doubt.
 
-- Explain the problem this PR solves
-- Provide business or technical context
-- Reference related issue numbers using `#123` or `Fixes #123`, `Closes #456`
-- If no issue exists, briefly explain the motivation
+## Shape 1: Trivial
 
-### How (Approach/Solution)
+One sentence. No Markdown headers. Optional `Fixes #N` line.
 
-- Describe your implementation approach
-- Explain any design decisions or trade-offs
-- Include architectural changes if applicable
-- Note any breaking changes prominently
+```
+Pin third-party GitHub Actions references to immutable commit SHAs.
+```
 
-## Supporting Details
+```
+Bump pinned Bun from 1.3.6 to 1.3.14.
 
-### Testing and Quality
+Fixes #1311.
+```
 
-- What tests were added/modified
-- How to manually verify the changes (if applicable)
-- Any areas of concern or limitations
-- Performance impact (if relevant)
+## Shape 2: Standard
 
-### Dependencies and Risk
+```
+<One short intro paragraph stating the change and why it matters.
+ Reference the failure mode or user-visible symptom when there is one.>
 
-- New dependencies introduced (if any)
-- Backward compatibility status
-- Potential side effects
-- Migration steps (if needed)
+Fixes #<n>.
 
-## Optional but Valuable
+## Changes
 
-### Related Issues/PRs
+- `path/to/file.ext`: short clause describing the change
+- `path/to/other.ext`: short clause
+- `tests/foo.test.ts`: 2 new cases for X
 
-- Link to dependent PRs or issues
-- Note any follow-up work needed
+## Test plan
 
-### Screenshots/Examples (for UI changes)
+- `bun test test/foo.test.ts`
+- `bun run typecheck`
+- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
+```
 
-- Before/after comparisons when visual changes are involved
+The intro paragraph carries the Why -- no `## Why` header needed when one paragraph is enough.
 
-### Reviewer Guidance
+## Shape 3: Heavy
 
-- Specific areas to focus on
-- Questions for reviewers
-- Deployment considerations
+```
+<Two- to four-sentence intro: scope, motivation, user-visible effect.
+ Link to the prior PR or issue that motivates this one if applicable.>
 
-## Tone and Style Guidelines
+Fixes #<n>.
 
-- Be clear and concise -- reviewers scan quickly
-- Use second person sparingly -- focus on what the code does, not what the reviewer should do
-- Avoid jargon -- explain technical terms if non-obvious
-- Use markdown formatting -- bullets, code blocks, headers for readability
-- Be honest about limitations -- acknowledge trade-offs and known issues
-- Assume reviewers are unfamiliar -- provide sufficient context
+## Problem
 
-## What to Avoid
+<Concrete description of the failure mode or gap. Include the actual
+ error text, a reproduction, or the symptomatic log line in a fenced
+ code block when it helps.>
 
-- Vague statements like "fix bug" or "update code"
-- AI-generated summaries without human verification
-- Large walls of text -- break into sections
-- Repeating information from commit messages
-- References to temporary branch names or internal jargon without context
+```
+<example error or reproduction>
+```
+
+## Fix
 
-## Example Structure
+<What the change does at the level a reviewer needs to evaluate it.
+ Reference the file or function by path/name. Don't restate the diff
+ line-by-line -- the reviewer can read the code.>
 
-```markdown
-## Description
-Brief 1-2 sentence overview of the change.
+- `src/path/file.ts`: brief description
+- `src/path/other.ts`: brief description
 
-## Why
-Problem/context and reference to related issue (#123).
+## Verification
 
-## How
-Implementation approach and design decisions.
+- Command 1
+- Command 2 (with output count when useful: "666 pass, 0 fail")
+- Manual scenarios walked through
 
-## Testing
-How this was tested and verified.
+## Caveat
 
-## Risk Assessment
-Any breaking changes, dependencies, or concerns.
+<Anything a reviewer or downstream user needs to know that isn't in
+ the diff. Omit this section when there is no caveat.>
 ```
+
+Optional heavy-shape sections, used when they earn their place:
+
+- `## Runtime behavior` -- when the change preserves behavior but moves it.
+- `## Components` -- a small table when the PR introduces multiple named artifacts.
+- `## Backward compatibility` -- when an older consumer might still hit this code path.
+- `## Context` -- background a reviewer outside the area would need.
+
+## Section vocabulary
+
+Pick from these. Don't invent new ones, and don't use synonyms within one PR:
+
+| Intent | Header (pick one) |
+|---|---|
+| What this PR is and why | `## Summary` -- or no header (preferred when 1-3 sentences) |
+| The failure being fixed | `## Problem` -- or no header when the intro paragraph carries it |
+| The change itself | `## Changes` or `## Fix` |
+| How it was verified | `## Test plan`, `## Validation`, `## Verification`, or `## Testing` |
+| Things to know | `## Caveat`, `## Runtime behavior`, `## Backward compatibility`, `## Context` |
+
+## File reference style
+
+- Always backtick file paths: `` `src/github/operations/branch.ts` ``.
+- Use the full path from repo root, not just the basename, unless the basename is unambiguous within the PR.
+- Bullet lists describing per-file changes lead with the backticked path and a colon:
+  - `` `src/foo.ts`: whitelists `,` in branch names ``
+  - `` `test/foo.test.ts`: 3 new cases for comma-bearing branches ``
+- Prose calling out a single primary file bolds the backticked filename plus a colon: `` **`branch.ts`**: ... ``.
+
+## Cross-references
+
+- Issue/PR shorthand: `#1311` (same repo), `anthropics/claude-code#40576` (cross-repo).
+- `Fixes #N` and `Closes #N` close the linked issue on merge -- use them deliberately.
+- `Linear: CC-1723` -- one line, no Markdown, after the intro paragraph or at the bottom.
+- "Same change as <repo>#<n>" / "Follow-up to #<n>" -- one-liners that orient a reviewer.
+
+## Markers and footers
+
+- `<!-- NO CHANGELOG -->` on its own line, at the very end, for docs-only or CI-only PRs in repos that auto-generate changelogs from PR titles.
+- Don't add a "Generated with Claude Code" footer -- merged Anthropic PRs don't use one consistently, and the repo's commit trailer covers attribution.
+
+## What the hook checks
+
+`pr_description_enforcer.py` runs on `gh pr create` and `gh pr edit` invocations that include a body. It blocks when any of the following are true:
+
+- The body, after stripping Markdown ceremony (headers, code fences, bullet markers, bold/emphasis, link text), contains fewer than 40 characters of prose. A skeleton of `## Summary` + `## Changes` + bullets with no Why paragraph fails here.
+- The body contains vague phrases like `fix bug`, `update code`, `minor changes`, or `various fixes`.
+
+The hook does not require any specific section headers -- `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan` are all optional, including any combination of them. A single substantive sentence ("Pin third-party GitHub Actions references to immutable commit SHAs.") satisfies the check.
+
+When the hook blocks, it points the caller at the `pr-description-writer` agent and at this guide.
+
+## Tone
+
+- Plain language. "The pull engine would blindly overwrite any record marked as 'synced'" -- not "PullEngine.run() exhibited non-idempotent behavior".
+- Active voice. "Add `,` to the whitelist" -- not "`,` was added to the whitelist".
+- No filler. Start with the content, not "This PR..." or "In this change...".
+- No restating the diff. Trust the reviewer to read the code; explain the parts they can't infer.
+- No hedging ("should", "might", "I think") unless the uncertainty is real -- in which case say "not yet verified" and call it out.
+
+## What to avoid
+
+- Code snippets that simply repeat the diff. Code blocks are for error reproductions, failing commands, or before/after when the contrast is the point.
+- Technical jargon for non-obvious internals ("Dexie transaction" -> "database transaction").
+- Multi-line preamble. The PR title already says what the change is.
+- Section headers over empty content. If `## Caveat` would be empty, drop the header.
+- Second-person commentary directed at the reviewer ("please review carefully"). The reviewer knows their job.

package/hooks/blocking/pr_description_enforcer.py

@@ -20,16 +20,30 @@ from _gh_body_arg_utils import (
     iter_significant_tokens,
 )
 
-PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-PR_GUIDE_PATH = os.path.join(PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
 
-REQUIRED_PR_SECTION_HEADERS = [
-    "description",
-    "why",
-    "how",
-]
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.pr_description_enforcer_constants import (
+    BLOCKQUOTE_MARKER_PATTERN,
+    BOLD_PAIR_PATTERN,
+    BULLET_MARKER_PATTERN,
+    FENCED_CODE_BLOCK_PATTERN,
+    HEADING_LINE_PATTERN,
+    INLINE_CODE_PATTERN,
+    LINK_TEXT_PATTERN,
+    MINIMUM_SUBSTANTIVE_PROSE_CHARS,
+    WHITESPACE_RUN_PATTERN,
+)
 
-MINIMUM_PR_BODY_LENGTH = 50
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+PR_GUIDE_PATH = os.path.join(PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
 
 VAGUE_LANGUAGE_PATTERN = re.compile(
     r'\b(fix(?:ed)? (?:bug|issue|it)|update(?:d)? code|minor changes|various (?:fixes|updates|improvements))\b',
@@ -269,23 +283,43 @@ def extract_body_from_command(
     return result
 
 
+def _count_substantive_prose_chars(body: str) -> int:
+    """Return the count of prose characters after stripping Markdown ceremony.
+
+    Removes fenced code, inline code, heading lines, blockquote markers,
+    bullet list markers, bold/emphasis markers, and Markdown link targets.
+    Collapses internal whitespace so a body of only headers and bullets --
+    no real WHY paragraph -- registers as effectively empty.
+    """
+    body_without_fences = FENCED_CODE_BLOCK_PATTERN.sub('', body)
+    body_without_inline_code = INLINE_CODE_PATTERN.sub('', body_without_fences)
+    body_without_blockquotes = BLOCKQUOTE_MARKER_PATTERN.sub('', body_without_inline_code)
+    body_without_headings = HEADING_LINE_PATTERN.sub('', body_without_blockquotes)
+    body_without_bullets = BULLET_MARKER_PATTERN.sub('', body_without_headings)
+    body_without_bold = BOLD_PAIR_PATTERN.sub(r'\1', body_without_bullets)
+    body_without_emphasis = body_without_bold.replace('*', '')
+    body_without_links = LINK_TEXT_PATTERN.sub(r'\1', body_without_emphasis)
+    body_collapsed = WHITESPACE_RUN_PATTERN.sub(' ', body_without_links).strip()
+    return len(body_collapsed)
+
+
 def validate_pr_body(body: str) -> list[str]:
-    violations = []
-    body_lower = body.lower()
+    """Audit a PR body for substantive-prose and vague-language violations.
 
-    missing_required_sections = [
-        header for header in REQUIRED_PR_SECTION_HEADERS
-        if f"## {header}" not in body_lower and f"**{header}" not in body_lower
-    ]
+    Args:
+        body: The PR body markdown text to audit.
 
-    if missing_required_sections:
-        formatted_sections = ", ".join(f"'{each_section.title()}'" for each_section in missing_required_sections)
-        violations.append(f"Missing required section(s): {formatted_sections}")
+    Returns:
+        A list of human-readable violation messages. Empty when the body passes.
+    """
+    violations = []
 
-    stripped_body = re.sub(r'#.*', '', body).strip()
-    stripped_body = re.sub(r'\*\*.*?\*\*', '', stripped_body).strip()
-    if len(stripped_body) < MINIMUM_PR_BODY_LENGTH:
-        violations.append("PR body too short -- provide meaningful context for reviewers")
+    substantive_chars = _count_substantive_prose_chars(body)
+    if substantive_chars < MINIMUM_SUBSTANTIVE_PROSE_CHARS:
+        violations.append(
+            "PR body lacks substantive prose -- include a Why paragraph or "
+            "substantive explanation, not only headers and bullets"
+        )
 
     vague_matches = VAGUE_LANGUAGE_PATTERN.findall(body)
     if vague_matches:
@@ -329,7 +363,8 @@ def main() -> None:
         pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
         denial_reason = (
             f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
-            f"Follow the PR description guide:{pr_guide_reference}"
+            f"Use the pr-description-writer agent to author the body in Anthropic claude-code style. "
+            f"Guide:{pr_guide_reference}"
         )
         result = {
             "hookSpecificOutput": {

package/hooks/blocking/test_pr_description_enforcer.py

@@ -25,8 +25,21 @@ extract_body_from_command = hook_module.extract_body_from_command
 validate_pr_body = hook_module.validate_pr_body
 
 VALID_BODY = (
-    "## Description\n\nThis PR fixes a real bug.\n\n"
-    "## Why\n\nBecause it was broken in production.\n\n"
+    "Allow commas in branch names so PRs whose head branch was generated from "
+    "a title or external identifier no longer fail validation before any git "
+    "operation.\n\n"
+    "Fixes #1300.\n\n"
+    "## Changes\n\n"
+    "- `src/github/operations/branch.ts`: add `,` to the whitelist regex\n"
+    "- `test/branch.test.ts`: 3 new cases covering comma-bearing branch names\n\n"
+    "## Test plan\n\n"
+    "- `bun test test/branch.test.ts`\n"
+    "- `bun run typecheck`\n"
+)
+
+LEGACY_DESCRIPTION_WHY_HOW_BODY = (
+    "## Description\n\nThis PR fixes a real bug in the authentication module.\n\n"
+    "## Why\n\nBecause it was broken in production and customers reported failures.\n\n"
     "## How\n\nRefactored the auth module to handle edge cases correctly.\n"
 )
 
@@ -109,15 +122,63 @@ def test_extract_short_flag_shell_var_returns_empty() -> None:
     assert extract_body_from_command(command) == ""
 
 
-def test_validate_passes_complete_body() -> None:
+def test_validate_passes_anthropic_standard_body() -> None:
     assert validate_pr_body(VALID_BODY) == []
 
 
-def test_validate_blocks_missing_sections() -> None:
-    violations = validate_pr_body("Some body text without required sections.\n" * 5)
-    assert any(
-        "Missing required section" in each_violation for each_violation in violations
+def test_validate_passes_legacy_description_why_how_body() -> None:
+    """Existing Description/Why/How bodies must still pass -- the relaxed rule only widens what's accepted."""
+    assert validate_pr_body(LEGACY_DESCRIPTION_WHY_HOW_BODY) == []
+
+
+def test_validate_passes_sectionless_prose_body() -> None:
+    """Anthropic's trivial-PR shape is one sentence with no headers."""
+    body = (
+        "Pin third-party GitHub Actions references to immutable commit SHAs "
+        "so a tag move cannot redirect CI to attacker-controlled code."
+    )
+    assert validate_pr_body(body) == []
+
+
+def test_validate_blocks_skeleton_body_with_only_headers_and_bullets() -> None:
+    """Sections + bullets without any prose Why is rejected -- the substantive-prose check catches this."""
+    body = (
+        "## Summary\n\n"
+        "## Changes\n\n"
+        "- `a`\n"
+        "- `b`\n"
+        "- `c`\n"
+    )
+    violations = validate_pr_body(body)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
+
+
+def test_validate_blocks_blockquoted_headings_with_no_real_prose() -> None:
+    """Regression: blockquote markers must strip BEFORE heading stripping.
+
+    A line like `> ## Summary` starts with `>`, so `^#+[ \\t].*$` cannot match it
+    in heading position. If blockquote markers are stripped after, the bare
+    `## Summary` text survives into the prose stream and inflates the count.
+    Correct order strips `> ` first, then the line becomes a real heading and
+    drops out, leaving an effectively empty body below the 40-character minimum.
+    """
+    body = "> ## Summary\n> ## Why\n> ## How"
+    violations = validate_pr_body(body)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
+
+
+def test_validate_passes_prose_after_bare_hashes_with_no_space() -> None:
+    """Bug regression: `##\\n` followed by prose must not have its prose eaten by the heading regex.
+
+    The previous pattern `^#+\\s.*$` matched `\\s` against the newline, then `.*$` greedily
+    consumed the next line. The fix restricts the whitespace class to `[ \\t]` so only true
+    headings (`## text`) match, leaving prose-after-bare-hashes intact for substantive-prose counting.
+    """
+    body = (
+        "##\nThis is real prose that should not be eaten by the heading regex, "
+        "it should pass the 40-character minimum."
     )
+    assert validate_pr_body(body) == []
 
 
 def test_validate_blocks_vague_language() -> None:
@@ -128,7 +189,7 @@ def test_validate_blocks_vague_language() -> None:
 
 def test_validate_blocks_short_body() -> None:
     violations = validate_pr_body("Too short.")
-    assert any("too short" in each_violation.lower() for each_violation in violations)
+    assert any("substantive prose" in each_violation.lower() for each_violation in violations)
 
 
 def test_body_file_content_validated(tmp_path: pathlib.Path) -> None:

package/hooks/config/pr_description_enforcer_constants.py

@@ -0,0 +1,14 @@
+"""Configuration constants for the pr_description_enforcer PreToolUse hook."""
+
+import re
+
+MINIMUM_SUBSTANTIVE_PROSE_CHARS: int = 40
+
+FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```.*?```", re.DOTALL)
+INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]*`")
+HEADING_LINE_PATTERN: re.Pattern[str] = re.compile(r"^#+[ \t].*$", re.MULTILINE)
+BOLD_PAIR_PATTERN: re.Pattern[str] = re.compile(r"\*\*([^*]+?)\*\*")
+BULLET_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
+BLOCKQUOTE_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*>\s+", re.MULTILINE)
+LINK_TEXT_PATTERN: re.Pattern[str] = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+WHITESPACE_RUN_PATTERN: re.Pattern[str] = re.compile(r"\s+")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.39.0",
+    "version": "1.40.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/bugteam/SKILL.md

@@ -32,6 +32,11 @@ other failures require manual fix before Step 0. Full detail:
 
 First match wins; respond with the quoted line exactly and stop:
 
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` contains the
+  token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
+  `/bugteam is disabled via CLAUDE_REVIEWS_DISABLED.` The pre-flight script
+  also exits 7 in this case so any caller invoking it directly halts on the
+  same signal.
 - **No PR or upstream diff.** `No PR or upstream diff. /bugteam needs a target.`
 - **Dirty tree.** `Uncommitted changes detected. Stash, commit, or revert before
   /bugteam.`
@@ -50,16 +55,29 @@ Every internal audit pass (CLEAN or DIRTY) ends with one call to
 finding; each becomes its own resolvable thread). The mandate applies
 whether bugteam runs inside `/pr-converge` or standalone.
 
-**Self-PR precondition.** GitHub rejects both `APPROVE` and
-`REQUEST_CHANGES` reviews when the authenticated identity (the `gh auth`
-token in scope) matches the PR author with HTTP 422 ("Cannot
-approve/request changes on your own pull request"). `post_audit_thread.py`
-will retry on transient errors and then exit 2 (retry exhaustion); the
-script does not detect the self-PR case and downgrade to `COMMENT`. To
-run bugteam on a PR you authored, switch `gh auth` to an alternate
-reviewer identity (a separate GitHub account) BEFORE invoking the skill.
-Without this switch, exit 2 is a hard halt — there is no automated
-fallback path. The script does not auto-downgrade on the self-PR case.
+**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
+`REQUEST_CHANGES` reviews with HTTP 422 when the authenticated identity
+matches the PR author ("Cannot approve/request changes on your own pull
+request"). `post_audit_thread.py` detects this case via `gh api user` +
+`gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh
+account's token for the reviews POST — the active `gh auth` account is
+not mutated; only the bearer token sent on the request changes. After
+the POST the active account is still whoever it was before, so no
+"swap back" step is needed.
+
+Configuration:
+
+- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle.
+  Set them when you need to pin a specific reviewer identity by token
+  rather than by account login.
+- `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated alternate
+  to prefer when a toggle is needed (for example,
+  `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). When unset, the script falls back
+  to the first alternate account `gh auth status` reports.
+- The named alternate must be logged in (`gh auth login -h github.com -u
+  <login>`) before the audit skill runs. The script exits 1 with a
+  pointing-at-`gh auth login` message when self-PR is detected and no
+  usable alternate is authenticated.
 
 ```
 python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \

package/skills/bugteam/reference/team-setup.md

@@ -138,3 +138,8 @@ Self-claiming by task subject prefix keeps each teammate on its assigned PR.
 **`--bugbot-retrigger` flag:** when present, the FIX subagent posts a `bugbot
 run` issue comment via the Step 2.5 issue-comments fallback endpoint after
 every successful FIX push, to re-trigger Cursor's bugbot on the new commit.
+
+**Opt-out gate.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated,
+case-insensitive, whitespace-tolerant) contains the token `bugbot`, the FIX
+subagent skips the re-trigger post even when the flag is present. The rest of
+the bugteam audit/fix cycle continues unchanged.

package/skills/bugteam/scripts/bugteam_preflight.py

@@ -12,8 +12,11 @@ for each_cached_module_name in [
     if each_module_key == "config" or each_module_key.startswith("config.")
 ]:
     sys.modules.pop(each_cached_module_name, None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+_bugteam_scripts_directory = str(Path(__file__).absolute().parent)
+while _bugteam_scripts_directory in sys.path:
+    sys.path.remove(_bugteam_scripts_directory)
+if _bugteam_scripts_directory not in sys.path:
+    sys.path.insert(0, _bugteam_scripts_directory)
 
 from config.bugteam_preflight_constants import (
     ALL_DISCOVERY_IGNORE_DIRECTORIES,
@@ -32,6 +35,26 @@ from config.bugteam_preflight_constants import (
     PYTEST_INI_FILENAME,
 )
 
+for each_cached_module_name in [
+    each_module_key
+    for each_module_key in list(sys.modules)
+    if each_module_key == "config" or each_module_key.startswith("config.")
+]:
+    sys.modules.pop(each_cached_module_name, None)
+_shared_pr_loop_scripts_directory = (
+    Path(__file__).absolute().parent
+    / ".." / ".." / ".." / "_shared" / "pr-loop" / "scripts"
+).absolute()
+if str(_shared_pr_loop_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_pr_loop_scripts_directory))
+
+from reviews_disabled import (
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+    EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
+    is_bugteam_disabled_via_env,
+)
+
 
 def verify_git_hooks_path(repository_root: Path | None) -> int:
     """Check that core.hooksPath resolves to the claude-dev-env git-hooks directory.
@@ -259,6 +282,17 @@ def main(all_argv: list[str] | None = None) -> int:
     if os.environ.get(BUGTEAM_PREFLIGHT_SKIP_ENV_VAR_NAME, "").strip() == "1":
         print(f"{BUGTEAM_PREFLIGHT_PREFIX}skipped (BUGTEAM_PREFLIGHT_SKIP=1).", file=sys.stderr)
         return 0
+    reviews_disabled_env_var_name = CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME
+    reviews_disabled_bugteam_token = CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN
+    disabled_via_env_exit_code = EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+    if is_bugteam_disabled_via_env():
+        print(
+            f"{BUGTEAM_PREFLIGHT_PREFIX}halted "
+            f"({reviews_disabled_env_var_name} contains "
+            f"'{reviews_disabled_bugteam_token}').",
+            file=sys.stderr,
+        )
+        return disabled_via_env_exit_code
     start = Path.cwd()
     resolved_repository_root: Path = (
         arguments.repo_root.resolve()

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -266,3 +266,44 @@ def test_has_pytest_configuration_returns_false_without_either_file(
     repository_root = tmp_path / "repo"
     repository_root.mkdir()
     assert bugteam_preflight.has_pytest_configuration(repository_root) is False
+
+
+def test_main_should_halt_when_env_var_lists_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED=bugteam must halt preflight with the dedicated exit code."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+    captured = capsys.readouterr()
+    assert "CLAUDE_REVIEWS_DISABLED" in captured.err
+    assert "bugteam" in captured.err
+
+
+def test_main_should_continue_when_env_var_omits_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED without the bugteam token must not halt preflight."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot,bugbot")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code != bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+
+
+def test_main_should_halt_when_env_var_contains_uppercase_or_whitespace_bugteam_token(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Token matching must be case-insensitive and whitespace-tolerant."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugTeam , copilot ")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV

package/skills/copilot-review/SKILL.md

@@ -21,6 +21,22 @@ The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to k
 
 ## The Process
 
+### Step 0: Opt-out check
+
+Before any other work, inspect the `CLAUDE_REVIEWS_DISABLED` environment
+variable. Treat the value as a comma-separated list of skill tokens
+(case-insensitive, whitespace-tolerant). When the parsed list contains
+`copilot`, respond with the literal line `/copilot-review is disabled via
+CLAUDE_REVIEWS_DISABLED.` and stop — do not spawn the subagent, do not call
+the Copilot reviewer API, do not run any other step of this skill.
+
+PowerShell probe (Windows):
+
+```pwsh
+$disabled = ($env:CLAUDE_REVIEWS_DISABLED -split ',' | ForEach-Object { $_.Trim().ToLowerInvariant() })
+if ($disabled -contains 'copilot') { '/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.' }
+```
+
 ### Step 1: Gather PR context
 
 From the current repo: