claude-dev-env 1.26.1 → 1.26.3

package/skills/bugteam/{_claude_permissions_common.py → scripts/_claude_permissions_common.py}

@@ -13,28 +13,12 @@ import os
 import stat
 import sys
 from pathlib import Path
-from typing import Any, NoReturn
+from typing import 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"
@@ -47,9 +31,20 @@ def exit_with_error(message: str) -> NoReturn:
 
 
 def path_contains_glob_metacharacters(candidate_path: str) -> bool:
+    glob_metacharacters_in_path: tuple[str, ...] = (
+        "*",
+        "?",
+        "[",
+        "]",
+        "(",
+        ")",
+        "{",
+        "}",
+        ",",
+    )
     return any(
         each_character in candidate_path
-        for each_character in GLOB_METACHARACTERS_IN_PATH
+        for each_character in glob_metacharacters_in_path
     )
 
 
@@ -76,10 +71,10 @@ def build_permission_rules(
     ]
 
 
-def load_settings(settings_path: Path) -> dict[str, Any]:
+def load_settings(settings_path: Path) -> dict[str, object]:
     if not settings_path.exists():
         return {}
-    parsed_settings: dict[str, Any] = {}
+    parsed_settings: dict[str, object] = {}
     try:
         raw_text = settings_path.read_text(encoding=TEXT_FILE_ENCODING)
     except OSError as read_error:
@@ -100,11 +95,21 @@ def load_settings(settings_path: Path) -> dict[str, Any]:
     return parsed_settings
 
 
+def serialize_settings_to_json_text(settings: dict[str, object]) -> str:
+    json_indent_width_columns: int = len("  ")
+    return json.dumps(
+        settings,
+        indent=json_indent_width_columns,
+        sort_keys=True,
+    )
+
+
 def get_mode_to_preserve(settings_path: Path) -> int:
+    default_settings_file_mode: int = 0o600
     try:
         stat_result = os.stat(settings_path)
     except FileNotFoundError:
-        return DEFAULT_SETTINGS_FILE_MODE
+        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)
@@ -122,13 +127,12 @@ def write_atomically_with_mode(
         writer.write(serialized_content)
 
 
-def save_settings(settings_path: Path, settings: dict[str, Any]) -> None:
+def save_settings(settings_path: Path, settings: dict[str, object]) -> None:
+    atomic_write_temporary_suffix: str = ".tmp"
     settings_path.parent.mkdir(parents=True, exist_ok=True)
-    serialized_settings = json.dumps(
-        settings, indent=JSON_INDENT_SPACES, sort_keys=True
-    )
+    serialized_settings = serialize_settings_to_json_text(settings)
     temporary_path = settings_path.with_suffix(
-        settings_path.suffix + ATOMIC_WRITE_TEMPORARY_SUFFIX
+        settings_path.suffix + atomic_write_temporary_suffix
     )
     mode_to_preserve = get_mode_to_preserve(settings_path)
     try:
@@ -149,7 +153,7 @@ def save_settings(settings_path: Path, settings: dict[str, Any]) -> None:
                 pass
 
 
-def append_if_missing(target_list: list[str], new_value: str) -> bool:
+def append_if_missing(target_list: list[object], new_value: str) -> bool:
     if new_value in target_list:
         return False
     target_list.append(new_value)
@@ -157,8 +161,8 @@ def append_if_missing(target_list: list[str], new_value: str) -> bool:
 
 
 def ensure_dict_section(
-    settings: dict[str, Any], section_name: str
-) -> dict[str, Any]:
+    settings: dict[str, object], section_name: str
+) -> dict[str, object]:
     """Return an existing dict section or create an empty one if absent.
 
     A missing key and an explicit JSON null are treated identically: both
@@ -168,7 +172,7 @@ def ensure_dict_section(
     """
     existing_section = settings.get(section_name)
     if existing_section is None:
-        replacement_section: dict[str, Any] = {}
+        replacement_section: dict[str, object] = {}
         settings[section_name] = replacement_section
         return replacement_section
     if not isinstance(existing_section, dict):
@@ -180,7 +184,7 @@ def ensure_dict_section(
     return existing_section
 
 
-def ensure_list_entry(section: dict[str, Any], entry_name: str) -> list[Any]:
+def ensure_list_entry(section: dict[str, object], entry_name: str) -> list[object]:
     """Return an existing list entry or create an empty one if absent.
 
     A missing key and an explicit JSON null are treated identically: both
@@ -190,7 +194,7 @@ def ensure_list_entry(section: dict[str, Any], entry_name: str) -> list[Any]:
     """
     existing_entry = section.get(entry_name)
     if existing_entry is None:
-        replacement_entry: list[Any] = []
+        replacement_entry: list[object] = []
         section[entry_name] = replacement_entry
         return replacement_entry
     if not isinstance(existing_entry, list):
@@ -203,7 +207,7 @@ def ensure_list_entry(section: dict[str, Any], entry_name: str) -> list[Any]:
 
 
 def prune_empty_list_then_empty_section(
-    settings: dict[str, Any], section_key: str, list_key: str
+    settings: dict[str, object], section_key: str, list_key: str
 ) -> None:
     section = settings.get(section_key)
     if not isinstance(section, dict):

package/skills/bugteam/scripts/bugteam_code_rules_gate.py

@@ -46,6 +46,8 @@ def resolve_merge_base(repository_root: Path, base_reference: str) -> str:
         cwd=str(repository_root),
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     if merge_result.returncode != 0:
@@ -58,6 +60,35 @@ def resolve_merge_base(repository_root: Path, base_reference: str) -> str:
     return merge_result.stdout.strip()
 
 
+def filter_paths_under_prefixes(
+    file_paths: list[Path],
+    repository_root: Path,
+    prefix_list: list[str],
+) -> list[Path]:
+    if not prefix_list:
+        return file_paths
+    normalized_prefixes = [
+        each.strip().replace("\\", "/").rstrip("/")
+        for each in prefix_list
+        if each.strip()
+    ]
+    if not normalized_prefixes:
+        return file_paths
+    resolved_root = repository_root.resolve()
+    filtered: list[Path] = []
+    for each_path in file_paths:
+        try:
+            relative_posix = each_path.resolve().relative_to(resolved_root).as_posix()
+        except ValueError:
+            continue
+        if any(
+            relative_posix == prefix or relative_posix.startswith(prefix + "/")
+            for prefix in normalized_prefixes
+        ):
+            filtered.append(each_path)
+    return filtered
+
+
 def paths_from_git_diff(repository_root: Path, base_reference: str) -> list[Path]:
     merge_base = resolve_merge_base(repository_root, base_reference)
     name_result = subprocess.run(
@@ -65,6 +96,8 @@ def paths_from_git_diff(repository_root: Path, base_reference: str) -> list[Path
         cwd=str(repository_root),
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     if name_result.returncode != 0:
@@ -109,6 +142,8 @@ def is_file_new_at_base(
         cwd=str(repository_root),
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     return cat_result.returncode != 0
@@ -124,6 +159,8 @@ def added_lines_for_file(
         cwd=str(repository_root),
         capture_output=True,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     if diff_result.returncode != 0:
@@ -300,6 +337,17 @@ def parse_arguments(argv: list[str]) -> argparse.Namespace:
         default="origin/main",
         help="Merge-base ref for git diff (default: origin/main).",
     )
+    parser.add_argument(
+        "--only-under",
+        action="append",
+        default=[],
+        dest="only_under",
+        metavar="PREFIX",
+        help=(
+            "After resolving the merge-base diff, keep only files whose repo-relative path "
+            "uses POSIX slashes and starts with PREFIX or equals PREFIX (repeatable)."
+        ),
+    )
     parser.add_argument(
         "paths",
         nargs="*",
@@ -321,6 +369,13 @@ def main(argv: list[str] | None = None) -> int:
         file_paths = [repository_root / path for path in arguments.paths]
         return run_gate(validate_content, file_paths, repository_root, added_lines_map=None)
     file_paths = paths_from_git_diff(repository_root, arguments.base)
+    file_paths = filter_paths_under_prefixes(
+        file_paths,
+        repository_root,
+        arguments.only_under,
+    )
+    if not file_paths:
+        return 0
     scoped_added_lines = added_lines_by_file(repository_root, arguments.base, file_paths)
     return run_gate(
         validate_content,

package/skills/bugteam/{grant_project_claude_permissions.py → scripts/grant_project_claude_permissions.py}

@@ -8,7 +8,6 @@ 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))
 
@@ -26,16 +25,13 @@ from _claude_permissions_common import (  # noqa: E402
 )
 
 
-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:
+def add_rules_to_allow_list(settings: dict[str, object], rules_to_add: list[str]) -> int:
     permissions_section = ensure_dict_section(settings, "permissions")
     existing_allow_list = ensure_list_entry(permissions_section, "allow")
     return sum(
@@ -46,7 +42,7 @@ def add_rules_to_allow_list(settings: dict[str, Any], rules_to_add: list[str]) -
 
 
 def add_directory_to_additional_directories(
-    settings: dict[str, Any], directory_path: str
+    settings: dict[str, object], directory_path: str
 ) -> int:
     permissions_section = ensure_dict_section(settings, "permissions")
     existing_directories = ensure_list_entry(
@@ -57,7 +53,9 @@ def add_directory_to_additional_directories(
     return 0
 
 
-def add_auto_mode_environment_entry(settings: dict[str, Any], entry_text: str) -> int:
+def add_auto_mode_environment_entry(
+    settings: dict[str, object], 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):
@@ -66,6 +64,7 @@ def add_auto_mode_environment_entry(settings: dict[str, Any], entry_text: str) -
 
 
 def grant_permissions_for_current_directory() -> None:
+    claude_user_settings_path: Path = Path.home() / ".claude" / "settings.json"
     project_root_path = Path.cwd()
     if not is_valid_project_root(project_root_path):
         print(
@@ -79,7 +78,7 @@ def grant_permissions_for_current_directory() -> None:
     environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
         project_path=project_path
     )
-    settings = load_settings(CLAUDE_USER_SETTINGS_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
@@ -92,12 +91,12 @@ def grant_permissions_for_current_directory() -> None:
     )
     if total_changes_count == 0:
         print(f"Project path: {project_path}")
-        print(f"Settings file: {CLAUDE_USER_SETTINGS_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)
+    save_settings(claude_user_settings_path, settings)
     print(f"Project path: {project_path}")
-    print(f"Settings file: {CLAUDE_USER_SETTINGS_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}")

package/skills/bugteam/{revoke_project_claude_permissions.py → scripts/revoke_project_claude_permissions.py}

@@ -9,7 +9,6 @@ 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))
 
@@ -25,25 +24,24 @@ from _claude_permissions_common import (  # noqa: E402
 )
 
 
-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:
+def remove_values_from_list(target_list: list[object], 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
+        each_value
+        for each_value in target_list
+        if not (isinstance(each_value, str) and each_value 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]
+    settings: dict[str, object], rules_to_remove: list[str]
 ) -> int:
     permissions_section = settings.get("permissions")
     if not isinstance(permissions_section, dict):
@@ -55,7 +53,7 @@ def remove_rules_from_allow_list(
 
 
 def remove_directory_from_additional_directories(
-    settings: dict[str, Any], directory_path: str
+    settings: dict[str, object], directory_path: str
 ) -> int:
     permissions_section = settings.get("permissions")
     if not isinstance(permissions_section, dict):
@@ -67,7 +65,7 @@ def remove_directory_from_additional_directories(
 
 
 def remove_auto_mode_environment_entry(
-    settings: dict[str, Any], entry_text: str
+    settings: dict[str, object], entry_text: str
 ) -> int:
     auto_mode_section = settings.get("autoMode")
     if not isinstance(auto_mode_section, dict):
@@ -78,7 +76,7 @@ def remove_auto_mode_environment_entry(
     return remove_values_from_list(existing_environment, {entry_text})
 
 
-def prune_settings_after_revoke(settings: dict[str, Any]) -> None:
+def prune_settings_after_revoke(settings: dict[str, object]) -> None:
     prune_empty_list_then_empty_section(settings, "permissions", "allow")
     prune_empty_list_then_empty_section(
         settings, "permissions", "additionalDirectories"
@@ -87,6 +85,7 @@ def prune_settings_after_revoke(settings: dict[str, Any]) -> None:
 
 
 def revoke_permissions_for_current_directory() -> None:
+    claude_user_settings_path: Path = Path.home() / ".claude" / "settings.json"
     project_root_path = Path.cwd()
     if not is_valid_project_root(project_root_path):
         print(
@@ -100,7 +99,7 @@ def revoke_permissions_for_current_directory() -> None:
     environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
         project_path=project_path
     )
-    settings = load_settings(CLAUDE_USER_SETTINGS_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
@@ -115,13 +114,13 @@ def revoke_permissions_for_current_directory() -> None:
     )
     if total_changes_count == 0:
         print(f"Project path: {project_path}")
-        print(f"Settings file: {CLAUDE_USER_SETTINGS_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)
+    save_settings(claude_user_settings_path, settings)
     print(f"Project path: {project_path}")
-    print(f"Settings file: {CLAUDE_USER_SETTINGS_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(

package/skills/bugteam/sources.md

@@ -0,0 +1,93 @@
+# Bugteam skill — sources and citations
+
+Canonical URLs and verbatim quotes that `SKILL.md` relies on. Load this file when verifying wording against upstream documentation or when expanding citations. Domain-oriented narrative (without duplicating these quotes) lives under [`reference/README.md`](reference/README.md).
+
+---
+
+## Claude Code — Agent teams
+
+**URL:** [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams)
+
+**Enable flag (operational link used in refusal copy):** [Enable agent teams](https://code.claude.com/docs/en/agent-teams#enable-agent-teams)
+
+### Teammate context isolation (clean-room basis)
+
+Direct quote:
+
+> "Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over."
+
+**Skill use:** Independent context per teammate enforces the clean-room audit property; the same sentence is cited again where per-loop `Agent` spawns are justified.
+
+### Subagents vs agent teams
+
+Direct quote:
+
+> "Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own."
+
+**Skill use:** Subagents return into the lead context (accumulates across loops); agent-team teammates do not pollute the lead. This skill needs the independent-context property.
+
+### Team creation in natural language
+
+Direct quote:
+
+> "tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt."
+
+**Skill use:** Maps to the `TeamCreate` tool step in the process section.
+
+### Referencing subagent types when spawning teammates
+
+Direct quote:
+
+> "When spawning a teammate, you can reference a subagent type from any subagent scope: project, user, plugin, or CLI-defined. This lets you define a role once... and reuse it both as a delegated subagent and as an agent team teammate."
+
+**Skill use:** Bugfind / bugfix roles reference `code-quality-agent` and `clean-coder` by subagent type name.
+
+### Lead cleanup and active teammates
+
+Direct quote:
+
+> "When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first."
+
+**Skill use:** Step 4 shutdown sequence before `TeamDelete`.
+
+### Ending the team
+
+Direct quote:
+
+> "When you're done, ask the lead to clean up: 'Clean up the team'."
+
+**Skill use:** Maps to calling `TeamDelete()` after shutdown messages.
+
+---
+
+## Claude — Agent skills best practices
+
+**Base URL:** [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+### Table of contents for long skills
+
+**URL:** [Structure longer reference files with table of contents](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#structure-longer-reference-files-with-table-of-contents)
+
+**Skill use:** Justifies the top-of-file Contents section so partial reads still expose scope.
+
+### Progressive disclosure and utility scripts
+
+**URL:** [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns)
+
+**Skill use:** Shell helpers live under `scripts/` and are executed, not loaded as primary context.
+
+### Concise is key
+
+**URL:** [Concise is key](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#concise-is-key)
+
+Direct quotes:
+
+> "However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context."
+
+Heading and following line (section uses the heading as its own emphasis):
+
+> Default assumption: Claude is already very smart
+
+> "Only add context Claude doesn't already have. Challenge each piece of information:"
+
+**Skill use:** `SKILL.md` revisions that drop redundant narration and trust the reader’s prior knowledge.