claude-dev-env 2.28.1 → 2.29.0

package/.agents/skills/skill-builder/references/AGENTS.md

@@ -1,25 +1 @@
-# skill-builder/references
 
-Best-practice specifications and the mandatory self-audit checklist for the `/skill-builder` skill.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `self-audit-checklist.md` | Audit task seeds after every build, improve, or polish. Register via TaskCreate / TodoWrite. |
-| `skill-types.md` | 9-type skill taxonomy with folder structures per type. |
-| `progressive-disclosure.md` | Hub pattern, folder conventions, hard rules: SKILL.md under 500 lines, one-level references. |
-| `skill-modularity.md` | Cross-skill modularity: one capability, sub-skills by name, composition plan, anti-monolith. |
-| `description-field.md` | Frontmatter description as trigger catalog (capability stem + Triggers). No story prose. |
-| `deterministic-elements.md` | Classify process steps; deterministic ones ship as code, task seeds, or fixed artifacts under CODE_RULES. |
-| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer-agent. |
-| `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
-
-## Conventions
-
-- These files load on demand from `SKILL.md` routing — not all on every run.
-- `self-audit-checklist.md` always loads at the end of a build cycle.
-- Load `skill-modularity.md` during Gather and when scope/overlap is diagnosed.
-- Load `description-field.md` during Gather, polish Step 1, and any activation diagnosis.
-- Load `deterministic-elements.md` during Gather, when prose-as-code is diagnosed, and on polish structure audit.
-- `thariq-x-post-skills.json` is source reference data, not executable content.

package/.agents/skills/skill-builder/templates/AGENTS.md

@@ -1,14 +1 @@
-# skill-builder/templates
 
-Reusable templates for skill-building artifacts.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `gap-analysis.md` | Template for gaps, composition plan, description triggers, and deterministic-elements inventory. Used in new-skill Gather and improve diagnosis. |
-
-## Conventions
-
-- Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
-- Composition plan, Description triggers, and Deterministic Elements Inventory sections are required before Write on a new skill.

package/.agents/skills/skill-builder/workflows/AGENTS.md

@@ -1,19 +1 @@
-# skill-builder/workflows
 
-Step-by-step workflow files for each skill lifecycle phase, loaded on demand by `SKILL.md` routing.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via the skill-writer-agent agent, self-audit, deliver. |
-| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
-| `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
-
-## Conventions
-
-- `SKILL.md` routes to exactly one workflow file per invocation based on the user's intent (new / improve / polish).
-- Each workflow references `../references/self-audit-checklist.md` at its final verification step.
-- New and improve load `skill-modularity.md`, `description-field.md`, and `deterministic-elements.md` when gathering or diagnosing.
-- Polish Step 1 is the dedicated description rewrite pass; Step 2 covers structure, modularity, and deterministic placement.
-- Load only the workflow that matches the active task; the other two stay out of context.

package/.agents/skills/task-build/AGENTS.md

@@ -1,29 +1 @@
-# task-build
 
-Gathers every open task in the current session and registers each one with the best available task or plan tool.
-
-**Trigger:** `/task-build`, "build my task list", "capture these tasks", "add open tasks to the task list", "track these".
-
-## Purpose
-
-Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or task items raised this session, then registers one item per open task — skipping anything already tracked or already complete.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Complete task discovery and registration workflow |
-| `reference/tool-routing.md` | Progressive-disclosure routing and fallback rules |
-
-## How the skill runs
-
-1. Reads the current list or visible plan with the selected host tool — prevents duplicates.
-2. Scans `$ARGUMENTS`, the conversation, and any plan or checklist items for open, actionable work.
-3. Prefers `update_plan`; otherwise uses `TaskList`/`TaskCreate`, then `TodoWrite` as the fallback. See `reference/tool-routing.md` for field mapping.
-4. Reports the selected tool, how many tasks were added, and how many were already tracked.
-
-## Conventions
-
-- This skill only records tasks — it does not start, assign, or complete them.
-- Use the matching host operation to set status after the list is built.
-- `disable-model-invocation: true` is not set; the skill uses model judgment to classify open vs. complete items.

package/.agents/skills/update/AGENTS.md

@@ -1,38 +1 @@
-# update
 
-Fast-forwards a local git repository's `main` branch to a chosen remote's `main`.
-
-**Trigger:** `/update`, "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", "bring main up to date".
-
-## Purpose
-
-Advances the `main` ref in a safe, confirmed, fast-forward-only way. Never forces, never merges. Confirms the repo path and source remote before any write. Offers to switch the checkout to `main` after the ref moves, with a clean-tree safety check.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — five phases, refusals, gotchas. Flat by design; no companion files. |
-
-## Five phases
-
-| Phase | Key action |
-|---|---|
-| 1 — Resolve path | `git -C "<path>" rev-parse --show-toplevel` |
-| 2 — Confirm path + remote | One `AskUserQuestion` listing remote/URL pairs; recommends `origin/main` first |
-| 3 — Fetch + fast-forward | Fetch, check ancestry with `merge-base --is-ancestor`, apply via `merge --ff-only` (on main) or `fetch main:main` (off main) |
-| 4 — Report | Old SHA → new SHA, checkout state, dirty tracked files |
-| 5 — Offer to land on disk | `AskUserQuestion` to switch checkout to `main` (only when tree is clean and `main` is not held by another worktree) |
-
-## Refusals (first match wins)
-
-- Path is not a git repository → stated error, stop.
-- Remote has no `main` → stated error, stop.
-- Local `main` has diverged (not a fast-forward) → stated error, stop. Use `/rebase` to reconcile.
-
-## Conventions
-
-- Every command uses `git -C "<path>"` — never `cd` into the repo.
-- Path confirmation is mandatory even when the path comes from the argument.
-- The skill never switches to any branch other than `main`, and only in Phase 5 with operator approval.
-- `origin` is not always the source of truth; the confirmed remote may be `upstream` or another name.

package/.agents/skills-archived/AGENTS.md

@@ -1,45 +1 @@
-# skills-archived
 
-Versioned archive of retired Claude Code skills. These trees stay in the repository for reference and history but are not shipped to users.
-
-## Layout
-
-Each subdirectory is one retired skill with its historical `SKILL.md`, reference docs, scripts, and tests. Live runtime helpers for convergence and Codex review live under `packages/claude-dev-env/_shared/pr-loop/scripts/` — not in these trees.
-
-## Installer behavior
-
-`bin/install.mjs` copies skills only from `.agents/skills/`. This directory is outside that path and outside the `.claude/skills` lookup pointer, so archived skills never install to `~/.agents/skills/`.
-
-`bin/ever-shipped-skills.mjs` still lists retired skill names so a full install prunes stale copies from prior releases.
-
-## Archived skills
-
-| Skill | Role |
-|---|---|
-| `anthropic-plan` | Source-grounded plan packet workflow |
-| `auditing-claude-config` | Claude Code startup instruction audit |
-| `beat-sheet` | Single-line beat formatting |
-| `bugteam` | Open PR audit-fix loop |
-| `closeout` | Session obstacle harvest to GitHub issues |
-| `codex-review` | Local Codex PR reviewer (runtime scripts in `_shared`) |
-| `comments` | PR review comment guide |
-| `condensing-instructions` | Instruction slimming for Claude 5 |
-| `copilot-finding-triage` | Copilot gate finding tiering |
-| `copilot-review` | Copilot reviewer babysitter |
-| `descriptions` | PR description guide |
-| `emergencies` | Emergency change guide |
-| `grokify` | Grok Build handoff prompt |
-| `plan-to-pr` | Plan packet to PR workflow |
-| `pr-converge` | Paced PR convergence loop (runtime scripts in `_shared`) |
-| `pr-fix-protocol` | Reviewer finding fix protocol |
-| `pr-loop-cloud-transport` | Cloud session gh-to-MCP transport |
-| `pr-loop-lifecycle` | PR-loop open and close |
-| `recall` | Obsidian vault recall |
-| `release-notes-html` | Session release-notes HTML page |
-| `remember` | Obsidian vault remember |
-| `reviewer-gates` | External reviewer availability gates |
-| `reviews` | Code review guide |
-| `show` | Inline visual explanations |
-| `split-pr` | PR split analyzer |
-
-Prompt-generator dependency skills (`agent-prompt`, `pmin`, `pmax`, `pmid`, `prompt-generator`) shipped via the `@jl-cmd/prompt-generator` npm package and never had source trees in this repository.

package/.agents/skills-archived/anthropic-plan/AGENTS.md

@@ -1,34 +1 @@
-# 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/.agents/skills-archived/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/.agents/skills-archived/anthropic-plan/scripts/AGENTS.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. |

package/.agents/skills-archived/anthropic-plan/scripts/anthropic_plan_scripts_constants/AGENTS.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
-```

package/.agents/skills-archived/anthropic-plan/templates/AGENTS.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. |

package/.agents/skills-archived/anthropic-plan/workflow/AGENTS.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`.

package/.agents/skills-archived/auditing-claude-config/AGENTS.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.

package/.agents/skills-archived/bugteam/AGENTS.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.

package/.agents/skills-archived/bugteam/reference/AGENTS.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). |

package/.agents/skills-archived/bugteam/reference/obstacles/AGENTS.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. |

package/.agents/skills-archived/bugteam/scripts/AGENTS.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. |

package/.agents/skills-archived/bugteam/scripts/bugteam_scripts_constants/AGENTS.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.

package/.agents/skills-archived/codex-review/AGENTS.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.

package/.agents/skills-archived/codex-review/reference/AGENTS.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.

package/.agents/skills-archived/codex-review/scripts/codex_review_scripts_constants/AGENTS.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.

package/.agents/skills-archived/codex-review/test_skill_scaffold.py

@@ -9,9 +9,15 @@ from pathlib import Path
 
 SKILL_DIRECTORY = Path(__file__).resolve().parent
 SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
-PACKAGE_MAP_PATH = SKILL_DIRECTORY / "AGENTS.md"
-REFERENCE_DIRECTORY = SKILL_DIRECTORY / "reference"
 PACKAGE_ROOT = SKILL_DIRECTORY.parents[2]
+REPOSITORY_ROOT = PACKAGE_ROOT.parents[1]
+AGENTS_MD_ARCHIVE_ROOT = REPOSITORY_ROOT / "docs" / "records" / "agents-md"
+PACKAGE_MAP_PATH = (
+    AGENTS_MD_ARCHIVE_ROOT
+    / SKILL_DIRECTORY.relative_to(REPOSITORY_ROOT)
+    / "AGENTS.md.archive"
+)
+REFERENCE_DIRECTORY = SKILL_DIRECTORY / "reference"
 PYPROJECT_PATH = PACKAGE_ROOT / "pyproject.toml"
 EVER_SHIPPED_SKILLS_PATH = PACKAGE_ROOT / "bin" / "ever-shipped-skills.mjs"
 CONSTANTS_PACKAGE_NAME = "codex_review_scripts_constants"
@@ -131,7 +137,11 @@ 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" / "AGENTS.md"
+        AGENTS_MD_ARCHIVE_ROOT
+        / SKILL_DIRECTORY.relative_to(REPOSITORY_ROOT)
+        / "scripts"
+        / "codex_review_scripts_constants"
+        / "AGENTS.md.archive"
     ).read_text(encoding="utf-8")
     wrapper_path = SKILL_DIRECTORY / "scripts" / "run_codex_review.py"
 

package/.agents/skills-archived/copilot-review/AGENTS.md

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

package/.agents/skills-archived/pr-converge/AGENTS.md

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

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

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