claude-dev-env 2.13.0 → 2.14.1

package/skills/codex-review/AGENTS.md

@@ -0,0 +1,46 @@
+# codex-review
+
+Runs OpenAI Codex as a local PR or uncommitted-diff reviewer: opt-out gate, version/shape probe, target pick, classifying review (`codex exec … review --json`), outcome classification, and handoff of findings into `pr-fix-protocol`. Triggered by `/codex-review`, `codex review`, `run codex review`, `babysit codex review`, or `codex as a PR reviewer`.
+
+## Purpose
+
+One Codex review pass per invocation. The skill owns sequence and skill-level classification (`down` / `clean` / `findings`). The headless wrapper is capture-only (`completed` / `codex_down` plus raw fields). Shared peers own opt-out parsing (`reviews_disabled.py` / `reviewer-gates`) and the fix sequence (`pr-fix-protocol`). Observed raw CLI surface, wrapper capture contract, probe signals, failure fixtures, auth modes, cloud runbook, and classification map live under `reference/cli-contract.md`; PR-loop wiring lives under `reference/loop-integration.md`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Flow skeleton: opt-out → probe → target → wrapper → classify → fix handoff; refusals; sub-skills table; ground rules. |
+| `reference/cli-contract.md` | Wrapper entrypoint and argv; version/shape probe; success JSONL and findings parse; failure classes tied to fixtures; auth modes; cloud runbook. |
+| `reference/loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; re-entry after fixes. |
+| `scripts/run_codex_review.py` | Headless capture wrapper: probes, single-target argv, JSONL capture, `completed` / `codex_down`. |
+| `scripts/test_run_codex_review.py` | Behavioral tests for `run_codex_review`. |
+| `scripts/codex_down_classifier.py` | Maps a Codex run's exit code and stream text to a failure detail class and the gate outcome class (`completed` / `codex_down`). |
+| `scripts/parse_codex_findings.py` | Parses reviewer text into findings: fenced JSON first, then the freeform bullet shape, then a single floor finding. |
+| `scripts/codex_usage_probe.py` | Weekly usage probe CLI: app-server rate-limits read, null-on-unknown JSON report. |
+| `scripts/test_codex_usage_probe.py` | Unit tests for the weekly usage probe and gate helper. |
+| `scripts/codex_review_scripts_constants/run_constants.py` | Named constants package for skill scripts: binary name, flags, prompt, probe pattern, timeout, exit sentinels, JSONL keys, capture outcome labels. |
+| `scripts/codex_review_scripts_constants/codex_usage_probe_constants.py` | Named constants for the weekly usage probe. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Progressive-disclosure pages for cli-contract and loop-integration. |
+| `scripts/` | Capture wrapper, classifier, findings parser, weekly usage probe, tests, fixtures, and constants package. |
+
+## Environment opt-out
+
+Step 0 runs `reviews_disabled.py --reviewer codex` before any probe or review invoke.
+
+| Gate exit | Meaning for this skill |
+|---|---|
+| 0 | Opt-out active — refuse with the opt-out line in `SKILL.md` and stop |
+| 1 | Continue the flow |
+| Any other | Blocker — stop; do not invent an opt-out refusal |
+
+Set `CLAUDE_REVIEWS_DISABLED=codex` to disable. This package does not re-parse `CLAUDE_REVIEWS_DISABLED`; the shared gate owns the token parse.
+
+## Scripts surface
+
+`scripts/` holds the capture wrapper (`run_codex_review.py`), the down classifier (`codex_down_classifier.py`), the findings parser (`parse_codex_findings.py`), the weekly usage probe (`codex_usage_probe.py`), their tests, fixtures, and named constants. The wrapper returns capture fields only (`completed` / `codex_down`); agents map those fields to skill classes via the skill-class map and parse findings through `parse_codex_findings`. Classify only from a `codex exec … review --json` JSONL stream; do not invent a non-JSONL parse.

package/skills/codex-review/CLAUDE.md

@@ -1,46 +1 @@
-# codex-review
-
-Runs OpenAI Codex as a local PR or uncommitted-diff reviewer: opt-out gate, version/shape probe, target pick, classifying review (`codex exec … review --json`), outcome classification, and handoff of findings into `pr-fix-protocol`. Triggered by `/codex-review`, `codex review`, `run codex review`, `babysit codex review`, or `codex as a PR reviewer`.
-
-## Purpose
-
-One Codex review pass per invocation. The skill owns sequence and skill-level classification (`down` / `clean` / `findings`). The headless wrapper is capture-only (`completed` / `codex_down` plus raw fields). Shared peers own opt-out parsing (`reviews_disabled.py` / `reviewer-gates`) and the fix sequence (`pr-fix-protocol`). Observed raw CLI surface, wrapper capture contract, probe signals, failure fixtures, auth modes, cloud runbook, and classification map live under `reference/cli-contract.md`; PR-loop wiring lives under `reference/loop-integration.md`.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Flow skeleton: opt-out → probe → target → wrapper → classify → fix handoff; refusals; sub-skills table; ground rules. |
-| `reference/cli-contract.md` | Wrapper entrypoint and argv; version/shape probe; success JSONL and findings parse; failure classes tied to fixtures; auth modes; cloud runbook. |
-| `reference/loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; re-entry after fixes. |
-| `scripts/run_codex_review.py` | Headless capture wrapper: probes, single-target argv, JSONL capture, `completed` / `codex_down`. |
-| `scripts/test_run_codex_review.py` | Behavioral tests for `run_codex_review`. |
-| `scripts/codex_down_classifier.py` | Maps a Codex run's exit code and stream text to a failure detail class and the gate outcome class (`completed` / `codex_down`). |
-| `scripts/parse_codex_findings.py` | Parses reviewer text into findings: fenced JSON first, then the freeform bullet shape, then a single floor finding. |
-| `scripts/codex_usage_probe.py` | Weekly usage probe CLI: app-server rate-limits read, null-on-unknown JSON report. |
-| `scripts/test_codex_usage_probe.py` | Unit tests for the weekly usage probe and gate helper. |
-| `scripts/codex_review_scripts_constants/run_constants.py` | Named constants package for skill scripts: binary name, flags, prompt, probe pattern, timeout, exit sentinels, JSONL keys, capture outcome labels. |
-| `scripts/codex_review_scripts_constants/codex_usage_probe_constants.py` | Named constants for the weekly usage probe. |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Progressive-disclosure pages for cli-contract and loop-integration. |
-| `scripts/` | Capture wrapper, classifier, findings parser, weekly usage probe, tests, fixtures, and constants package. |
-
-## Environment opt-out
-
-Step 0 runs `reviews_disabled.py --reviewer codex` before any probe or review invoke.
-
-| Gate exit | Meaning for this skill |
-|---|---|
-| 0 | Opt-out active — refuse with the opt-out line in `SKILL.md` and stop |
-| 1 | Continue the flow |
-| Any other | Blocker — stop; do not invent an opt-out refusal |
-
-Set `CLAUDE_REVIEWS_DISABLED=codex` to disable. This package does not re-parse `CLAUDE_REVIEWS_DISABLED`; the shared gate owns the token parse.
-
-## Scripts surface
-
-`scripts/` holds the capture wrapper (`run_codex_review.py`), the down classifier (`codex_down_classifier.py`), the findings parser (`parse_codex_findings.py`), the weekly usage probe (`codex_usage_probe.py`), their tests, fixtures, and named constants. The wrapper returns capture fields only (`completed` / `codex_down`); agents map those fields to skill classes via the skill-class map and parse findings through `parse_codex_findings`. Classify only from a `codex exec … review --json` JSONL stream; do not invent a non-JSONL parse.
+@AGENTS.md

package/skills/codex-review/reference/AGENTS.md

@@ -0,0 +1,15 @@
+# codex-review/reference
+
+Reference pages for the `codex-review` skill. `SKILL.md` cites these files for CLI contract and PR-loop integration detail.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `cli-contract.md` | Observed Codex CLI review surface: classifying `codex exec … review --json` path, wrapper capture (`completed` / `codex_down`), probe signals, success JSONL and findings parse, fixture-backed failure classes, skill-class map (`down` / `clean` / `findings`), auth modes, and cloud runbook. |
+| `loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; target selection; skill-class vocabulary; findings handoff; re-entry after a fix push. |
+
+## Conventions
+
+- Each page is the stable home for one child workstream. Cross-references from `SKILL.md` use these paths.
+- Keep one level deep: `SKILL.md` links here; orchestrator-owned detail links out to pr-converge / autoconverge pages rather than restating them.

package/skills/codex-review/reference/CLAUDE.md

@@ -1,15 +1 @@
-# codex-review/reference
-
-Reference pages for the `codex-review` skill. `SKILL.md` cites these files for CLI contract and PR-loop integration detail.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `cli-contract.md` | Observed Codex CLI review surface: classifying `codex exec … review --json` path, wrapper capture (`completed` / `codex_down`), probe signals, success JSONL and findings parse, fixture-backed failure classes, skill-class map (`down` / `clean` / `findings`), auth modes, and cloud runbook. |
-| `loop-integration.md` | Gate placement in pr-converge and autoconverge; threshold rule; opt-out token; state fields; target selection; skill-class vocabulary; findings handoff; re-entry after a fix push. |
-
-## Conventions
-
-- Each page is the stable home for one child workstream. Cross-references from `SKILL.md` use these paths.
-- Keep one level deep: `SKILL.md` links here; orchestrator-owned detail links out to pr-converge / autoconverge pages rather than restating them.
+@AGENTS.md

package/skills/codex-review/scripts/codex_review_scripts_constants/AGENTS.md

@@ -0,0 +1,18 @@
+# codex-review/scripts/codex_review_scripts_constants
+
+Python package of named constants imported by codex-review scripts. Importing from this package keeps magic values out of script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `__init__.py` | Package marker and package docstring. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, and capture outcome class labels for `run_codex_review.py`. |
+| `findings_constants.py` | Finding field keys, fenced-JSON and freeform patterns for `parse_codex_findings.py`. |
+| `classifier_constants.py` | Failure class names and stream markers for `codex_down_classifier.py`. |
+| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, JSONL capture filename and newline mode, and capture outcome class labels for `run_codex_review.py`. |
+| `codex_usage_probe_constants.py` | The weekly-usage probe CLI: gate threshold, report JSON keys, app-server JSON-RPC surface, rate-limit field keys, weekly-window sizing, text-status parse patterns, source labels, and exit codes. |
+
+## Convention
+
+Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.

package/skills/codex-review/scripts/codex_review_scripts_constants/CLAUDE.md

@@ -1,18 +1 @@
-# codex-review/scripts/codex_review_scripts_constants
-
-Python package of named constants imported by codex-review scripts. Importing from this package keeps magic values out of script bodies.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `__init__.py` | Package marker and package docstring. |
-| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, and capture outcome class labels for `run_codex_review.py`. |
-| `findings_constants.py` | Finding field keys, fenced-JSON and freeform patterns for `parse_codex_findings.py`. |
-| `classifier_constants.py` | Failure class names and stream markers for `codex_down_classifier.py`. |
-| `run_constants.py` | Binary name, flag strings, custom-instructions prompt, version-probe pattern, timeout default, decode/timeout exit sentinels, flag_token_pattern suffix (whole-token shape match), JSONL keys, JSONL capture filename and newline mode, and capture outcome class labels for `run_codex_review.py`. |
-| `codex_usage_probe_constants.py` | The weekly-usage probe CLI: gate threshold, report JSON keys, app-server JSON-RPC surface, rate-limit field keys, weekly-window sizing, text-status parse patterns, source labels, and exit codes. |
-
-## Convention
-
-Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.
+@AGENTS.md

package/skills/codex-review/test_skill_scaffold.py

@@ -9,7 +9,7 @@ from pathlib import Path
 
 SKILL_DIRECTORY = Path(__file__).resolve().parent
 SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
-PACKAGE_MAP_PATH = SKILL_DIRECTORY / "CLAUDE.md"
+PACKAGE_MAP_PATH = SKILL_DIRECTORY / "AGENTS.md"
 REFERENCE_DIRECTORY = SKILL_DIRECTORY / "reference"
 PACKAGE_ROOT = SKILL_DIRECTORY.parents[1]
 PYPROJECT_PATH = PACKAGE_ROOT / "pyproject.toml"
@@ -131,7 +131,7 @@ def test_scripts_surface_names_capture_wrapper_and_constants() -> None:
     skill_text = _read_skill_text()
     package_map_text = PACKAGE_MAP_PATH.read_text(encoding="utf-8")
     constants_map_text = (
-        SKILL_DIRECTORY / "scripts" / "codex_review_scripts_constants" / "CLAUDE.md"
+        SKILL_DIRECTORY / "scripts" / "codex_review_scripts_constants" / "AGENTS.md"
     ).read_text(encoding="utf-8")
     wrapper_path = SKILL_DIRECTORY / "scripts" / "run_codex_review.py"
 
@@ -168,7 +168,7 @@ def test_skill_body_stays_under_line_cap() -> None:
     assert skill_line_count < MAXIMUM_SKILL_BODY_LINE_COUNT
 
 
-def test_package_map_claude_md_exists() -> None:
+def test_package_map_agents_md_exists() -> None:
     package_map_text = PACKAGE_MAP_PATH.read_text(encoding="utf-8")
 
     assert "codex-review" in package_map_text

package/skills/copilot-review/AGENTS.md

@@ -0,0 +1,18 @@
+# copilot-review
+
+Spawns a background subagent that polls the GitHub Copilot reviewer on the current PR, fixes unaddressed findings, and re-requests review each tick until the PR is clean. Triggered by `/copilot-review`, `watch copilot`, `babysit copilot review`, or `keep re-requesting copilot`.
+
+## Purpose
+
+The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 6-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, resolve each addressed thread, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, three consecutive ticks with no Copilot review at the current HEAD, or after 20 ticks.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+| `templates/subagent-prompt.md` | The background watcher prompt Step 3 passes to the subagent word for word, with placeholders for PR number, owner, repo, branch, and HEAD SHA. |
+
+## Environment opt-out
+
+Set `CLAUDE_REVIEWS_DISABLED=copilot` to disable. The skill checks this before spawning anything.

package/skills/copilot-review/CLAUDE.md

@@ -1,18 +1 @@
-# copilot-review
-
-Spawns a background subagent that polls the GitHub Copilot reviewer on the current PR, fixes unaddressed findings, and re-requests review each tick until the PR is clean. Triggered by `/copilot-review`, `watch copilot`, `babysit copilot review`, or `keep re-requesting copilot`.
-
-## Purpose
-
-The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 6-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, resolve each addressed thread, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, three consecutive ticks with no Copilot review at the current HEAD, or after 20 ticks.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
-| `templates/subagent-prompt.md` | The background watcher prompt Step 3 passes to the subagent word for word, with placeholders for PR number, owner, repo, branch, and HEAD SHA. |
-
-## Environment opt-out
-
-Set `CLAUDE_REVIEWS_DISABLED=copilot` to disable. The skill checks this before spawning anything.
+@AGENTS.md

package/skills/everything-search/AGENTS.md

@@ -0,0 +1,17 @@
+# everything-search
+
+Fast file search on Windows using the Everything (voidtools) `es.exe` command-line tool. Triggered by `find files`, `search for files`, `locate files`, or any request to use Everything.
+
+## Purpose
+
+Searches files by extension, name, date modified, size, or path against Everything's real-time index. Returns results instantly regardless of drive size. The skill covers the correct `es.exe` path, search operator syntax, multi-extension patterns, output options, and the junction/symlink note (Everything indexes real NTFS paths only — not junctions or mapped drives).
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Command syntax for WSL and Windows paths, all search operators (`ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT), output flags (`-sort`, `-n`, `-size`), worked examples, and a junction/drive-mapping lookup table. |
+
+## When to use
+
+Use for file-system searches by name, extension, size, or date. For content searches use Grep. If a path is a junction or mapped drive and Everything returns nothing, translate to the real NTFS path or fall back to the Glob tool.

package/skills/everything-search/CLAUDE.md

@@ -1,17 +1 @@
-# everything-search
-
-Fast file search on Windows using the Everything (voidtools) `es.exe` command-line tool. Triggered by `find files`, `search for files`, `locate files`, or any request to use Everything.
-
-## Purpose
-
-Searches files by extension, name, date modified, size, or path against Everything's real-time index. Returns results instantly regardless of drive size. The skill covers the correct `es.exe` path, search operator syntax, multi-extension patterns, output options, and the junction/symlink note (Everything indexes real NTFS paths only — not junctions or mapped drives).
-
-## Key file
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Command syntax for WSL and Windows paths, all search operators (`ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT), output flags (`-sort`, `-n`, `-size`), worked examples, and a junction/drive-mapping lookup table. |
-
-## When to use
-
-Use for file-system searches by name, extension, size, or date. For content searches use Grep. If a path is a junction or mapped drive and Everything returns nothing, translate to the real NTFS path or fall back to the Glob tool.
+@AGENTS.md

package/skills/fresh-branch/AGENTS.md

@@ -0,0 +1,14 @@
+# fresh-branch
+
+Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under a configured root. Default: `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Optional absolute `--worktree-root` relocates the root (agent and branch still nest under it). Relative roots and path escape fail closed. Does not push, open a PR, or run `checkout -b` in the caller tree.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Phases, checklist, configured-root contract, execute-vs-read for the CLI, gotchas |
+| `scripts/create_fresh_branch.py` | Deterministic CLI: resolve configured root (fail closed before fetch), fetch base, `git worktree add -b`, JSON stdout |
+| `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
+| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos (default root, explicit root, escape, collisions) |
+| `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
+| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for CLI flags and error strings |

package/skills/fresh-branch/CLAUDE.md

@@ -1,14 +1 @@
-# fresh-branch
-
-Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under a configured root. Default: `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Optional absolute `--worktree-root` relocates the root (agent and branch still nest under it). Relative roots and path escape fail closed. Does not push, open a PR, or run `checkout -b` in the caller tree.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Phases, checklist, configured-root contract, execute-vs-read for the CLI, gotchas |
-| `scripts/create_fresh_branch.py` | Deterministic CLI: resolve configured root (fail closed before fetch), fetch base, `git worktree add -b`, JSON stdout |
-| `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
-| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos (default root, explicit root, escape, collisions) |
-| `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
-| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for CLI flags and error strings |
+@AGENTS.md

package/skills/grok-spawn/AGENTS.md

@@ -0,0 +1,28 @@
+# grok-spawn
+
+**Trigger:** `/grok-spawn`, "spawn grok workers", "grok worker fleet", "run this with grok workers", "headless grok batch".
+
+Orchestrator playbook for fleets of headless grok CLI workers. Composes
+`grok_worker_preflight.py` and `spawn_grok_batch.py` by name. Holds no spawn
+logic of its own. The calling session verifies results and owns every commit,
+push, and GitHub post.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Prompt-part templates and tool-profile flag docs the hub cites on demand. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry protocol: when to use, gotchas, preflight → batch spec → launch → collect → verify. |
+| `reference/worker-briefs.md` | Readonly investigation brief, build brief (edits and tests only), report contract. |
+| `reference/flag-profiles.md` | Readonly vs build flag sets, shared flags, leader-socket and stagger rules, `--agent` note. |
+
+## Entry point
+
+No skill-local scripts. Runtime lives in `$HOME/.claude/scripts/`
+(`grok_worker_preflight.py`, `spawn_grok_batch.py`, `grok_headless_runner.py`)
+after install. Constants live in `scripts/dev_env_scripts_constants/`.

package/skills/grok-spawn/CLAUDE.md

@@ -1,28 +1 @@
-# grok-spawn
-
-**Trigger:** `/grok-spawn`, "spawn grok workers", "grok worker fleet", "run this with grok workers", "headless grok batch".
-
-Orchestrator playbook for fleets of headless grok CLI workers. Composes
-`grok_worker_preflight.py` and `spawn_grok_batch.py` by name. Holds no spawn
-logic of its own. The calling session verifies results and owns every commit,
-push, and GitHub post.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Prompt-part templates and tool-profile flag docs the hub cites on demand. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Entry protocol: when to use, gotchas, preflight → batch spec → launch → collect → verify. |
-| `reference/worker-briefs.md` | Readonly investigation brief, build brief (edits and tests only), report contract. |
-| `reference/flag-profiles.md` | Readonly vs build flag sets, shared flags, leader-socket and stagger rules, `--agent` note. |
-
-## Entry point
-
-No skill-local scripts. Runtime lives in `$HOME/.claude/scripts/`
-(`grok_worker_preflight.py`, `spawn_grok_batch.py`, `grok_headless_runner.py`)
-after install. Constants live in `scripts/dev_env_scripts_constants/`.
+@AGENTS.md

package/skills/pr-converge/AGENTS.md

@@ -0,0 +1,32 @@
+# pr-converge skill
+
+Drives a draft PR to convergence by driving the internal passes to clean first — a code-review pass and a bugteam audit — then running Cursor Bugbot and Copilot as terminal confirmation gates, applying TDD fixes, posting inline replies, and re-triggering the external reviewers each tick until all are clean on the same HEAD and the PR is mergeable.
+
+**Trigger:** `/pr-converge`, "drive PR to convergence", "loop bugbot and bugteam", "babysit bugbot and bugteam", "until both are clean", "converge this PR".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full tick workflow, pre-flight checks, state schema, budget-aware tick boundaries, stop conditions |
+| `pr_converge_skill_constants/constants.py` | Runtime and API constants (bot logins, review states, GH API path templates, regex patterns) |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr_converge_skill_constants/` | Importable constants module shared by skill scripts |
+| `reference/` | Per-tick steps, convergence gates, fix protocol, obstacle runbooks, state schema, stop conditions, examples |
+| `scripts/` | Python helpers (bugbot check, convergence check, Copilot review fetcher, fix-reply poster, reflow tool) and their tests |
+| `workflows/` | ScheduleWakeup loop pacing specification (`pacer=schedule_wakeup`) |
+
+## Conventions
+
+- Pre-flight selects a pacer via `select_converge_pacer.py`: `schedule_wakeup` or `portable`. Missing `ScheduleWakeup` selects portable — it does not abort the skill.
+- On `pacer=schedule_wakeup`, each invocation runs one tick and the next advances via `ScheduleWakeup`. On `pacer=portable`, the session runs ticks continuously (continue or in-session poll) until convergence, a stop condition, or a budget handoff.
+- Loop state persists to `$CLAUDE_JOB_DIR/pr-converge-state.json` between ticks.
+- Isolation uses `EnterWorktree` when present; otherwise the portable driver git worktree path, then `preflight_worktree.py`.
+- All findings and PR reports state verified facts only — no hedging language.
+- The GitHub MCP (`pull_request_read`, `pull_request_review_write`) is the primary path for PR inspection; `gh api` is the fallback.
+- Three step-scoped agents (`fix_executor`, `thread_sweep`, `copilot_watch`) persist across ticks via the `persistent_agents` map in loop state; each tick resumes them with `SendMessage` and spawns a fresh named agent when a stored id is dead.
+- The tick delegates shared mechanics to three sibling sub-skills: `reviewer-gates` (opt-out, Copilot quota, Bugbot trigger), `pr-fix-protocol` (fix sequence + unresolved-thread sweep), and `pr-loop-lifecycle` (run open/close). Target resolution happens inline in `reference/per-tick.md` Steps 1 and 1.5. Audit posting follows the `_shared/pr-loop/post-audit-thread-contract.md` contract, run through `_shared/pr-loop/scripts/post_audit_thread.py`.

package/skills/pr-converge/CLAUDE.md

@@ -1,32 +1 @@
-# pr-converge skill
-
-Drives a draft PR to convergence by driving the internal passes to clean first — a code-review pass and a bugteam audit — then running Cursor Bugbot and Copilot as terminal confirmation gates, applying TDD fixes, posting inline replies, and re-triggering the external reviewers each tick until all are clean on the same HEAD and the PR is mergeable.
-
-**Trigger:** `/pr-converge`, "drive PR to convergence", "loop bugbot and bugteam", "babysit bugbot and bugteam", "until both are clean", "converge this PR".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full tick workflow, pre-flight checks, state schema, budget-aware tick boundaries, stop conditions |
-| `pr_converge_skill_constants/constants.py` | Runtime and API constants (bot logins, review states, GH API path templates, regex patterns) |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `pr_converge_skill_constants/` | Importable constants module shared by skill scripts |
-| `reference/` | Per-tick steps, convergence gates, fix protocol, obstacle runbooks, state schema, stop conditions, examples |
-| `scripts/` | Python helpers (bugbot check, convergence check, Copilot review fetcher, fix-reply poster, reflow tool) and their tests |
-| `workflows/` | ScheduleWakeup loop pacing specification (`pacer=schedule_wakeup`) |
-
-## Conventions
-
-- Pre-flight selects a pacer via `select_converge_pacer.py`: `schedule_wakeup` or `portable`. Missing `ScheduleWakeup` selects portable — it does not abort the skill.
-- On `pacer=schedule_wakeup`, each invocation runs one tick and the next advances via `ScheduleWakeup`. On `pacer=portable`, the session runs ticks continuously (continue or in-session poll) until convergence, a stop condition, or a budget handoff.
-- Loop state persists to `$CLAUDE_JOB_DIR/pr-converge-state.json` between ticks.
-- Isolation uses `EnterWorktree` when present; otherwise the portable driver git worktree path, then `preflight_worktree.py`.
-- All findings and PR reports state verified facts only — no hedging language.
-- The GitHub MCP (`pull_request_read`, `pull_request_review_write`) is the primary path for PR inspection; `gh api` is the fallback.
-- Three step-scoped agents (`fix_executor`, `thread_sweep`, `copilot_watch`) persist across ticks via the `persistent_agents` map in loop state; each tick resumes them with `SendMessage` and spawns a fresh named agent when a stored id is dead.
-- The tick delegates shared mechanics to three sibling sub-skills: `reviewer-gates` (opt-out, Copilot quota, Bugbot trigger), `pr-fix-protocol` (fix sequence + unresolved-thread sweep), and `pr-loop-lifecycle` (run open/close). Target resolution happens inline in `reference/per-tick.md` Steps 1 and 1.5. Audit posting follows the `_shared/pr-loop/post-audit-thread-contract.md` contract, run through `_shared/pr-loop/scripts/post_audit_thread.py`.
+@AGENTS.md

package/skills/pr-converge/pr_converge_skill_constants/AGENTS.md

@@ -0,0 +1,26 @@
+# pr_converge_skill_constants
+
+Importable Python constants module for the `pr-converge` skill. Script-specific constants (CLI args, markdown patterns, reflow settings) live in `scripts/pr_converge_scripts_constants/` and import from here.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `constants.py` | All runtime and API constants: bot logins, review states, GH API path templates, bugbot/bugteam detection patterns, exit codes |
+
+## Exported constants (selected)
+
+| Constant | Purpose |
+|---|---|
+| `CURSOR_BOT_LOGIN` | Login string for the Cursor bugbot reviewer |
+| `COPILOT_REVIEWER_LOGIN` | Login string for the Copilot reviewer bot |
+| `ALL_COPILOT_CLEAN_REVIEW_STATES` | Tuple of review states that count as clean for Copilot |
+| `BUGBOT_DIRTY_BODY_REGEX` | Regex that matches a bugbot review body reporting findings |
+| `GH_REVIEWS_PATH_TEMPLATE` | `gh api` path template for PR reviews |
+| `GH_INLINE_COMMENTS_PATH_TEMPLATE` | `gh api` path template for PR inline comments |
+
+## Conventions
+
+- All path templates use `str.format(**kwargs)` with keys `owner`, `repo`, `number`.
+- `packages/claude-dev-env/skills/pr-converge/scripts/pr_converge_scripts_constants/pr_converge_constants.py` re-exports everything here via `from pr_converge_skill_constants.constants import ...` so scripts can import from either location.

package/skills/pr-converge/pr_converge_skill_constants/CLAUDE.md

@@ -1,26 +1 @@
-# pr_converge_skill_constants
-
-Importable Python constants module for the `pr-converge` skill. Script-specific constants (CLI args, markdown patterns, reflow settings) live in `scripts/pr_converge_scripts_constants/` and import from here.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `constants.py` | All runtime and API constants: bot logins, review states, GH API path templates, bugbot/bugteam detection patterns, exit codes |
-
-## Exported constants (selected)
-
-| Constant | Purpose |
-|---|---|
-| `CURSOR_BOT_LOGIN` | Login string for the Cursor bugbot reviewer |
-| `COPILOT_REVIEWER_LOGIN` | Login string for the Copilot reviewer bot |
-| `ALL_COPILOT_CLEAN_REVIEW_STATES` | Tuple of review states that count as clean for Copilot |
-| `BUGBOT_DIRTY_BODY_REGEX` | Regex that matches a bugbot review body reporting findings |
-| `GH_REVIEWS_PATH_TEMPLATE` | `gh api` path template for PR reviews |
-| `GH_INLINE_COMMENTS_PATH_TEMPLATE` | `gh api` path template for PR inline comments |
-
-## Conventions
-
-- All path templates use `str.format(**kwargs)` with keys `owner`, `repo`, `number`.
-- `packages/claude-dev-env/skills/pr-converge/scripts/pr_converge_scripts_constants/pr_converge_constants.py` re-exports everything here via `from pr_converge_skill_constants.constants import ...` so scripts can import from either location.
+@AGENTS.md

package/skills/pr-converge/reference/AGENTS.md

@@ -0,0 +1,28 @@
+# pr-converge/reference
+
+Reference documents for the `pr-converge` skill. These files define the per-tick step sequence, convergence gates, fix protocol, stop conditions, state schema, multi-PR orchestration, and examples.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
+| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
+| `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
+| `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |
+| `ground-rules.md` | Non-negotiable constraints for the convergence loop |
+| `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
+| `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |
+| `multi-pr-orchestration.md` | How to run the loop across multiple PRs in parallel |
+| `examples.md` | Worked examples of tick sequences |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-obstacle runbooks for known failure modes in the convergence loop |
+
+## Conventions
+
+- `per-tick.md` is the primary reference loaded during each tick. The pacing workflow lives in `../workflows/schedule-wakeup-loop.md`.
+- Every gate in `convergence-gates.md` must produce evidence before the next gate runs.

package/skills/pr-converge/reference/CLAUDE.md

@@ -1,28 +1 @@
-# pr-converge/reference
-
-Reference documents for the `pr-converge` skill. These files define the per-tick step sequence, convergence gates, fix protocol, stop conditions, state schema, multi-PR orchestration, and examples.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `progress-checklist.md` | The per-tick eleven-step checklist (Step 0 open → Step 11 report), each step pointing to its spoke file |
-| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
-| `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
-| `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |
-| `ground-rules.md` | Non-negotiable constraints for the convergence loop |
-| `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
-| `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |
-| `multi-pr-orchestration.md` | How to run the loop across multiple PRs in parallel |
-| `examples.md` | Worked examples of tick sequences |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `obstacles/` | Per-obstacle runbooks for known failure modes in the convergence loop |
-
-## Conventions
-
-- `per-tick.md` is the primary reference loaded during each tick. The pacing workflow lives in `../workflows/schedule-wakeup-loop.md`.
-- Every gate in `convergence-gates.md` must produce evidence before the next gate runs.
+@AGENTS.md

package/skills/pr-converge/reference/obstacles/AGENTS.md

@@ -0,0 +1,23 @@
+# pr-converge/reference/obstacles
+
+Per-obstacle runbooks for known failure modes in the `pr-converge` convergence loop. Each file covers one specific obstacle: what causes it, how to detect it, and how to recover.
+
+## Files
+
+| File | Obstacle |
+|---|---|
+| `fix-post-replies.md` | Posting inline review replies fails or posts to the wrong thread |
+| `fix-publish-summary.md` | Publishing the bugteam summary comment fails |
+| `fix-push.md` | `git push` fails during a fix commit |
+| `fix-read-filelines.md` | Reading file line ranges for a fix fails |
+| `fix-reset-state.md` | State JSON becomes corrupt or inconsistent between ticks |
+| `fix-resolve-threads.md` | Resolving inline comment threads via GraphQL fails |
+| `fix-spawn-clean-coder.md` | Spawning the `clean-coder` subagent fails or produces no output |
+| `fix-stage-commit.md` | Staging or committing a fix fails |
+| `fix-trigger-bugbot.md` | Triggering Cursor Bugbot via an issue comment fails |
+| `fix-write-test.md` | Writing a failing test before a fix fails |
+
+## Conventions
+
+- Each runbook is loaded on demand when the convergence loop hits that specific obstacle.
+- Runbooks do not overlap with `per-tick.md`; they cover edge cases and recovery paths that fall outside the normal tick flow.

package/skills/pr-converge/reference/obstacles/CLAUDE.md

@@ -1,23 +1 @@
-# pr-converge/reference/obstacles
-
-Per-obstacle runbooks for known failure modes in the `pr-converge` convergence loop. Each file covers one specific obstacle: what causes it, how to detect it, and how to recover.
-
-## Files
-
-| File | Obstacle |
-|---|---|
-| `fix-post-replies.md` | Posting inline review replies fails or posts to the wrong thread |
-| `fix-publish-summary.md` | Publishing the bugteam summary comment fails |
-| `fix-push.md` | `git push` fails during a fix commit |
-| `fix-read-filelines.md` | Reading file line ranges for a fix fails |
-| `fix-reset-state.md` | State JSON becomes corrupt or inconsistent between ticks |
-| `fix-resolve-threads.md` | Resolving inline comment threads via GraphQL fails |
-| `fix-spawn-clean-coder.md` | Spawning the `clean-coder` subagent fails or produces no output |
-| `fix-stage-commit.md` | Staging or committing a fix fails |
-| `fix-trigger-bugbot.md` | Triggering Cursor Bugbot via an issue comment fails |
-| `fix-write-test.md` | Writing a failing test before a fix fails |
-
-## Conventions
-
-- Each runbook is loaded on demand when the convergence loop hits that specific obstacle.
-- Runbooks do not overlap with `per-tick.md`; they cover edge cases and recovery paths that fall outside the normal tick flow.
+@AGENTS.md