claude-dev-env 2.12.0 → 2.14.0

package/skills/autoconverge/workflow/converge.precatch.test.mjs

@@ -148,5 +148,5 @@ test('COMMIT_RECOVERY_MAX_ATTEMPTS is one and bounds the commitWithRecovery loop
   assert.match(convergeSource, /const COMMIT_RECOVERY_MAX_ATTEMPTS = 1/, 'expected a dedicated commit-recovery cap of one');
   assert.match(convergeSource, /const FIX_RECOVERY_MAX_ATTEMPTS = 2/, 'expected the wider verify-recovery cap to stay at two');
   const commitBody = functionSource('commitWithRecovery');
-  assert.match(commitBody, /attempt < COMMIT_RECOVERY_MAX_ATTEMPTS/, 'expected commitWithRecovery to bound its loop by the dedicated cap');
+  assert.match(commitBody, /attempt <= COMMIT_RECOVERY_MAX_ATTEMPTS/, 'expected commitWithRecovery to bound its loop by the dedicated cap');
 });

package/skills/bugteam/AGENTS.md

@@ -0,0 +1,30 @@
+# bugteam
+
+Runs an audit-fix loop on an open pull request until all findings are resolved or the 20-loop cap is reached. Triggered by `/bugteam`, `run the bug team`, `auto-fix the PR until clean`, or `loop audit and fix`.
+
+## Purpose
+
+Each loop: a `code-quality-agent` (fresh context, all A–Q audit categories) produces an outcome XML; a `clean-coder` agent applies every fix; the lead commits, pushes, and posts a GitHub PR review (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty). Grants `.claude/**` write permissions at the start and revokes them at the end.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — pre-flight call, refusals, the audit-posting step (runs the shared `post_audit_thread.py` helper), progress checklist, and situation-to-reference table. Read this first. |
+| `PROMPTS.md` | Spawn XML, A–Q category bindings, outcome XML schemas. |
+| `CONSTRAINTS.md` | Invariants — what the loop must never violate. |
+| `EXAMPLES.md` | Exit scenarios: converged, cap-reached, stuck, refusal, mixed-outcome. |
+| `sources.md` | Doc URLs and verbatim quotes cited in the skill body. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Expanded workflow detail loaded on demand (team setup, audit contract, GitHub PR review shape, teardown). |
+| `scripts/` | Python scripts executed by the lead or teammates at runtime. |
+
+## Environment controls
+
+- `CLAUDE_REVIEWS_DISABLED=bugteam` — disables the skill entirely (pre-flight exits 7).
+- `BUGTEAM_PREFLIGHT_SKIP=1` — skips pytest in pre-flight.
+- `BUGTEAM_REVIEWER_ACCOUNT=<login>` — names the alternate `gh` account for posting reviews when the PR author and reviewer identity match.

package/skills/bugteam/CLAUDE.md

@@ -1,30 +1 @@
-# bugteam
-
-Runs an audit-fix loop on an open pull request until all findings are resolved or the 20-loop cap is reached. Triggered by `/bugteam`, `run the bug team`, `auto-fix the PR until clean`, or `loop audit and fix`.
-
-## Purpose
-
-Each loop: a `code-quality-agent` (fresh context, all A–Q audit categories) produces an outcome XML; a `clean-coder` agent applies every fix; the lead commits, pushes, and posts a GitHub PR review (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty). Grants `.claude/**` write permissions at the start and revokes them at the end.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Hub — pre-flight call, refusals, the audit-posting step (runs the shared `post_audit_thread.py` helper), progress checklist, and situation-to-reference table. Read this first. |
-| `PROMPTS.md` | Spawn XML, A–Q category bindings, outcome XML schemas. |
-| `CONSTRAINTS.md` | Invariants — what the loop must never violate. |
-| `EXAMPLES.md` | Exit scenarios: converged, cap-reached, stuck, refusal, mixed-outcome. |
-| `sources.md` | Doc URLs and verbatim quotes cited in the skill body. |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Expanded workflow detail loaded on demand (team setup, audit contract, GitHub PR review shape, teardown). |
-| `scripts/` | Python scripts executed by the lead or teammates at runtime. |
-
-## Environment controls
-
-- `CLAUDE_REVIEWS_DISABLED=bugteam` — disables the skill entirely (pre-flight exits 7).
-- `BUGTEAM_PREFLIGHT_SKIP=1` — skips pytest in pre-flight.
-- `BUGTEAM_REVIEWER_ACCOUNT=<login>` — names the alternate `gh` account for posting reviews when the PR author and reviewer identity match.
+@AGENTS.md

package/skills/bugteam/CONSTRAINTS.md

@@ -13,7 +13,7 @@
 - **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
 - **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
 - **Fix subagent receives the latest audit as its input contract.** Each loop's fix run operates on the current audit's output and only that.
-- **Lead owns the final PR description rewrite only** (Step 4 Close substep via `pr-loop-lifecycle`), composed directly against `docs/PR_DESCRIPTION_GUIDE.md`.
+- **Lead owns the final PR description.** The lead applies the [description guide](../descriptions/SKILL.md#required-content) through `pr-loop-lifecycle`.
 
 ## Why this design
 

package/skills/bugteam/SKILL.md

@@ -29,6 +29,15 @@ and take `true` as the pass. When any check fails, run the
 `pr-loop-cloud-transport` skill first and route every `gh` operation in this
 skill through its substitution matrix.
 
+## Judgment guides
+
+Use the [review guide](../reviews/SKILL.md#review-workflow) to decide whether a
+changed behavior is a finding. Use the [comment guide](../comments/SKILL.md#writing-useful-review-comments)
+for posted findings and replies, the [description guide](../descriptions/SKILL.md#reviewing-a-description)
+for final PR context, the [emergency guide](../emergencies/SKILL.md#while-the-incident-is-active)
+for active incidents, and the [small-change guide](../small-cl/SKILL.md#reviewable-scope)
+when the diff needs a narrower review boundary.
+
 ## Pre-flight
 
 ```bash

package/skills/bugteam/reference/AGENTS.md

@@ -0,0 +1,20 @@
+# bugteam/reference
+
+Expanded workflow detail for the `bugteam` skill. Load a file from this directory when the orchestration stub in `SKILL.md` is not enough — for example, when debugging GitHub review shape, understanding gate semantics, or working through teardown edge cases.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `README.md` | Index of all files in this directory with one-line domain summaries. |
+| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
+| `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
+| `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
+| `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |
+| `copilot-gap-analysis.md` | Historical gap analysis (reference only). |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-step obstacle guides — one file per common failure point (e.g., write XML, resolve thread, push, test suite). |

package/skills/bugteam/reference/CLAUDE.md

@@ -1,20 +1 @@
-# bugteam/reference
-
-Expanded workflow detail for the `bugteam` skill. Load a file from this directory when the orchestration stub in `SKILL.md` is not enough — for example, when debugging GitHub review shape, understanding gate semantics, or working through teardown edge cases.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `README.md` | Index of all files in this directory with one-line domain summaries. |
-| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
-| `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
-| `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
-| `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |
-| `copilot-gap-analysis.md` | Historical gap analysis (reference only). |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `obstacles/` | Per-step obstacle guides — one file per common failure point (e.g., write XML, resolve thread, push, test suite). |
+@AGENTS.md

package/skills/bugteam/reference/audit-and-teammates.md

@@ -104,8 +104,10 @@ Repeat until an exit condition fires.
       action** below). Instructions: read the gate script’s stderr, edit the
       repo until a **re-run** of the **same** gate command exits **0**. On
       tiers 1 and 3 the headless worker edits and runs tests but never
-      commits or pushes — the lead stages with explicit `git add`, mints the
-      code-verifier verdict, then commits and pushes. Tier 2 keeps in-agent
+      commits or pushes — the lead stages with explicit `git add`, confirms the
+      gate output and changed behavior against the
+      [review guide](../../reviews/SKILL.md#review-workflow), then commits and
+      pushes. Tier 2 keeps in-agent
       commit and push with `mode="bypassPermissions"`. Repeat standards-fix
       spawns until the gate exits **0** or **5** failed gate rounds (each
       round = one worker session after a non-zero gate). If still non-zero
@@ -219,8 +221,9 @@ worker session after a non-zero gate).
      headless worker edits and runs tests but never commits or pushes. The
      lead session stages the worker's files itself with an explicit `git add`
      (the session edit tracker does not see files the lead did not edit),
-     mints the code-verifier verdict in its own context, then commits and
-     pushes — so the commit gate and the staged-commit scans fire on the real
+     confirms the gate output and changed behavior against the
+     [review guide](../../reviews/SKILL.md#review-workflow), then commits and
+     pushes — so the commit gate and the staged-commit scans run on the real
      diff. Re-run the gate command; if still non-zero, start the next round.
    - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
      that reason): spawn the Agent-tool worker with in-agent commit and push:
@@ -283,8 +286,9 @@ Pass finding comment URL, comment id, and thread node id for each finding
      and 3 the headless worker edits and runs tests but never commits or
      pushes. The lead session stages the worker's files itself with an
      explicit `git add` (the session edit tracker does not see files the lead
-     did not edit), mints the code-verifier verdict in its own context, then
-     commits and pushes — so the commit gate and the staged-commit scans fire
+     did not edit), confirms the gate output and changed behavior against the
+     [review guide](../../reviews/SKILL.md#review-workflow), then commits and
+     pushes — so the commit gate and the staged-commit scans run
      on the real diff. Read the outcome XML at
      `<worktree_path>/.bugteam-pr<N>-loop<L>.fix-outcomes.xml`. The **lead**
      posts one reply per finding using the unified template at

package/skills/bugteam/reference/obstacles/AGENTS.md

@@ -0,0 +1,24 @@
+# bugteam/reference/obstacles
+
+Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific failure point that can occur during an audit-fix loop. Load the matching file when a step fails rather than improvising a fix.
+
+## Files
+
+| File | Obstacle it addresses |
+|---|---|
+| `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
+| `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
+| `audit-walk-categories.md` | Walking all A–Q categories without skipping. |
+| `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
+| `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
+| `fix-apply-fixes.md` | Applying code fixes from the finding list. |
+| `fix-git-add-commit.md` | Staging and committing the fixed files. |
+| `fix-git-push.md` | Pushing the fix commit to the remote branch. |
+| `fix-post-reply.md` | Posting inline replies to finding threads on the PR. |
+| `fix-publish-summary.md` | Publishing the loop summary to the PR. |
+| `fix-py-compile.md` | Verifying Python syntax after fixes. |
+| `fix-read-files.md` | Reading the files referenced in a finding. |
+| `fix-resolve-thread.md` | Resolving a finding's review thread on GitHub. |
+| `fix-test-suite.md` | Running the test suite and interpreting failures. |
+| `fix-violation-count.md` | Counting open violations after a fix pass. |
+| `fix-write-xml.md` | Writing the per-fix XML record. |

package/skills/bugteam/reference/obstacles/CLAUDE.md

@@ -1,24 +1 @@
-# bugteam/reference/obstacles
-
-Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific failure point that can occur during an audit-fix loop. Load the matching file when a step fails rather than improvising a fix.
-
-## Files
-
-| File | Obstacle it addresses |
-|---|---|
-| `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
-| `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
-| `audit-walk-categories.md` | Walking all A–Q categories without skipping. |
-| `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
-| `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
-| `fix-apply-fixes.md` | Applying code fixes from the finding list. |
-| `fix-git-add-commit.md` | Staging and committing the fixed files. |
-| `fix-git-push.md` | Pushing the fix commit to the remote branch. |
-| `fix-post-reply.md` | Posting inline replies to finding threads on the PR. |
-| `fix-publish-summary.md` | Publishing the loop summary to the PR. |
-| `fix-py-compile.md` | Verifying Python syntax after fixes. |
-| `fix-read-files.md` | Reading the files referenced in a finding. |
-| `fix-resolve-thread.md` | Resolving a finding's review thread on GitHub. |
-| `fix-test-suite.md` | Running the test suite and interpreting failures. |
-| `fix-violation-count.md` | Counting open violations after a fix pass. |
-| `fix-write-xml.md` | Writing the per-fix XML record. |
+@AGENTS.md

package/skills/bugteam/scripts/AGENTS.md

@@ -0,0 +1,30 @@
+# bugteam/scripts
+
+Python scripts executed by the bugteam lead or teammates at runtime. These are not loaded into context as instructions — they run as subprocess calls from within the skill workflow.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `bugteam_preflight.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/preflight.py`. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
+| `bugteam_fix_hookspath.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/fix_hookspath.py`. Auto-remediates a stale `core.hooksPath` override. |
+| `bugteam_code_rules_gate.py` | Thin skill-path entry; re-exports shared `_shared/pr-loop/scripts/code_rules_gate.py` (of record). |
+| `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
+| `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
+| `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
+
+## Test files
+
+| File | Tests |
+|---|---|
+| `test_bugteam_preflight.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_preflight.py` |
+| `test_bugteam_code_rules_gate.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_code_rules_gate.py` |
+| `test_bugteam_fix_hookspath.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_fix_hookspath.py` |
+| `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
+| `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `bugteam_scripts_constants/` | Named constants imported by the scripts above. |

package/skills/bugteam/scripts/CLAUDE.md

@@ -1,30 +1 @@
-# bugteam/scripts
-
-Python scripts executed by the bugteam lead or teammates at runtime. These are not loaded into context as instructions — they run as subprocess calls from within the skill workflow.
-
-## Scripts
-
-| File | Purpose |
-|---|---|
-| `bugteam_preflight.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/preflight.py`. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
-| `bugteam_fix_hookspath.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/fix_hookspath.py`. Auto-remediates a stale `core.hooksPath` override. |
-| `bugteam_code_rules_gate.py` | Thin skill-path entry; re-exports shared `_shared/pr-loop/scripts/code_rules_gate.py` (of record). |
-| `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
-| `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
-| `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
-
-## Test files
-
-| File | Tests |
-|---|---|
-| `test_bugteam_preflight.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_preflight.py` |
-| `test_bugteam_code_rules_gate.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_code_rules_gate.py` |
-| `test_bugteam_fix_hookspath.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_fix_hookspath.py` |
-| `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
-| `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `bugteam_scripts_constants/` | Named constants imported by the scripts above. |
+@AGENTS.md

package/skills/bugteam/scripts/bugteam_scripts_constants/AGENTS.md

@@ -0,0 +1,18 @@
+# bugteam/scripts/bugteam_scripts_constants
+
+Python package of named constants imported by the bugteam scripts. Each module holds the constants for one script; importing from this package keeps magic values out of the script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `probe_code_rules_enforcer_check_constants.py` | `probe_code_rules_enforcer_check.py` — enforcer module path and function name constants. |
+| `reflow_skill_md_constants.py` | `reflow_skill_md.py` — line-length and formatting constants. |
+| `windows_safe_rmtree_constants.py` | `windows_safe_rmtree.py` — retry count and wait constants. |
+| `__init__.py` | Empty package marker. |
+
+Preflight, fix_hookspath, and code_rules_gate constants live under package shared `pr_loop_shared_constants` with the shared implementations.
+
+## 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/bugteam/scripts/bugteam_scripts_constants/CLAUDE.md

@@ -1,18 +1 @@
-# bugteam/scripts/bugteam_scripts_constants
-
-Python package of named constants imported by the bugteam scripts. Each module holds the constants for one script; importing from this package keeps magic values out of the script bodies.
-
-## Modules
-
-| File | Constants for |
-|---|---|
-| `probe_code_rules_enforcer_check_constants.py` | `probe_code_rules_enforcer_check.py` — enforcer module path and function name constants. |
-| `reflow_skill_md_constants.py` | `reflow_skill_md.py` — line-length and formatting constants. |
-| `windows_safe_rmtree_constants.py` | `windows_safe_rmtree.py` — retry count and wait constants. |
-| `__init__.py` | Empty package marker. |
-
-Preflight, fix_hookspath, and code_rules_gate constants live under package shared `pr_loop_shared_constants` with the shared implementations.
-
-## 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/bugteam/test_skill_additions.py

@@ -18,3 +18,12 @@ def test_skill_names_implementer_subagent_type():
 def test_skill_documents_bugbot_retrigger_flag():
     skill_text = _read_skill_text()
     assert "--bugbot-retrigger" in skill_text
+
+
+def test_skill_routes_judgment_to_canonical_guides() -> None:
+    skill_text = _read_skill_text()
+    assert "../reviews/SKILL.md#review-workflow" in skill_text
+    assert "../comments/SKILL.md#writing-useful-review-comments" in skill_text
+    assert "../descriptions/SKILL.md#reviewing-a-description" in skill_text
+    assert "../emergencies/SKILL.md#while-the-incident-is-active" in skill_text
+    assert "../small-cl/SKILL.md#reviewable-scope" in skill_text

package/skills/closeout/reference/handoff-prompt-template.md

@@ -55,7 +55,7 @@ Open a PR per filed issue below and drive each to convergence.
 ## Safety — never do these
 - Never run, merge, deploy, or sync the claude-dev-env publish pipeline. It is live in production (publishes to npm).
 - Never run the host repo's automations.
-- Never hand-edit .cursor/BUGBOT.md; it is generated from AGENTS.md.
+- Keep `.cursor/BUGBOT.md` aligned with the repository's review rules.
 
 ## Base branch and verification
 - Base branch: main

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/comments/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: comments
+description: >-
+  Draft, refine, or respond to pull-request review comments. Use when a user
+  asks to "write a review comment", "address review feedback", or "reply to a reviewer".
+---
+
+# Review Comment Guide
+
+## When to Use This Guide
+
+Use this guide to draft a finding, refine its tone, reply to reviewer feedback,
+or resolve a comment thread. Use the [review guide](../reviews/SKILL.md#review-judgment)
+to decide whether a concern merits a finding.
+
+## Writing Useful Review Comments
+
+Each comment names the affected behavior, the observed concern, the relevant
+evidence, and the expected outcome. Give the author enough context to choose an
+effective fix.
+
+- Use `Required` for a change that materially affects the review judgment.
+- Use `Consider`, `Nit`, or `FYI` for improvement, polish, and context.
+- Explain the technical rationale when the connection from evidence to outcome
+  needs context.
+- Recognize strong decisions and completed fixes with the same specificity.
+
+## Respectful and Actionable Feedback
+
+Treat every contributor as capable and acting in good faith. Keep feedback
+about the code, its behavior, and its effect on users or maintainers.
+
+- Consolidate a disagreement into one focused exchange with the relevant
+  context and reasoning.
+- Use proportionate language that directs attention to the required change.
+- Respect repository tooling and established formatting conventions.
+- Close a thread when its outcome satisfies the applicable review judgment.
+
+## Responding to Feedback
+
+Start with the substance of the feedback. Clarify the code, its tests, or its
+documentation when that gives future readers the needed context.
+
+Ask for clarification when the requested outcome remains unclear. Reply with
+the trade-off, evidence, and proposed resolution when an alternative approach
+better serves the stated goal.
+
+## Resolving Pushback
+
+Reassess a disputed finding against the repository rubric and the change's
+evidence. Keep advocating for a material improvement when the rationale remains
+sound, and accept an evidence-backed alternative that meets the same quality
+goal.
+
+Escalate to a maintainer or lead when product direction or code ownership is
+needed. Record the resulting decision in the pull request thread.
+
+## Related Guides
+
+- Use [reviews](../reviews/SKILL.md#review-workflow) for substantive code
+  assessment.
+- Use [small-cl](../small-cl/SKILL.md#responding-to-review) for author-side
+  review responses and focused follow-up work.
+- Use [emergencies](../emergencies/SKILL.md#while-the-incident-is-active) for
+  urgent production-change communication.