claude-dev-env 2.13.0 → 2.14.1

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -1,21 +1 @@
-# dev_env_scripts_constants
-
-Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
-| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
-| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
-| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
-| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
-| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
-| `__init__.py` | Empty package marker |
-
-## Convention
-
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies. `code_review_constants.py` also exports pure helpers that resolve review-loop terminals from those tokens.
+@AGENTS.md

package/scripts/sync_to_cursor/AGENTS.md

@@ -0,0 +1,23 @@
+# sync_to_cursor
+
+Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
+| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
+| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
+| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `__init__.py` | Empty package marker |
+
+## Layout resolution
+
+`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
+
+## Tests
+
+Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.

package/scripts/sync_to_cursor/CLAUDE.md

@@ -1,23 +1 @@
-# sync_to_cursor
-
-Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
-| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
-| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
-| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
-| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
-| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
-| `__init__.py` | Empty package marker |
-
-## Layout resolution
-
-`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
-
-## Tests
-
-Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.
+@AGENTS.md

package/scripts/test_active_capability_references.py

@@ -32,7 +32,7 @@ def test_inventory_includes_shipped_skill_and_agent_names() -> None:
 
 def test_strip_inert_fenced_blocks_drops_historical_examples() -> None:
     markdown = (
-        "Use /commit for commits.\n"
+        "Use /sr-loop for cleanup.\n"
         "```historical\n"
         "Use /qbug for bugs.\n"
         "```\n"
@@ -40,7 +40,7 @@ def test_strip_inert_fenced_blocks_drops_historical_examples() -> None:
     )
     stripped = strip_inert_fenced_blocks(markdown)
     assert "/qbug" not in stripped
-    assert "/commit" in stripped
+    assert "/sr-loop" in stripped
 
 
 def test_extract_active_capability_names_finds_slash_and_backticks() -> None:

package/scripts/test_validate_instruction_pairs.py

@@ -0,0 +1,90 @@
+import subprocess
+from pathlib import Path
+
+from validate_instruction_pairs import validate_repository
+
+
+def initialize_repository(repository_root: Path) -> None:
+    subprocess.run(["git", "init", "--quiet"], cwd=repository_root, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "tests@example.com"],
+        cwd=repository_root,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Instruction tests"],
+        cwd=repository_root,
+        check=True,
+    )
+
+
+def stage_instruction_files(repository_root: Path) -> None:
+    subprocess.run(["git", "add", "AGENTS.md", "CLAUDE.md"], cwd=repository_root, check=True)
+
+
+def test_exact_import_passes(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+    stage_instruction_files(tmp_path)
+
+    assert validate_repository(tmp_path) == []
+
+
+def test_claude_context_fails_exact_import_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n\nExtra context\n")
+    stage_instruction_files(tmp_path)
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("exactly import" in each_error for each_error in all_errors)
+
+
+def test_nearest_ancestor_import_passes(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    nested_directory = tmp_path / ".claude"
+    nested_directory.mkdir()
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (nested_directory / "CLAUDE.md").write_bytes(b"@../AGENTS.md\n")
+    subprocess.run(["git", "add", "AGENTS.md", ".claude/CLAUDE.md"], cwd=tmp_path, check=True)
+
+    assert validate_repository(tmp_path) == []
+
+
+def test_crlf_import_fails_line_ending_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\r\n")
+    stage_instruction_files(tmp_path)
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("exactly import" in each_error for each_error in all_errors)
+
+
+def test_executable_import_fails_git_mode_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+    stage_instruction_files(tmp_path)
+    subprocess.run(
+        ["git", "update-index", "--chmod=+x", "CLAUDE.md"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("Git mode 100644" in each_error for each_error in all_errors)
+
+
+def test_untracked_import_fails_tracking_check(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    (tmp_path / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (tmp_path / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+
+    all_errors = validate_repository(tmp_path)
+
+    assert any("Git mode 100644" in each_error for each_error in all_errors)

package/scripts/test_verify_installable_package.py

@@ -31,6 +31,7 @@ def test_load_manifest_lists_hooks_and_claude_md() -> None:
     all_root_files = mod.required_root_file_names(manifest)
     assert "hooks" in all_directories
     assert "output-styles" in all_directories
+    assert "AGENTS.md" in all_root_files
     assert "CLAUDE.md" in all_root_files
     assert MANIFEST_FILENAME in all_root_files
 
@@ -58,10 +59,12 @@ def test_surface_appears_in_tarball_members_for_directory_children() -> None:
     all_members = frozenset(
         {
             f"{TARBALL_PACKAGE_PREFIX}hooks/hooks.json",
+            f"{TARBALL_PACKAGE_PREFIX}AGENTS.md",
             f"{TARBALL_PACKAGE_PREFIX}CLAUDE.md",
         }
     )
     assert mod.surface_appears_in_tarball_members("hooks", all_members)
+    assert mod.surface_appears_in_tarball_members("AGENTS.md", all_members)
     assert mod.surface_appears_in_tarball_members("CLAUDE.md", all_members)
     assert not mod.surface_appears_in_tarball_members("missing-dir", all_members)
 
@@ -69,11 +72,12 @@ def test_surface_appears_in_tarball_members_for_directory_children() -> None:
 def test_missing_manifest_surfaces_in_tarball_reports_absent_root_file() -> None:
     manifest = {
         "directories": ["hooks"],
-        "root_files": ["CLAUDE.md", "codex-capability-map.json"],
+        "root_files": ["AGENTS.md", "CLAUDE.md", "codex-capability-map.json"],
     }
     all_members = frozenset(
         {
             f"{TARBALL_PACKAGE_PREFIX}hooks/hooks.json",
+            f"{TARBALL_PACKAGE_PREFIX}AGENTS.md",
             f"{TARBALL_PACKAGE_PREFIX}CLAUDE.md",
         }
     )

package/scripts/tests/AGENTS.md

@@ -0,0 +1,33 @@
+# scripts/tests
+
+pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
+
+## Test files
+
+| File | Covers |
+|---|---|
+| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
+| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
+| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
+| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
+
+## PowerShell test files
+
+| File | Covers |
+|---|---|
+| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
+
+## Running
+
+Python scripts (pytest):
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```

package/scripts/tests/CLAUDE.md

@@ -1,33 +1 @@
-# scripts/tests
-
-pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
-
-## Test files
-
-| File | Covers |
-|---|---|
-| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
-| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
-| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
-| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
-| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
-
-## PowerShell test files
-
-| File | Covers |
-|---|---|
-| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
-
-## Running
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```
+@AGENTS.md

package/scripts/tests/test_codex_compat_materializer.py

@@ -77,6 +77,42 @@ def test_discover_agents_returns_sorted_parsed_agents(tmp_path: Path) -> None:
     assert [agent.name for agent in agents] == ["Alpha", "Zulu"]
 
 
+def test_discover_agents_skips_instruction_aliases_and_keeps_real_agents(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "real-agent.md").write_text(
+        "---\nname: Real Agent\ndescription: real\n---\n",
+        encoding="utf-8",
+    )
+    (source / "CLAUDE.md").write_text("# Guidance\n", encoding="utf-8")
+    try:
+        (source / "AGENTS.md").symlink_to("CLAUDE.md")
+    except OSError as error:
+        pytest.skip(f"symlinks unavailable: {error}")
+
+    agents = materializer.discover_agents(MaterializerConfig(source, tmp_path / "target"))
+
+    assert [agent.name for agent in agents] == ["Real Agent"]
+
+
+def test_discover_agents_rejects_non_alias_reparse_points(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "real-agent.md").write_text(
+        "---\nname: Real Agent\ndescription: real\n---\n",
+        encoding="utf-8",
+    )
+    try:
+        (source / "linked-agent.md").symlink_to("real-agent.md")
+    except OSError as error:
+        pytest.skip(f"symlinks unavailable: {error}")
+
+    with pytest.raises(MaterializerError, match="source reparse point is not allowed"):
+        materializer.discover_agents(MaterializerConfig(source, tmp_path / "target"))
+
+
 def test_content_to_bytes_preserves_bytes_and_encodes_text() -> None:
     assert content_to_bytes(b"payload") == b"payload"
     assert content_to_bytes("payload") == b"payload"
@@ -662,4 +698,3 @@ def test_frontmatter_rejects_non_string_name() -> None:
             "---\nname: 1\ndescription: y\n---\n",
             "bad.md",
         )
-

package/scripts/validate_instruction_pairs.py

@@ -0,0 +1,183 @@
+"""Validate exact Claude instruction imports and regular Git file modes."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+git_directory_name = ".git"
+git_listing_commands = (
+    (("git", "ls-files", "--stage", "-z"), True),
+    (("git", "ls-files", "--others", "--exclude-standard", "-z"), False),
+)
+ascii_encoding_name = "ascii"
+utf8_encoding_name = "utf-8"
+regular_git_file_mode = "100644"
+canonical_instruction_names = frozenset(("AGENTS.md", "CLAUDE.md"))
+logger = logging.getLogger(__name__)
+
+
+def _read_git_paths_and_modes(
+    repository_root: Path,
+) -> tuple[set[Path], dict[Path, set[str]]]:
+    all_git_paths: set[Path] = set()
+    modes_by_path: dict[Path, set[str]] = {}
+    for each_command, each_has_git_mode in git_listing_commands:
+        completed_process = subprocess.run(
+            each_command,
+            cwd=repository_root,
+            capture_output=True,
+            check=True,
+        )
+        for each_record in completed_process.stdout.split(b"\0"):
+            if not each_record:
+                continue
+            if each_has_git_mode:
+                each_header, each_path_bytes = each_record.split(b"\t", 1)
+                each_mode = each_header.split(b" ", 1)[0].decode(ascii_encoding_name)
+                each_path = repository_root / Path(os.fsdecode(each_path_bytes))
+                modes_by_path.setdefault(each_path, set()).add(each_mode)
+            else:
+                each_path = repository_root / Path(os.fsdecode(each_record))
+            all_git_paths.add(each_path)
+    return all_git_paths, modes_by_path
+
+
+def _discover_named_files(
+    repository_root: Path,
+    all_git_paths: set[Path],
+    expected_name: str,
+) -> list[Path]:
+    all_candidate_paths = set(all_git_paths)
+    all_candidate_paths.update(repository_root.rglob("*"))
+    return sorted(
+        each_path
+        for each_path in all_candidate_paths
+        if git_directory_name not in each_path.parts
+        and each_path.name.casefold() == expected_name.casefold()
+    )
+
+
+def _find_nearest_agents_path(
+    claude_path: Path,
+    repository_root: Path,
+    agents_by_directory: dict[Path, Path],
+) -> Path | None:
+    each_directory = claude_path.parent
+    while True:
+        each_agents_path = agents_by_directory.get(each_directory)
+        if each_agents_path is not None:
+            return each_agents_path
+        if each_directory == repository_root:
+            return None
+        each_directory = each_directory.parent
+
+
+def _relative_import_path(claude_path: Path, agents_path: Path) -> str:
+    return Path(os.path.relpath(agents_path, claude_path.parent)).as_posix()
+
+
+def _expected_import_text(claude_path: Path, agents_path: Path) -> bytes:
+    return f"@{_relative_import_path(claude_path, agents_path)}\n".encode(
+        utf8_encoding_name
+    )
+
+
+def _is_regular_file(each_path: Path) -> bool:
+    try:
+        return stat.S_ISREG(each_path.lstat().st_mode)
+    except FileNotFoundError:
+        return False
+
+
+def validate_repository(repository_root: Path) -> list[str]:
+    """Validate instruction filenames, modes, and exact Claude imports.
+
+    Args:
+        repository_root: Repository directory containing the Git metadata.
+
+    Returns:
+        Human-readable validation errors, with an empty list for a valid tree.
+    """
+    repository_root = repository_root.resolve()
+    all_errors: list[str] = []
+    all_git_paths, modes_by_path = _read_git_paths_and_modes(repository_root)
+    all_agents_paths = _discover_named_files(
+        repository_root, all_git_paths, "AGENTS.md"
+    )
+    all_claude_paths = _discover_named_files(
+        repository_root, all_git_paths, "CLAUDE.md"
+    )
+    agents_by_directory = {
+        each_path.parent: each_path
+        for each_path in all_agents_paths
+        if each_path.name == "AGENTS.md"
+    }
+
+    for each_instruction_path in (*all_agents_paths, *all_claude_paths):
+        relative_path = each_instruction_path.relative_to(repository_root)
+        tracked_modes = modes_by_path.get(each_instruction_path, set())
+        if each_instruction_path.name not in canonical_instruction_names:
+            all_errors.append(f"Use the canonical filename: {relative_path}")
+        if not _is_regular_file(each_instruction_path):
+            all_errors.append(f"Use a regular file: {relative_path}")
+        if tracked_modes != {regular_git_file_mode}:
+            all_errors.append(
+                f"Commit the instruction file with Git mode 100644: {relative_path}"
+            )
+
+    for each_claude_path in all_claude_paths:
+        relative_claude_path = each_claude_path.relative_to(repository_root)
+        each_agents_path = _find_nearest_agents_path(
+            each_claude_path, repository_root, agents_by_directory
+        )
+        if each_agents_path is None:
+            all_errors.append(f"Add the nearest governing AGENTS.md: {relative_claude_path}")
+            continue
+        if not _is_regular_file(each_claude_path):
+            continue
+        expected_bytes = _expected_import_text(each_claude_path, each_agents_path)
+        actual_bytes = each_claude_path.read_bytes()
+        if actual_bytes != expected_bytes:
+            relative_import_path = _relative_import_path(
+                each_claude_path, each_agents_path
+            )
+            relative_agents_path = each_agents_path.relative_to(repository_root)
+            all_errors.append(
+                f"Make {relative_claude_path} exactly import "
+                f"@{relative_import_path} for {relative_agents_path}"
+            )
+
+    return all_errors
+
+
+def _parse_arguments() -> argparse.Namespace:
+    argument_parser = argparse.ArgumentParser(
+        description="Validate exact CLAUDE.md imports and regular AGENTS.md files."
+    )
+    argument_parser.add_argument(
+        "--repository-root",
+        type=Path,
+        default=Path.cwd(),
+        help="Repository root containing the .git directory.",
+    )
+    return argument_parser.parse_args()
+
+
+def _main() -> int:
+    parsed_arguments = _parse_arguments()
+    repository_root = parsed_arguments.repository_root.resolve()
+    all_errors = validate_repository(repository_root)
+    if all_errors:
+        for each_error in all_errors:
+            logger.error("%s", each_error)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

package/skills/AGENTS.md

@@ -0,0 +1,72 @@
+# Skills Directory
+
+Each skill is a self-contained folder Claude Code loads on demand. At startup, only the skill's `name` and `description` metadata load. The full `SKILL.md` body and any support files load only when a skill becomes relevant to the conversation.
+
+## Skill folder convention
+
+| Item | Role |
+|---|---|
+| `SKILL.md` | Required entry point. YAML frontmatter with `name` and `description` (the trigger). Body holds the skill's full instructions. |
+| `scripts/` | Python helper scripts the skill invokes at runtime. |
+| `workflow/` | `.mjs` workflow scripts run via the `Workflow` tool. |
+| `templates/` | Template files the skill or workflow renders at build time. |
+| `reference/` | Reference docs the skill cites or the workflow reads. |
+| `*_constants/` | Python package of named constants imported by `scripts/`. |
+
+Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. See `docs/references/skill-install-system.md` for the install pipeline.
+
+## Shared support code
+
+**`skills/_shared/`** — skill-local PR-loop helpers plus `@` stubs that name
+canonical homes under **`@~/.claude/_shared/`** (advisor protocol, PR-loop
+contracts, runtime scripts). Map: `skills/_shared/CLAUDE.md`. End-of-run gotchas: `skills/_shared/end-of-run-gotcha-recommendations.md`.
+
+## Skill groups
+
+**Planning and implementation**
+- `anthropic-plan` — creates a source-grounded plan packet before any code changes
+- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; a third-party host: max-tier Claude via CLI Claude-chain)
+- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; a third-party host's Claude CLI chain, no Agent-tool advisor spawn)
+- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable); consult cadence and weight live in `docs/references/advisor-tool.md`
+- `grokify` — builds a paste-ready Grok Build handoff with a Claude advisor charter
+- `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers (preflight, batch spec, `spawn_grok_batch.py`)
+
+**PR review and convergence**
+- `autoconverge` — autonomous single-run workflow that drives a PR to ready
+- `pr-converge` — paced convergence loop across `ScheduleWakeup` ticks
+- `bugteam` — open-loop audit-fix until convergence
+- `copilot-review` — requests and polls a GitHub Copilot review
+- `copilot-finding-triage` — tiers each Copilot gate finding, verifies each code concern with an executed check, then routes it (auto-fix a confirmed defect, resolve a refuted one, page the user only for an inconclusive one)
+- `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
+- `pr-fix-protocol` — applies reviewer findings as verified fixes and drives unresolved review threads to zero
+- `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
+- `pr-loop-cloud-transport` — six-step transport workflow that lets any PR-loop skill run in a session whose `gh` CLI is absent or cannot act on the PR (MCP schema load, origin/HEAD fix, identity rules, the gh-to-MCP substitution matrix, the Copilot status rule, and the post self-check)
+
+**Code review guides (Google eng-practices, adapted for an AI reviewer)**
+- `small-cl` — the Small CLs guide; refs: handling reviewer comments
+- `comments` — writing review comments and handling reviewer comments; refs: the review standard, pushback, respectful code reviews
+- `reviews` — the reviewer guide: standard, what to look for, navigating a CL, speed, pushback; refs: CL descriptions, review comments, emergencies, style guides, the two guide indexes
+- `descriptions` — writing good CL descriptions
+- `emergencies` — what counts as an emergency change; refs: what to look for, speed
+- Focused pull request guidance: [`small-cl/SKILL.md`](small-cl/SKILL.md)
+
+**Research and discovery**
+- `recall` — retrieves facts from memory files
+- `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
+- `everything-search` — file-system search via the Everything `es.exe` CLI
+- `beat-sheet` — reformats a reply as short single-line beats
+- `show` — creates and reviews inline visual explanations: diagrams, interactive widgets, mockups, charts, and illustrations
+
+**Session and workflow management**
+- `session-log` — logs a session report to the Obsidian vault
+- `session-tidy` — tidies the session folder
+- `task-build` — gathers open tasks
+- `issue-tracker` — one consistent way to create, update in place, and close GitHub issues for a work-stream: one epic parent with native sub-issues, dedup-first, marker-delimited body sections edited in place, and an epic checklist mirroring the children
+- `closeout` — session-end entry that harvests obstacles into issue-candidate records and delegates filing to the `issue-tracker` agent (skill fallback), keeping the user-validation gate on each draft
+- `privacy-hygiene` — full-repo personal-data and secret sweep plus remediation guide
+- `update` — updates the dev-env package
+- `fresh-branch` — creates a clean branch off main
+- `rebase` — rebases onto main
+- `usage-pause` — waits out the 5-hour usage window in ScheduleWakeup stages that keep agent contexts warm; probes the OAuth usage endpoint or takes a manual reset override
+- `skill-builder` — complete skill-building lifecycle
+- `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings