claude-dev-env 2.13.0 → 2.14.0

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/AGENTS.md

@@ -0,0 +1,24 @@
+# skills_pr_loop_constants
+
+Python package of named constants for the `pr-loop` shared scripts. All constants are `UPPER_SNAKE_CASE` module-level names imported by the sibling scripts.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
+| `audit_category_schema_constants.py` | Paths, regexes, and encoding constants for `audit_category_schema.py` (A-Q schema load and projection parity). |
+| `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
+| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
+| `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |
+| `portable_driver_constants.py` | Phase names, next-action tokens, wait delays, blockers, CLI flags, and result keys for `portable_converge_driver.py`. |
+| `converge_task_list_constants.py` | Task ids, kinds, and CLI flags for `build_converge_task_list.py`. |
+
+## Usage
+
+Scripts import directly from the package:
+
+```python
+from skills_pr_loop_constants.path_resolver_constants import PER_PR_WORKSPACE_TEMPLATE
+```

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -1,24 +1 @@
-# skills_pr_loop_constants
-
-Python package of named constants for the `pr-loop` shared scripts. All constants are `UPPER_SNAKE_CASE` module-level names imported by the sibling scripts.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
-| `audit_category_schema_constants.py` | Paths, regexes, and encoding constants for `audit_category_schema.py` (A-Q schema load and projection parity). |
-| `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
-| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
-| `pacer_constants.py` | Entry-skill names, pacer tokens, CLI flags, and result keys for `select_converge_pacer.py`. |
-| `portable_driver_constants.py` | Phase names, next-action tokens, wait delays, blockers, CLI flags, and result keys for `portable_converge_driver.py`. |
-| `converge_task_list_constants.py` | Task ids, kinds, and CLI flags for `build_converge_task_list.py`. |
-
-## Usage
-
-Scripts import directly from the package:
-
-```python
-from skills_pr_loop_constants.path_resolver_constants import PER_PR_WORKSPACE_TEMPLATE
-```
+@AGENTS.md

package/skills/anthropic-plan/AGENTS.md

@@ -0,0 +1,34 @@
+# anthropic-plan
+
+**Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
+
+Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | Python validator (`validate_packet.py`) that checks the packet's required files, placeholders, and consistency. |
+| `templates/` | Template files the workflow renders when building the packet (`README.md`, `build-prompt.md`, `reuse-audit.md`, `source-map.md`, `visual-plan.template.html`). |
+| `workflow/` | The `.mjs` workflow scripts and their test files. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry point. Full planning protocol, workflow contract, packet shape, and validation rules. |
+| `workflow/plan-packet.mjs` | Main workflow script. Reads repo context, writes the packet, runs the validator, spawns `plan-packet-validator`, runs the reuse audit, builds the visual HTML, and returns the packet path. |
+| `workflow/plan-packet.contract.test.mjs` | Contract tests for the workflow script. |
+| `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py` | Deterministic validator: checks required files, open questions, source-map strength, TDD coverage, and `packet.json` consistency. Exits with code 2 on failure. |
+| `templates/visual-plan.template.html` | Template for the single-file offline visual HTML the workflow builds after validation. |
+
+## Entry point
+
+```js
+Workflow({
+  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
+  args: { task: "<user request>", cwd: "<working directory>" }
+})
+```
+
+The session must be in a worktree (path has `.claude/worktrees/`) before calling the workflow.

package/skills/anthropic-plan/CLAUDE.md

@@ -1,34 +1 @@
-# anthropic-plan
-
-**Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
-
-Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The skill first drafts a short starting plan and gets the user's approval in plan mode (`EnterPlanMode` / `ExitPlanMode`); on approval it runs the workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `scripts/` | Python validator (`validate_packet.py`) that checks the packet's required files, placeholders, and consistency. |
-| `templates/` | Template files the workflow renders when building the packet (`README.md`, `build-prompt.md`, `reuse-audit.md`, `source-map.md`, `visual-plan.template.html`). |
-| `workflow/` | The `.mjs` workflow scripts and their test files. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Entry point. Full planning protocol, workflow contract, packet shape, and validation rules. |
-| `workflow/plan-packet.mjs` | Main workflow script. Reads repo context, writes the packet, runs the validator, spawns `plan-packet-validator`, runs the reuse audit, builds the visual HTML, and returns the packet path. |
-| `workflow/plan-packet.contract.test.mjs` | Contract tests for the workflow script. |
-| `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py` | Deterministic validator: checks required files, open questions, source-map strength, TDD coverage, and `packet.json` consistency. Exits with code 2 on failure. |
-| `templates/visual-plan.template.html` | Template for the single-file offline visual HTML the workflow builds after validation. |
-
-## Entry point
-
-```js
-Workflow({
-  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
-  args: { task: "<user request>", cwd: "<working directory>" }
-})
-```
-
-The session must be in a worktree (path has `.claude/worktrees/`) before calling the workflow.
+@AGENTS.md

package/skills/anthropic-plan/scripts/AGENTS.md

@@ -0,0 +1,11 @@
+# scripts
+
+Python scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `validate_packet.py` | Deterministic packet validator. Checks that all required files exist under `docs/plans/<slug>/`, that no placeholder text remains, that `packet.json` is consistent with the folder contents, and that the TDD plan is present. Exits with code 2 on failure; the workflow treats a non-zero exit as a blocking finding. |
+| `test_validate_packet.py` | Tests for `validate_packet.py`. |
+| `anthropic_plan_scripts_constants/` | Named constants package (`validate_packet_constants.py`) that lists every required relative path the validator checks. |

package/skills/anthropic-plan/scripts/CLAUDE.md

@@ -1,11 +1 @@
-# scripts
-
-Python scripts for the `anthropic-plan` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `validate_packet.py` | Deterministic packet validator. Checks that all required files exist under `docs/plans/<slug>/`, that no placeholder text remains, that `packet.json` is consistent with the folder contents, and that the TDD plan is present. Exits with code 2 on failure; the workflow treats a non-zero exit as a blocking finding. |
-| `test_validate_packet.py` | Tests for `validate_packet.py`. |
-| `anthropic_plan_scripts_constants/` | Named constants package (`validate_packet_constants.py`) that lists every required relative path the validator checks. |
+@AGENTS.md

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/AGENTS.md

@@ -0,0 +1,16 @@
+# anthropic_plan_scripts_constants
+
+Python package of named constants for `anthropic-plan/scripts/`.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `validate_packet_constants.py` | Defines `ALL_REQUIRED_RELATIVE_PATHS` — the tuple of every relative path that must exist inside a valid plan packet (e.g. `README.md`, `packet.json`, `context/source-map.md`, `implementation/tdd-plan.md`, `handoff/build-prompt.md`). Also defines `MARKDOWN_FILE_SUFFIX` and `EXIT_CODE_VALIDATION_FAILED`. |
+
+## Usage
+
+```python
+from anthropic_plan_scripts_constants.validate_packet_constants import ALL_REQUIRED_RELATIVE_PATHS
+```

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/CLAUDE.md

@@ -1,16 +1 @@
-# anthropic_plan_scripts_constants
-
-Python package of named constants for `anthropic-plan/scripts/`.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `validate_packet_constants.py` | Defines `ALL_REQUIRED_RELATIVE_PATHS` — the tuple of every relative path that must exist inside a valid plan packet (e.g. `README.md`, `packet.json`, `context/source-map.md`, `implementation/tdd-plan.md`, `handoff/build-prompt.md`). Also defines `MARKDOWN_FILE_SUFFIX` and `EXIT_CODE_VALIDATION_FAILED`. |
-
-## Usage
-
-```python
-from anthropic_plan_scripts_constants.validate_packet_constants import ALL_REQUIRED_RELATIVE_PATHS
-```
+@AGENTS.md

package/skills/anthropic-plan/templates/AGENTS.md

@@ -0,0 +1,13 @@
+# templates
+
+Template files the `plan-packet.mjs` workflow renders when building a plan packet.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `README.md` | Markdown template for the packet's top-level `README.md`. Placeholder slots for plan title, goal, status, packet map, and build path. |
+| `build-prompt.md` | Template for `handoff/build-prompt.md` — the standalone prompt the build agent reads to start coding without needing the rest of the packet. |
+| `reuse-audit.md` | Template for `validation/reuse-audit.md` — the per-item verdict table the workflow fills in during the reuse audit step. |
+| `source-map.md` | Template for `context/source-map.md` — the inventory of source files and facts the planner extracts. |
+| `visual-plan.template.html` | Single-file offline HTML template. The workflow fills this with packet data after validation to produce `visual-plan.html` beside the packet. Inlines all CSS and JavaScript; references no external assets. |

package/skills/anthropic-plan/templates/CLAUDE.md

@@ -1,13 +1 @@
-# templates
-
-Template files the `plan-packet.mjs` workflow renders when building a plan packet.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `README.md` | Markdown template for the packet's top-level `README.md`. Placeholder slots for plan title, goal, status, packet map, and build path. |
-| `build-prompt.md` | Template for `handoff/build-prompt.md` — the standalone prompt the build agent reads to start coding without needing the rest of the packet. |
-| `reuse-audit.md` | Template for `validation/reuse-audit.md` — the per-item verdict table the workflow fills in during the reuse audit step. |
-| `source-map.md` | Template for `context/source-map.md` — the inventory of source files and facts the planner extracts. |
-| `visual-plan.template.html` | Single-file offline HTML template. The workflow fills this with packet data after validation to produce `visual-plan.html` beside the packet. Inlines all CSS and JavaScript; references no external assets. |
+@AGENTS.md

package/skills/anthropic-plan/workflow/AGENTS.md

@@ -0,0 +1,14 @@
+# workflow
+
+Workflow scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `plan-packet.mjs` | Main workflow script. Resolves repo root, reads project context, builds the source inventory, writes the full packet under `docs/plans/<slug>/`, runs `validate_packet.py`, spawns `plan-packet-validator` in a fresh context, runs the reuse audit, builds the visual HTML from `templates/visual-plan.template.html`, and returns the packet path and validation state. |
+| `plan-packet.contract.test.mjs` | Contract tests that verify the workflow script's interface and required steps without a live repo. |
+
+## Running
+
+The `plan-packet.mjs` script runs via the `Workflow` tool — do not invoke it directly with Node. The skill's `SKILL.md` specifies the exact call signature and required `args`.

package/skills/anthropic-plan/workflow/CLAUDE.md

@@ -1,14 +1 @@
-# workflow
-
-Workflow scripts for the `anthropic-plan` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `plan-packet.mjs` | Main workflow script. Resolves repo root, reads project context, builds the source inventory, writes the full packet under `docs/plans/<slug>/`, runs `validate_packet.py`, spawns `plan-packet-validator` in a fresh context, runs the reuse audit, builds the visual HTML from `templates/visual-plan.template.html`, and returns the packet path and validation state. |
-| `plan-packet.contract.test.mjs` | Contract tests that verify the workflow script's interface and required steps without a live repo. |
-
-## Running
-
-The `plan-packet.mjs` script runs via the `Workflow` tool — do not invoke it directly with Node. The skill's `SKILL.md` specifies the exact call signature and required `args`.
+@AGENTS.md

package/skills/auditing-claude-config/AGENTS.md

@@ -0,0 +1,21 @@
+# auditing-claude-config
+
+**Trigger:** `/auditing-claude-config`, reviewing the startup instruction load, `/memory` showing unexpected files, adding new rules, periodic config hygiene.
+
+Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.claude/` — for context-budget waste: duplicate `@`-imports, always-on rules that could be path-scoped or turned into skills, and oversized files. Produces a migration table with line savings.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
+| `reference/probe-hook.md` | The optional lazy-load probe hook: hook script, `settings.json` registration, and test protocol. |
+
+## What the skill produces
+
+1. **Baseline** — total always-loaded lines, broken down by file.
+2. **Migration table** — one row per rule: current lines, verdict, specific action, lines removed from preload.
+3. **Recommended next step** — the single highest-leverage change.
+4. **Open questions** — anything not verified by the probe hook.
+
+No runnable scripts or workflow files. The audit logic lives in the skill body; the optional lazy-load probe hook lives in `reference/probe-hook.md` as copy-ready text.

package/skills/auditing-claude-config/CLAUDE.md

@@ -1,21 +1 @@
-# auditing-claude-config
-
-**Trigger:** `/auditing-claude-config`, reviewing the startup instruction load, `/memory` showing unexpected files, adding new rules, periodic config hygiene.
-
-Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.claude/` — for context-budget waste: duplicate `@`-imports, always-on rules that could be path-scoped or turned into skills, and oversized files. Produces a migration table with line savings.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
-| `reference/probe-hook.md` | The optional lazy-load probe hook: hook script, `settings.json` registration, and test protocol. |
-
-## What the skill produces
-
-1. **Baseline** — total always-loaded lines, broken down by file.
-2. **Migration table** — one row per rule: current lines, verdict, specific action, lines removed from preload.
-3. **Recommended next step** — the single highest-leverage change.
-4. **Open questions** — anything not verified by the probe hook.
-
-No runnable scripts or workflow files. The audit logic lives in the skill body; the optional lazy-load probe hook lives in `reference/probe-hook.md` as copy-ready text.
+@AGENTS.md

package/skills/autoconverge/AGENTS.md

@@ -0,0 +1,36 @@
+# autoconverge
+
+**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
+
+Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
+| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
+| `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
+| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
+| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
+| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
+| `reference/convergence.md` | Round shape: the static sweep, the three parallel internal lenses, deduplication, fix commit, the terminal Bugbot, Copilot, and Codex gates, and the ready definition. |
+| `reference/copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
+| `reference/stop-conditions.md` | Every way the run ends short of ready, including the budget stop. |
+| `reference/gotchas.md` | Hard-won failure lessons. |
+| `reference/closing-report.md` | The closing HTML report: data source, build steps, publishing. |
+| `reference/multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
+| `reference/self-closing-loop.md` | The deferred-PR generations and the Conventional-Commit title rule. |
+| `reference/headless-safety.md` | The agent-prompt headless-safety preamble and the rm auto-allow paths. |
+
+## Entry point
+
+Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
+`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
+body specifies the pre-flight sequence and each pacer's run path.

package/skills/autoconverge/CLAUDE.md

@@ -1,36 +1 @@
-# autoconverge
-
-**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
-
-Drives one draft PR to convergence in one autonomous run. On `pacer=workflow`, each round runs a deterministic static sweep first, then a code-review pass, a bug-audit (with its adversarial second pass), and a self-review parity pass in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, and re-verifies; state lives in the workflow journal. On `pacer=portable`, the continuous driver in `_shared/pr-loop/portable-driver.md` runs the shared pr-converge phase machine with the same helpers and `check_convergence.py` ready definition. Once the internal passes are clean, Cursor Bugbot, Copilot, and Codex run as terminal confirmation gates, and the run marks the PR ready on convergence.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
-| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Full entry-point protocol: pacer selection, pre-flight steps, worktree setup, Workflow or portable path, budget-aware boundaries, teardown, and the convergence loop summary. |
-| `workflow/converge.mjs` | Main convergence workflow. Runs a static sweep then the internal lenses each round, applies fixes, runs Bugbot, Copilot, and Codex as terminal gates, checks convergence, and marks the PR ready. |
-| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
-| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
-| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
-| `reference/convergence.md` | Round shape: the static sweep, the three parallel internal lenses, deduplication, fix commit, the terminal Bugbot, Copilot, and Codex gates, and the ready definition. |
-| `reference/copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
-| `reference/stop-conditions.md` | Every way the run ends short of ready, including the budget stop. |
-| `reference/gotchas.md` | Hard-won failure lessons. |
-| `reference/closing-report.md` | The closing HTML report: data source, build steps, publishing. |
-| `reference/multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
-| `reference/self-closing-loop.md` | The deferred-PR generations and the Conventional-Commit title rule. |
-| `reference/headless-safety.md` | The agent-prompt headless-safety preamble and the rm auto-allow paths. |
-
-## Entry point
-
-Selects `workflow` or `portable` via `select_converge_pacer.py`. Missing
-`Workflow` selects portable and continues — it does not abort. The `SKILL.md`
-body specifies the pre-flight sequence and each pacer's run path.
+@AGENTS.md

package/skills/autoconverge/reference/AGENTS.md

@@ -0,0 +1,16 @@
+# reference
+
+Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
+| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
+| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
+| `gotchas.md` | Current operating guidance for PR title validation, conflicting PRs, worktree branch lock, resumed sessions, and commit or push failures. |
+| `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |
+| `multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
+| `self-closing-loop.md` | The deferred-PR generations the orchestrator converges after teardown, and the Conventional-Commit title rule on hardening PRs. |
+| `headless-safety.md` | The headless-safety preamble every agent prompt carries, and the rm auto-allow paths. |

package/skills/autoconverge/reference/CLAUDE.md

@@ -1,16 +1 @@
-# reference
-
-Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `convergence.md` | Round shape: the static sweep, the three parallel internal lenses (code-review, bug-audit, self-review), deduplication, the fix commit step, the terminal Bugbot, Copilot, and Codex gates, and the definition of a clean convergence. |
-| `copilot-findings.md` | The Copilot gate tiering, per-finding verification, and the `userReview` return contract. |
-| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, static-sweep stall, Bugbot, Copilot, and Codex bypass. |
-| `gotchas.md` | Current operating guidance for PR title validation, conflicting PRs, worktree branch lock, resumed sessions, and commit or push failures. |
-| `closing-report.md` | The closing HTML convergence report the teardown step builds and publishes: data source, build steps, publishing. |
-| `multi-pr.md` | The several-PRs path: per-PR worktrees, the `converge_multi.mjs` launch, per-PR teardown. |
-| `self-closing-loop.md` | The deferred-PR generations the orchestrator converges after teardown, and the Conventional-Commit title rule on hardening PRs. |
-| `headless-safety.md` | The headless-safety preamble every agent prompt carries, and the rm auto-allow paths. |
+@AGENTS.md

package/skills/autoconverge/workflow/AGENTS.md

@@ -0,0 +1,26 @@
+# workflow
+
+Workflow scripts and report utilities for the `autoconverge` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `converge.mjs` | Main convergence workflow script. Each round runs a deterministic static sweep first, then code-review, bug-audit, and self-review lenses in parallel, deduplicates findings, applies fixes, and pushes; Bugbot, Copilot, and Codex then run as terminal confirmation gates before it checks convergence and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
+| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
+| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
+| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
+| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
+| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
+| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
+| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
+| `converge.codex-gate.test.mjs` | Tests Codex gate classification (required+clean, skip-token, skip-usage, codex_down) and phase wiring. |
+| `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
+| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
+| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
+| `converge.p2-advance.test.mjs` | Tests P2-only fix-then-advance helpers and phase routing. |
+| `converge.run-input.test.mjs` | Tests workflow input validation. |
+| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
+| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
+| `test_render_report.py` | Tests for `render_report.py`. |
+| `fixtures/` | Test fixture data for the workflow tests. |

package/skills/autoconverge/workflow/CLAUDE.md

@@ -1,26 +1 @@
-# workflow
-
-Workflow scripts and report utilities for the `autoconverge` skill.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `converge.mjs` | Main convergence workflow script. Each round runs a deterministic static sweep first, then code-review, bug-audit, and self-review lenses in parallel, deduplicates findings, applies fixes, and pushes; Bugbot, Copilot, and Codex then run as terminal confirmation gates before it checks convergence and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
-| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
-| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
-| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
-| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
-| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
-| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
-| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
-| `converge.codex-gate.test.mjs` | Tests Codex gate classification (required+clean, skip-token, skip-usage, codex_down) and phase wiring. |
-| `converge.precatch.test.mjs` | Tests the pre-catch stage: static-sweep ordering and gate coverage, the adversarial second pass, the self-review lens, the terminal Bugbot gate, the read-only/edit preamble split, and the commit-recovery cap. |
-| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
-| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
-| `converge.p2-advance.test.mjs` | Tests P2-only fix-then-advance helpers and phase routing. |
-| `converge.run-input.test.mjs` | Tests workflow input validation. |
-| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
-| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
-| `test_render_report.py` | Tests for `render_report.py`. |
-| `fixtures/` | Test fixture data for the workflow tests. |
+@AGENTS.md

package/skills/autoconverge/workflow/autoconverge_report_constants/AGENTS.md

@@ -0,0 +1,16 @@
+# autoconverge_report_constants
+
+Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
+
+## Usage
+
+```python
+from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
+```

package/skills/autoconverge/workflow/autoconverge_report_constants/CLAUDE.md

@@ -1,16 +1 @@
-# autoconverge_report_constants
-
-Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `__init__.py` | Package marker. |
-| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
-
-## Usage
-
-```python
-from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
-```
+@AGENTS.md

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/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