claude-dev-env 2.13.0 → 2.14.1

package/skills/CLAUDE.md

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

package/skills/_shared/AGENTS.md

@@ -0,0 +1,44 @@
+# skills/_shared
+
+**Map** for skill-install shared assets. Open a stub, then load the `@` target.
+
+## Two homes
+
+| Home | Path | Holds |
+|---|---|---|
+| **Skills shared** | `~/.claude/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs |
+| **Top-level shared** | `~/.claude/_shared/` | Advisor protocol, PR-loop contracts, runtime scripts |
+
+
+## Reference docs (this tree)
+
+| File | Role |
+|---|---|
+| **`end-of-run-gotcha-recommendations.md`** | End-of-run pasteable gotcha protocol for every skill |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| **`advisor/`** | Stubs → `@~/.claude/_shared/advisor/` |
+| **`pr-loop/`** | Local converge helpers + stubs → `@~/.claude/_shared/pr-loop/` |
+
+## Canonical-path stubs
+
+| Stub here | Load |
+|---|---|
+| `advisor/advisor-protocol.md` | `@~/.claude/_shared/advisor/advisor-protocol.md` |
+| `advisor/CLAUDE.md` | `@~/.claude/_shared/advisor/CLAUDE.md` |
+| `advisor/scripts/README.md` | `@~/.claude/_shared/advisor/scripts/` |
+| `pr-loop/audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `pr-loop/audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `pr-loop/code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `pr-loop/fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+Install via `packages/claude-dev-env/bin/install.mjs`.

package/skills/_shared/CLAUDE.md

@@ -1,44 +1 @@
-# skills/_shared
-
-**Map** for skill-install shared assets. Open a stub, then load the `@` target.
-
-## Two homes
-
-| Home | Path | Holds |
-|---|---|---|
-| **Skills shared** | `~/.claude/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs |
-| **Top-level shared** | `~/.claude/_shared/` | Advisor protocol, PR-loop contracts, runtime scripts |
-
-
-## Reference docs (this tree)
-
-| File | Role |
-|---|---|
-| **`end-of-run-gotcha-recommendations.md`** | End-of-run pasteable gotcha protocol for every skill |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| **`advisor/`** | Stubs → `@~/.claude/_shared/advisor/` |
-| **`pr-loop/`** | Local converge helpers + stubs → `@~/.claude/_shared/pr-loop/` |
-
-## Canonical-path stubs
-
-| Stub here | Load |
-|---|---|
-| `advisor/advisor-protocol.md` | `@~/.claude/_shared/advisor/advisor-protocol.md` |
-| `advisor/CLAUDE.md` | `@~/.claude/_shared/advisor/CLAUDE.md` |
-| `advisor/scripts/README.md` | `@~/.claude/_shared/advisor/scripts/` |
-| `pr-loop/audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
-| `pr-loop/audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
-| `pr-loop/code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
-| `pr-loop/fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
-| `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
-| `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
-| `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
-| `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
-| `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
-| `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
-
-Install via `packages/claude-dev-env/bin/install.mjs`.
+@AGENTS.md

package/skills/_shared/advisor/AGENTS.md

@@ -0,0 +1,9 @@
+# Advisor
+
+**Canonical home:**
+
+@~/.claude/_shared/advisor/CLAUDE.md
+
+@~/.claude/_shared/advisor/advisor-protocol.md
+
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/CLAUDE.md

@@ -1,9 +1 @@
-# Advisor
-
-**Canonical home:**
-
-@~/.claude/_shared/advisor/CLAUDE.md
-
-@~/.claude/_shared/advisor/advisor-protocol.md
-
-Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).
+@AGENTS.md

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

@@ -0,0 +1,50 @@
+# pr-loop
+
+Shared infrastructure for the PR audit-fix loop used by `bugteam`,
+`pr-converge`, and `autoconverge`. Provides the XML prompt template, Python
+runtime scripts, the portable converge driver protocol, and named constants
+those skills invoke during each loop tick.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `prompts/` | XML agent prompt templates. |
+| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
+
+## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
+
+Open a stub, then load the `@` target:
+
+| Stub here | Load |
+|---|---|
+| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (live in this tree)
+
+| File | Role |
+|---|---|
+| `portable-driver.md` | Continuous in-session pacer when Workflow / ScheduleWakeup are absent. |
+| `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
+| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
+| `scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
+| `scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
+| `scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
+| `scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
+| `scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
+| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
+| `scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
+| `scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
+| `scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
+| `scripts/_xml_utils.py` | XML serialization helpers. |
+| `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |

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

@@ -1,50 +1 @@
-# pr-loop
-
-Shared infrastructure for the PR audit-fix loop used by `bugteam`,
-`pr-converge`, and `autoconverge`. Provides the XML prompt template, Python
-runtime scripts, the portable converge driver protocol, and named constants
-those skills invoke during each loop tick.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `prompts/` | XML agent prompt templates. |
-| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
-
-## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
-
-Open a stub, then load the `@` target:
-
-| Stub here | Load |
-|---|---|
-| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
-| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
-| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
-| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
-| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
-| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
-| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
-| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
-| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
-| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
-
-## Key files (live in this tree)
-
-| File | Role |
-|---|---|
-| `portable-driver.md` | Continuous in-session pacer when Workflow / ScheduleWakeup are absent. |
-| `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
-| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
-| `scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
-| `scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
-| `scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
-| `scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
-| `scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
-| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
-| `scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
-| `scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
-| `scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
-| `scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
-| `scripts/_xml_utils.py` | XML serialization helpers. |
-| `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
+@AGENTS.md

package/skills/_shared/pr-loop/prompts/AGENTS.md

@@ -0,0 +1,9 @@
+# prompts
+
+XML agent prompt templates for the PR audit-fix loop.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. `bugteam` and `pr-converge` both inject this prompt when running the consistency audit step. |

package/skills/_shared/pr-loop/prompts/CLAUDE.md

@@ -1,9 +1 @@
-# prompts
-
-XML agent prompt templates for the PR audit-fix loop.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. `bugteam` and `pr-converge` both inject this prompt when running the consistency audit step. |
+@AGENTS.md

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

@@ -0,0 +1,35 @@
+# scripts
+
+Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
+
+## Two script homes
+
+| Home | Path |
+|---|---|
+| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
+| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (skill-local)
+
+| File | Role |
+|---|---|
+| `audit_category_schema.py` | Loads the A-Q schema JSON, exports category entries, validates rubric/prompt projections, renders deterministic skeletons. |
+| `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
+| `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
+| `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |
+| `write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
+| `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
+| `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
+| `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
+| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
+| `select_converge_pacer.py` | Selects `workflow`, `schedule_wakeup`, or `portable` for pr-converge / autoconverge from host tool flags. |
+| `build_converge_task_list.py` | Step-1 task list: runnable review gates + final all_runnable_reviews_clean_same_head. |
+| `portable_converge_driver.py` | portable_converge_driver phase machine: open-run and post-step transitions emit JSON next/commands only. |
+| `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
+| `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
+| `_xml_utils.py` | XML serialization helpers for outcome files. |
+| `skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
+
+## Tests
+
+Each script has a paired test file (`test_build_audit_prompt.py`, `test_build_fix_prompt.py`, etc.) in this directory. Run with `python -m pytest` from the repo root.

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

@@ -1,35 +1 @@
-# scripts
-
-Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
-
-## Two script homes
-
-| Home | Path |
-|---|---|
-| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
-| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
-
-## Key files (skill-local)
-
-| File | Role |
-|---|---|
-| `audit_category_schema.py` | Loads the A-Q schema JSON, exports category entries, validates rubric/prompt projections, renders deterministic skeletons. |
-| `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
-| `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
-| `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |
-| `write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
-| `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
-| `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
-| `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
-| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
-| `select_converge_pacer.py` | Selects `workflow`, `schedule_wakeup`, or `portable` for pr-converge / autoconverge from host tool flags. |
-| `build_converge_task_list.py` | Step-1 task list: runnable review gates + final all_runnable_reviews_clean_same_head. |
-| `portable_converge_driver.py` | portable_converge_driver phase machine: open-run and post-step transitions emit JSON next/commands only. |
-| `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
-| `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
-| `_xml_utils.py` | XML serialization helpers for outcome files. |
-| `skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
-
-## Tests
-
-Each script has a paired test file (`test_build_audit_prompt.py`, `test_build_fix_prompt.py`, etc.) in this directory. Run with `python -m pytest` from the repo root.
+@AGENTS.md

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

@@ -1,6 +1,6 @@
 ---
 name: anthropic-plan
-description: Workflow-backed implementation planning that creates a deep repo-local packet under docs/plans/<slug>/ before any code changes. Use for /anthropic-plan, /plan, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial implementation requests that need source-grounded design, TDD steps, and validator approval before build work.
+description: Workflow-backed implementation planning that creates a deep repo-local packet under docs/plans/<slug>/ before any code changes. Use for /anthropic-plan, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial implementation requests that need source-grounded design, TDD steps, and validator approval before build work.
 ---
 
 # Anthropic Plan

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