claude-dev-env 2.28.1 → 2.29.0

package/.agents/agents/AGENTS.md

@@ -1,32 +1 @@
-# agents
 
-Agent definition files installed into `~/.agents/agents/` by `bin/install.mjs`. `~/.claude/agents` is a directory pointer to that folder. Each `.md` file defines a named subagent: its description (shown in the Claude Code UI), allowed tools, and behavioral instructions.
-
-Agent definitions use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form. Each agent keeps its role-specific return format.
-
-When the global presentation envelope applies, ELI5 owns beginner framing,
-large visuals, minimal text, one stable self-contained HTML artifact,
-update-in-place continuity, and sharing.
-
-## Agent files
-
-| File | Agent name | Role |
-|---|---|---|
-| `clean-coder.md` | Clean Coder | Primary code-writing agent; links the review contract, CODE_RULES, and enforcer; task-local discovery and gate-clean first writes |
-| `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
-| `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
-| `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
-| `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
-| `pr-description-writer.md` | PR Description Writer | Drafts PR descriptions and comments from the current diff using the canonical description and comment guides |
-| `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
-| `skill-writer-agent.md` | Skill Writer Agent | Authors SKILL.md and companion files to skill-builder conventions; caller-agnostic authoring specialist |
-
-## Format
-
-Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker. An agent definition carries no `model` key — the caller supplies the model on each spawn.
-
-## Adding an agent
-
-1. Create a new `.md` file in this directory with valid frontmatter.
-2. Run `bin/install.mjs` to copy it to `~/.agents/agents/`.
-3. Restart Claude Code to pick up the new agent.

package/.agents/agents/clean-coder.md

@@ -127,7 +127,7 @@ For a hook change, use the target package's active managed root for installed fi
 
 ## Session advisor
 
-Use the caller's existing warm `session-advisor`; do not bind or spawn another advisor. Consult it after orientation and before substantive work, before first write, before locking a plan or interpretation, before a hard-to-reverse action, after repeated failure or a stall when stuck, when changing approach (change of approach), before any commit, and after validation before completion when you believe the task is complete. Send exact scope and evidence. Follow its ENDORSE, CORRECTION, PLAN, or STOP signal before continuing.
+Consult the advisor the spawn ticket names. When the ticket names the orchestrating session, that session is the advisor. When the ticket names a warm `session-advisor`, use that agent; do not bind or spawn another advisor. Consult it after orientation and before substantive work, before first write, before locking a plan or interpretation, before a hard-to-reverse action, after repeated failure or a stall when stuck, when changing approach (change of approach), before any commit, and after validation before completion when you believe the task is complete. Send exact scope and evidence. Follow its ENDORSE, CORRECTION, PLAN, or STOP signal before continuing.
 
 ## Pre-write checklist
 

package/.agents/agents/test_agent_frontmatter.py

@@ -902,7 +902,9 @@ def test_clean_coder_uses_target_package_aware_hook_paths() -> None:
 
 def test_clean_coder_uses_the_callers_warm_advisor_at_approved_triggers() -> None:
     body = _clean_coder_body()
-    assert "caller's existing warm `session-advisor`" in body
+    assert "Consult the advisor the spawn ticket names" in body
+    assert "orchestrating session" in body
+    assert "warm `session-advisor`" in body
     assert "before first write" in body
     assert "before locking a plan or interpretation" in body
     assert "before a hard-to-reverse action" in body

package/.agents/skills/AGENTS.md

@@ -1,71 +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 bodies use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form. Each skill keeps its capability-specific output contract.
-
-## 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 `~/.agents/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. Claude Code looks them up at `~/.claude/skills/<skill-name>/`, a directory pointer to that folder. See `docs/references/skill-install-system.md` for the install pipeline.
-
-Retired skills live in `../skills-archived/` — versioned in the repo, not installed, not under the `.claude/skills` pointer. See `../skills-archived/AGENTS.md` for the archive index.
-
-## 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/CLAUDE.md`. End-of-run gotchas: `skills/_shared/end-of-run-gotcha-recommendations.md`.
-
-## Skill groups
-
-**Planning and implementation**
-- `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
-- `orchestrator-refresh` — re-asserts orchestrator discipline on a one-shot delayed wake
-- `team-advisor` — binds one advisor at the strongest reachable tier
-- `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers
-
-**PR review and convergence**
-
-- `pr-shared-extraction` — audits workflow packages for helpers that belong in shared libraries; extracts in small tested CLs
-- `pr-name-by-capability` — audits PR paths/titles for driver/motive words on reusable capability code
-- `review-tier` — classifies `review_tier_constants` from change axes, hard triggers, and user overrides
-- `review-router` — resolves and arms one supported `route_review_config` route through the registered Agent|Task gate
-- `pr-cleanup` — one-agent end-to-end PR cleanup: extraction → naming → sr-loop → pr-small-cl; apply and validate fixes as they return
-- `autoconverge` — autonomous single-run workflow that drives a PR to ready
-- `e-code-review` — max-recall code review at a selectable effort level
-- `e-simplify` — cleanup-only pass on the current diff
-- `pr-small-cl` — the Small CLs guide for scope and split decisions
-
-**Research and discovery**
-- `everything-search` — file-system search via the Everything `es.exe` CLI on Windows
-- `eli5` — owns beginner framing, large visuals, minimal text, one stable self-contained HTML artifact, update-in-place continuity, and sharing
-
-**Source commands**
-- `source-command-logifix` — restore the Logitech Gaming Software tray icon on Windows
-- `source-command-sr-loop` — converging cleanup loop: simplify then code-review until clean
-
-**Samsung certification**
-- `cert-classification-rule` — add or change a Samsung cert-failure classification rule
-
-**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` — GitHub epic and sub-issue workflow
-- `privacy-hygiene` — full-repo personal-data and secret sweep
-- `update` — fast-forwards a local `main` branch
-- `fresh-branch` — creates a clean branch off main in a worktree
-- `rebase` — rebases onto main with verification gates
-- `usage-pause` — waits out the usage window in ScheduleWakeup stages
-- `skill-builder` — complete skill-building lifecycle
-- `run-claude-dev-env` — build, install, and test the claude-dev-env installer
-- `prototype` — isolated hookless worktree sandbox for proof-of-concept builds

package/.agents/skills/_shared/AGENTS.md

@@ -1,45 +1 @@
-# skills/_shared
 
-**Map** for skill-install shared assets. Open a stub, then load the `@` target.
-
-## Two homes
-
-| Home | Path | Holds |
-|---|---|---|
-| **Skills shared** | `~/.agents/skills/_shared/` | Converge helpers, end-of-run gotcha ref, and `@` stubs. Claude Code looks this folder up at `~/.claude/skills/_shared/`. |
-| **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/CLAUDE.md` | `@../AGENTS.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/preflight-proposal.md` | `@~/.claude/_shared/pr-loop/preflight-proposal.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/.agents/skills/_shared/advisor/AGENTS.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/`).

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

@@ -1,58 +1 @@
-# pr-loop
 
-Shared infrastructure for autoconverge PR convergence: XML prompt templates,
-portable-driver phase machine scripts under `skills/_shared/pr-loop/scripts/`,
-and runtime convergence/Codex scripts under `~/.claude/_shared/pr-loop/scripts/`.
-Retired entry skills (`bugteam`, `pr-converge`, and others) are archived under
-`packages/claude-dev-env/.agents/skills-archived/` for reference only.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `prompts/` | XML agent prompt templates for internal lenses. |
-| `scripts/` | Portable pacer scripts: pacer selection, loop state, portable driver, prompt builders, handoff. |
-
-## 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` |
-| `preflight-proposal.md` | `@~/.claude/_shared/pr-loop/preflight-proposal.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` | Cross-file consistency audit prompt for autoconverge self-review lanes. |
-| `scripts/select_converge_pacer.py` | Maps entry skill + host tool flags to `workflow`, `schedule_wakeup`, or `portable`. |
-| `scripts/build_audit_prompt.py` | Assembles audit agent prompts from loop state (portable pacer). |
-| `scripts/build_fix_prompt.py` | Assembles fix agent prompts from loop state and findings. |
-| `scripts/init_loop_state.py` | Initializes per-PR loop state JSON for portable runs. |
-| `scripts/write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
-| `scripts/write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
-| `scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR. |
-| `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>/`. |
-| `scripts/portable_converge_driver.py` | Portable phase machine for autoconverge when `pacer=portable`. |
-| `scripts/build_converge_task_list.py` | Step-1 task list for portable runs. |
-| `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 for portable-driver scripts. |
-
-Runtime convergence checks, Codex review, and shared gates live in
-`packages/claude-dev-env/_shared/pr-loop/scripts/` (installed to
-`~/.claude/_shared/pr-loop/scripts/`).

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

@@ -1,9 +1 @@
-# prompts
 
-XML agent prompt templates for autoconverge internal lenses and portable pacer audits.
-
-## Key files
-
-| File | Role |
-|---|---|
-| `pr-consistency-audit.xml` | Structured prompt for the cross-file consistency audit. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. Autoconverge self-review and portable bug-audit lanes inject this prompt from `~/.claude/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml`. |

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

@@ -1,35 +1 @@
-# scripts
 
-Python scripts for autoconverge portable pacer control and loop helpers. Runtime convergence checks, Codex review, and shared gates live in `~/.claude/_shared/pr-loop/scripts/`.
-
-## 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/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/AGENTS.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
-```

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

package/.agents/skills/autoconverge/reference/AGENTS.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. |

package/.agents/skills/autoconverge/workflow/AGENTS.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. |

package/.agents/skills/autoconverge/workflow/autoconverge_report_constants/AGENTS.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
-```

package/.agents/skills/everything-search/AGENTS.md

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

package/.agents/skills/fresh-branch/AGENTS.md

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

package/.agents/skills/grok-spawn/AGENTS.md

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

package/.agents/skills/orchestrator/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/orchestrator/AGENTS.md

@@ -0,0 +1 @@
+