claude-dev-env 1.68.0 → 1.69.1

package/skills/doc-gist/references/examples/CLAUDE.md

@@ -0,0 +1,25 @@
+# doc-gist/references/examples
+
+HTML artifact gallery for the `doc-gist` skill. Has 21 self-contained `.html` files that cover distinct artifact shapes the skill can produce.
+
+Files `01`–`20` are Thariq Shihipar's html-effectiveness prototypes (used with permission). File `21-decision-signoff.html` is an original addition in the same style.
+
+## Use
+
+Study the matching file when designing a fresh artifact for a request. Crib palette, typography, spatial layout, and component patterns — then adapt to the specific request. The gallery teaches what shapes work; each new artifact is its own design.
+
+See `SKILL.md` for the full gallery-to-artifact-type mapping table (PR writeup, code review, implementation plan, slide deck, etc.).
+
+## Files (sample)
+
+| File | Shape |
+|---|---|
+| `01-exploration-code-approaches.html` | Side-by-side approach exploration |
+| `03-code-review-pr.html` | Annotated diff / code review |
+| `09-slide-deck.html` | Keyboard-navigable slide deck |
+| `12-incident-report.html` | Incident timeline / post-mortem |
+| `16-implementation-plan.html` | Implementation plan with timeline and risks |
+| `17-pr-writeup.html` | PR writeup with file-by-file tour |
+| `21-decision-signoff.html` | Decision / sign-off doc with accept-or-change per call |
+
+All 21 files are present; the table above is a representative sample.

package/skills/doc-gist/scripts/CLAUDE.md

@@ -0,0 +1,27 @@
+# doc-gist/scripts
+
+Transport script and supporting constants for the `doc-gist` skill.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `gist_upload.py` | Core transport: reads HTML from a file path or stdin, runs `gh gist create`, prints `Gist:` and `Preview:` URLs to stderr, prints the preview URL to stdout, and opens it in the default browser (unless `--no-open`). |
+| `test_gist_upload.py` | Tests for `gist_upload.py`. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `doc_gist_scripts_constants/` | Named constants imported by `gist_upload.py` (URL prefixes, default filename, timeout). |
+
+## CLI usage
+
+```
+python gist_upload.py --input <path-or-stdin>
+                      [--filename gist-file.html]
+                      [--description "short label"]
+                      [--no-open]
+```
+
+Pass `--input -` to read from stdin. The auto-publish hook calls this script with the written file's path; the skill body documents when to call it manually.

package/skills/doc-gist/scripts/doc_gist_scripts_constants/CLAUDE.md

@@ -0,0 +1,10 @@
+# doc-gist/scripts/doc_gist_scripts_constants
+
+Named constants for `gist_upload.py`. Importing from this package keeps all URL templates, default filenames, and timeout values out of the script body.
+
+## Modules
+
+| File | Constants |
+|---|---|
+| `gist_upload_constants.py` | `GIST_HOST_PREFIX` — base URL for parsing gist output; `PREVIEW_URL_TEMPLATE` — htmlpreview.github.io URL shape; `GIST_DEFAULT_FILENAME` — filename when input is stdin; `MINIMUM_GIST_URL_PARTS` — fewest path segments in a valid gist URL; `UPLOAD_TIMEOUT_SECONDS` — subprocess timeout for `gh gist create`. |
+| `__init__.py` | Empty package marker. |

package/skills/everything-search/CLAUDE.md

@@ -0,0 +1,17 @@
+# 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/skills/findbugs/CLAUDE.md

@@ -0,0 +1,20 @@
+# findbugs
+
+Audits the current branch's pull request for bugs by spawning the `code-quality-agent` against the full PR diff in a clean room. Triggered by `/findbugs`, `find bugs in this PR`, `audit the PR`, or `bug audit on the branch`.
+
+## Purpose
+
+Read-only. The skill resolves PR scope, writes the diff to a scoped temp file, and spawns two `code-quality-agent` instances (primary sonnet + secondary haiku) with a self-contained, context-free prompt covering all A–P audit categories. After both return it merges findings (de-dup, max-wins severity), posts one audit review to the PR via `post_audit_thread.py` (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty), and reports totals and cleared categories to the user.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Five-step process: resolve scope, capture diff to a scoped temp path, spawn agents (clean-room prompt XML), post audit review via `post_audit_thread.py`, surface findings and offer `/fixbugs`. Includes refusals, output format, and the anchored-vs-unanchored finding split. |
+
+## Constraints
+
+- Never edits files, never commits, never pushes.
+- One audit review per invocation is posted back to the PR — required so the unresolved-thread gate sees the audit pass.
+- Disabled by `CLAUDE_REVIEWS_DISABLED=bugteam` (shared token across the audit-skill family).
+- Always ask before running `/fixbugs`; never auto-spawn the fixer.

package/skills/fixbugs/CLAUDE.md

@@ -0,0 +1,19 @@
+# fixbugs
+
+Bridges `/findbugs` audit results to `/agent-prompt` for automated fixing. Triggered by `/fixbugs`, `fix all the bugs`, `apply the audit fixes`, or `implement the findbugs results`.
+
+## Purpose
+
+A thin bridge: recover the prior `/findbugs` findings from the current conversation, apply an optional severity filter (`P0`, `P0+P1`, `P1`, or all), re-resolve PR scope, then hand the filtered finding list to `/agent-prompt` as a structured goal string. `/agent-prompt` authors the XML prompt, shows an Outcome preview, asks for confirmation, and spawns a background sonnet `clean-coder` agent to apply all fixes in one commit.
+
+This skill never audits, never edits files, and never spawns agents directly. The `/agent-prompt` confirmation gate is always preserved.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-step process: recover findings, apply severity filter, re-resolve PR scope, hand off to `/agent-prompt` with a goal string in the exact expected shape. Includes refusal cases (no findings, zero bugs, empty filter, missing `agent-prompt` skill) and the implementer constraints (one commit, no `--force`, no rebase, explicit `git add` by path). |
+
+## Invocation order
+
+Run `/findbugs` first, then `/fixbugs`. Running `/fixbugs` with no prior `/findbugs` in the session returns `No findings in this session. Run /findbugs first.`

package/skills/fresh-branch/CLAUDE.md

@@ -0,0 +1,15 @@
+# fresh-branch
+
+Creates a new branch from `origin/main` (always fresh-fetched). Triggered by `fresh branch`, `new branch from main`, `/fresh-branch`, or `start fresh`.
+
+## Purpose
+
+A shared primitive used by other skills and directly by the user. Fetches `origin/main`, suggests 2–4 branch names via `AskUserQuestion` when a topic is available (polling recent branch naming patterns from `git branch -r`), then creates and checks out the branch with `git checkout -b <name> origin/main`.
+
+Does not push the branch. Does not create a PR. Does not switch an existing branch. Callers that need the new branch name (for example, to open a PR) receive it as a return value.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-phase instructions: fetch `origin/main`, pick branch name (suggest or prompt), create branch, report. Includes gotchas discovered during use. |

package/skills/gh-paginate/CLAUDE.md

@@ -0,0 +1,18 @@
+# gh-paginate skill
+
+Provides the safe-pagination rule and patterns for `gh api` calls against paginated GitHub list endpoints (PR reviews, PR comments, issue comments, pulls, issues). The rule prevents two silent-truncation defects: default page truncation and per-page `--jq` evaluation.
+
+**Trigger:** Loaded by the `gh-paginate` skill name or when any skill or rule references the pagination rule.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete rule: affected endpoints, safe `--paginate --slurp \| jq` pattern, single-page bound pattern, single-object pattern, newest-first walk pattern, and enforcement notes |
+
+## Conventions
+
+- The preferred pattern pipes `--paginate --slurp` to an **external** `jq` invocation so cross-page operations (`sort_by`, `last`, `reverse`) run on the merged array-of-pages. The built-in `--jq` flag is incompatible with `--slurp` and runs per-page, producing wrong cross-page results.
+- Single-object endpoints (e.g., `pulls/<number>`) are not paginated; `--paginate` is unnecessary and `gh --jq` is safe.
+- The single-page bound pattern (`?per_page=100` without `--paginate`) is acceptable only when the list is confirmed to stay under 100 entries.
+- This skill ships as documentation only; enforcement via a future PreToolUse hook is noted in `SKILL.md`.

package/skills/gotcha/CLAUDE.md

@@ -0,0 +1,33 @@
+# gotcha skill
+
+Captures an obstacle encountered during a skill run and records it as a gotcha entry in the relevant skill file, then opens a draft PR via the `fresh-branch` skill.
+
+**Trigger:** `/gotcha`, "add a gotcha", "document this gotcha", "record this obstacle".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full workflow: collect obstacle details, delegate to `bg-agent`, confirm to user |
+
+## Workflow
+
+1. Distill the obstacle into: which skill file was affected, what happened, what the user did to resolve it, and what to do differently next time.
+2. Invoke `/bg-agent` with a self-contained prompt that instructs the agent to use `/fresh-branch` (branch name `gotcha/<short-slug>`), append to or create a `## Gotchas` section at the bottom of the skill file, commit, push, and open a draft PR.
+3. Confirm to the user that the recording is running in the background.
+
+## Gotcha entry format
+
+Each entry is a bullet under `## Gotchas`:
+
+```markdown
+- **<title>:** <what happens>. <what to do instead>.
+```
+
+## Repo routing
+
+| Skill location | Target repo |
+|---|---|
+| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-code-config` |
+| `~/.claude/skills/<name>/` | `jl-cmd/claude-code-config` |
+| Project `.claude/skills/<name>/` | That project's repo |

package/skills/implement/CLAUDE.md

@@ -0,0 +1,27 @@
+# Spec Execution Skill
+
+This skill (`implement`) runs a spec end-to-end while maintaining a sidecar `implementation-notes.html` that records design decisions, deviations, tradeoffs, and open questions made during the build.
+
+**Trigger:** `/implement [path-to-spec]`, "build out this plan and keep notes".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full workflow: resolve spec, run it, write notes via `append_note.py` |
+| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI that creates or appends to `implementation-notes.html` |
+| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | Python CLI and constants for the notes file |
+
+## Conventions
+
+- The spec is taken from `$ARGUMENTS` (path) or the most recent plan in conversation context. If neither is present, the skill asks via `AskUserQuestion`.
+- Notes are appended as decisions are made — not batched at the end.
+- The `append_note.py` CLI accepts `--section decisions|deviations|tradeoffs|questions`, `--about`, `--note`, and optionally `--file`. When `--file` is omitted, the script writes to `./implementation-notes.html`.
+- `$CLAUDE_SKILL_DIR` is substituted by Claude Code at runtime so the bundled script is found regardless of the current working directory.
+- The notes file structure must not be hand-edited — `append_note.py` locates sections by `<section id="...">` markers and the first `</ul>` after each.

package/skills/implement/scripts/CLAUDE.md

@@ -0,0 +1,22 @@
+# scripts (spec-build skill)
+
+Support scripts for the spec-build (`implement`) skill. These scripts create and append to the `implementation-notes.html` sidecar file the skill maintains during a spec build.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `append_note.py` | CLI that creates `implementation-notes.html` with four sections on first run and appends a `<li>` to a named section on later runs |
+| `test_append_note.py` | Tests for `append_note.py` |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `implement_scripts_constants/` | Section slug → heading map and default filename constant |
+
+## Conventions
+
+- `append_note.py` imports section metadata from `implement_scripts_constants.notes_constants`.
+- HTML-escaping of `--about` and `--note` is handled by the script; callers pass raw text.
+- The script is invoked as `python "${CLAUDE_SKILL_DIR}/scripts/append_note.py"` from within the skill, where `$CLAUDE_SKILL_DIR` resolves to the installed skill directory at runtime.

package/skills/implement/scripts/implement_scripts_constants/CLAUDE.md

@@ -0,0 +1,22 @@
+# implement_scripts_constants
+
+Constants module for the `implement` skill's `append_note.py` script.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `notes_constants.py` | `HEADING_BY_SLUG` dict (section slugs → display headings) and `DEFAULT_NOTES_FILENAME` |
+
+## Exported constants
+
+| Constant | Value | Used by |
+|---|---|---|
+| `HEADING_BY_SLUG` | `{"decisions": "Design decisions", "deviations": "Deviations", "tradeoffs": "Tradeoffs", "questions": "Open questions"}` | `append_note.py` — maps `--section` slug to the `<h2>` heading in the HTML file |
+| `DEFAULT_NOTES_FILENAME` | `"implementation-notes.html"` | `append_note.py` — default output path when `--file` is omitted |
+
+## Conventions
+
+- This module is imported directly by `append_note.py` in the parent `scripts/` directory.
+- Adding a new section requires a new entry in `HEADING_BY_SLUG` and a matching branch in `append_note.py`.

package/skills/logifix/CLAUDE.md

@@ -0,0 +1,36 @@
+# logifix skill
+
+Restores the Logitech Gaming Software (LCore) tray icon when it disappears on Windows. Runs a PowerShell script that reproduces the verified recovery procedure.
+
+**Trigger:** `/logifix`, "logitech tray icon missing", "LCore tray gone", "logitech is not loaded".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full procedure description, invocation options, fallback steps |
+| `scripts/logifix.ps1` | PowerShell script that runs the recovery procedure |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | The PowerShell recovery script |
+
+## What the script does
+
+1. Takes a state snapshot (Explorer instances, Logitech services, LCore process).
+2. Stops LCore in user context.
+3. Runs one elevated UAC step: starts `LogiRegistryService`, stops `explorer.exe`, and lets Windows shell auto-respawn rebuild it (does **not** call `Start-Process explorer` from the elevated block).
+4. Waits for shell auto-respawn (default 5 seconds).
+5. Confirms exactly one Explorer in the user's session.
+6. Runs `LCoreRelaunchAttemptCount` full stop-then-launch cycles of `LCore.exe /minimized` (default 2). Always runs the full count.
+7. Takes a final state snapshot.
+
+## Invocation
+
+```
+/logifix
+```
+
+Optional parameters: `-ExplorerAutoRespawnWaitSeconds`, `-LCoreInitializationWaitSeconds`, `-LCoreRelaunchAttemptCount`.

package/skills/logifix/scripts/CLAUDE.md

@@ -0,0 +1,16 @@
+# logifix/scripts
+
+PowerShell recovery script for the `logifix` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `logifix.ps1` | Restores the LCore tray icon: stops LCore, runs one elevated UAC step (starts `LogiRegistryService`, stops explorer, lets Windows auto-respawn), then re-launches LCore a configurable number of times |
+
+## Conventions
+
+- The script accepts three optional parameters: `-ExplorerAutoRespawnWaitSeconds` (default 5), `-LCoreInitializationWaitSeconds` (default 5), `-LCoreRelaunchAttemptCount` (default 2).
+- The full relaunch count always runs — an early-exit on a responsive LCore is intentional behavior per the recovery procedure.
+- The elevated block does **not** call `Start-Process explorer`; Windows shell auto-respawn handles that to avoid a duplicate admin-context Explorer.
+- Run directly as: `pwsh -File "$HOME\.claude\skills\logifix\scripts\logifix.ps1"`.

package/skills/monitor-open-prs/CLAUDE.md

@@ -0,0 +1,34 @@
+# monitor-open-prs skill
+
+Discovers every open pull request across the `jl-cmd/*` and `JonEcho/*` owner scopes, dispatches `/bugteam` on each with the `--bugbot-retrigger` flag, and polls for new Cursor bugbot replies after each bugteam run.
+
+**Trigger:** `/monitor-open-prs`, "sweep the open PRs", "audit the open PR backlog".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full workflow: refusal cases, discovery, dispatch, post-convergence polling, final report |
+| `test_skill_contract.py` | Contract tests for the skill |
+| `packages/claude-dev-env/skills/monitor-open-prs/scripts/discover_open_prs.py` | Shells out to `gh search prs` per owner scope and flattens results to a uniform dict shape |
+| `packages/claude-dev-env/skills/monitor-open-prs/scripts/test_discover_open_prs.py` | Tests for the discovery helper |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | Discovery helper and its tests |
+
+## Workflow summary
+
+1. Call `discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to get the full open-PR list.
+2. For each PR, invoke `/bugteam --bugbot-retrigger <pr_number>` (omit `--bugbot-retrigger` if `CLAUDE_REVIEWS_DISABLED` has `bugbot`).
+3. After each bugteam run, poll for new bugbot comments on a 60s → 120s → 240s → 480s → 960s backoff. Re-invoke bugteam if new findings appear.
+4. Emit a sweep summary when all PRs exit polling.
+
+## Refusals (checked first)
+
+- `CLAUDE_REVIEWS_DISABLED` has `bugteam` → stop with a message.
+- GitHub API not accessible → stop.
+- Uncommitted changes in the caller's repo → stop.
+- Required subagent types missing (`code-quality-agent`, `clean-coder`) → stop.

package/skills/monitor-open-prs/scripts/CLAUDE.md

@@ -0,0 +1,17 @@
+# monitor-open-prs/scripts
+
+Discovery helper for the `monitor-open-prs` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `discover_open_prs.py` | Queries `gh search prs` for each owner scope and flattens results to a uniform list of dicts |
+| `test_discover_open_prs.py` | Tests for the discovery helper |
+
+## Conventions
+
+- `discover_open_prs(all_owners: list[str]) -> list[dict]` is the single entry point. It shells out to `gh search prs --owner <owner> --state open --json number,repository,url,headRefName,baseRefName` once per owner and merges the results.
+- Each returned dict has keys: `number`, `owner`, `repo`, `head_ref`, `base_ref`, `url`.
+- An empty scope or an empty sweep returns an empty list and exits cleanly with no errors.
+- The module is stateless and has no filesystem side effects.

package/skills/pr-consistency-audit/CLAUDE.md

@@ -0,0 +1,34 @@
+# pr-consistency-audit skill
+
+Audits a PR for cross-file inconsistencies: wrong argument names, missing required args, references to files or scripts that do not exist, stale feature remnants, docstring-vs-code mismatches, placeholder text, cross-file contradictions, parameter naming convention violations, and cross-platform bugs.
+
+**Trigger:** "audit this PR", "find inconsistencies", "cross-reference docs against scripts", "check for stale references", "PR consistency audit".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full process: build manifest, find canonical sources, run 10 detection rules, produce summary |
+| `reference/detection-rules.md` | All 10 detection rules with procedures |
+| `reference/illustrations.md` | Concrete examples of findings with why-they-matter explanations |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Detection rules and worked illustrations |
+
+## Process overview
+
+1. **Build manifest** — read every changed file; track argparse args, MCP tool calls, shell commands, file path references, named constants, and docstring claims. Write to a temp JSON file.
+2. **Find canonical sources** — note which files define the ground truth for each concept (schemas, payloads, config files, `.py` sources).
+3. **Run all 10 detection rules** — write each finding at once to a temp CSV with `file_path | line_number | rule_id | severity | what_is_wrong | what_it_should_be | evidence_path | evidence_detail`.
+4. **Produce summary** — print totals by rule and severity; list top findings; cite the CSV and manifest paths.
+
+## Severity
+
+| Severity | Meaning |
+|---|---|
+| P0 | Runtime failure — the command or tool call will error |
+| P1 | Confusing or wrong — will mislead but not crash |
+| P2 | Cleanup — stale references, docs out of sync |

package/skills/pr-consistency-audit/reference/CLAUDE.md

@@ -0,0 +1,16 @@
+# pr-consistency-audit/reference
+
+Reference material for the `pr-consistency-audit` skill. These files define the detection rules the skill runs and show worked examples of findings.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `detection-rules.md` | All 10 detection rules, each with a procedure for how to run it |
+| `illustrations.md` | Concrete examples of findings with explanations of why each matters |
+
+## Conventions
+
+- The skill reads `detection-rules.md` during Step 3 (run detection rules). Every rule must run against every file; none are skippable.
+- Rule 1 (canonical-source cross-reference) is the highest-signal rule. The skill runs it first.
+- `illustrations.md` is for reviewers and skill authors, not for the skill's runtime process.

package/skills/pr-converge/CLAUDE.md

@@ -0,0 +1,29 @@
+# pr-converge skill
+
+Drives a draft PR to convergence by looping Cursor Bugbot, a code-review pass, a second-opinion bug audit (`bugteam`), and Copilot — applying TDD fixes, posting inline replies, and re-triggering reviewers each tick until all reviewers 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 |
+
+## Conventions
+
+- Each invocation runs one tick. The next tick is scheduled via `ScheduleWakeup` unless convergence or a stop condition has been reached.
+- Loop state persists to `$CLAUDE_JOB_DIR/pr-converge-state.json` between ticks.
+- The pre-flight gate requires `EnterWorktree` before any file read or API call, and confirms `ScheduleWakeup` is in the tool list.
+- 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.

package/skills/pr-converge/pr_converge_skill_constants/CLAUDE.md

@@ -0,0 +1,26 @@
+# 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/skills/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.

package/skills/pr-converge/reference/CLAUDE.md

@@ -0,0 +1,27 @@
+# pr-converge/reference
+
+Reference documents for the `pr-converge` skill. These files define the per-tick step sequence, convergence gates, fix protocol, stop conditions, state schema, multi-PR orchestration, and examples.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run BUGBOT, CODE_REVIEW, BUGTEAM, COPILOT_WAIT phases, schedule next wakeup) |
+| `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
+| `fix-protocol.md` | How to apply fixes: TDD first, one commit per fix round, reply to each finding inline |
+| `ground-rules.md` | Non-negotiable constraints for the convergence loop |
+| `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
+| `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |
+| `multi-pr-orchestration.md` | How to run the loop across multiple PRs in parallel |
+| `examples.md` | Worked examples of tick sequences |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-obstacle runbooks for known failure modes in the convergence loop |
+
+## Conventions
+
+- `per-tick.md` is the primary reference loaded during each tick. The pacing workflow lives in `../workflows/schedule-wakeup-loop.md`.
+- Every gate in `convergence-gates.md` must produce evidence before the next gate runs.

package/skills/pr-converge/reference/obstacles/CLAUDE.md

@@ -0,0 +1,23 @@
+# pr-converge/reference/obstacles
+
+Per-obstacle runbooks for known failure modes in the `pr-converge` convergence loop. Each file covers one specific obstacle: what causes it, how to detect it, and how to recover.
+
+## Files
+
+| File | Obstacle |
+|---|---|
+| `fix-post-replies.md` | Posting inline review replies fails or posts to the wrong thread |
+| `fix-publish-summary.md` | Publishing the bugteam summary comment fails |
+| `fix-push.md` | `git push` fails during a fix commit |
+| `fix-read-filelines.md` | Reading file line ranges for a fix fails |
+| `fix-reset-state.md` | State JSON becomes corrupt or inconsistent between ticks |
+| `fix-resolve-threads.md` | Resolving inline comment threads via GraphQL fails |
+| `fix-spawn-clean-coder.md` | Spawning the `clean-coder` subagent fails or produces no output |
+| `fix-stage-commit.md` | Staging or committing a fix fails |
+| `fix-trigger-bugbot.md` | Triggering Cursor Bugbot via an issue comment fails |
+| `fix-write-test.md` | Writing a failing test before a fix fails |
+
+## Conventions
+
+- Each runbook is loaded on demand when the convergence loop hits that specific obstacle.
+- Runbooks do not overlap with `per-tick.md`; they cover edge cases and recovery paths that fall outside the normal tick flow.

package/skills/pr-converge/scripts/CLAUDE.md

@@ -0,0 +1,36 @@
+# pr-converge/scripts
+
+Python helper scripts for the `pr-converge` skill, plus their tests and a PowerShell/AutoHotkey toolset for advancing Cursor agents.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
+| `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
+| `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
+| `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
+| `post_fix_reply.py` | Posts an inline reply to a review comment thread |
+| `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
+| `README.md` | MCP tool reference for PR operations used by the scripts |
+| `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
+| `test_check_convergence.py` | Tests for `check_convergence.py` |
+| `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
+| `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
+| `caller-window-pid.ps1` | Gets the PID of the calling terminal window |
+| `cursor-agents-continue.ahk` | AutoHotkey script to advance Cursor agent prompts |
+| `cursor-agents-continue.cmd` | CMD wrapper for the AHK script |
+| `cursor-agents-continue-stop-others.ps1` | Stops other Cursor agents before advancing one |
+| `cursor-agents-continue-caller.cmd` | Caller-side CMD wrapper |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr_converge_scripts_constants/` | Script-specific constants (re-exports skill constants plus adds reflow/CLI constants) |
+
+## Conventions
+
+- Scripts import constants from `pr_converge_scripts_constants.pr_converge_constants`, which re-exports everything from `pr_converge_skill_constants.constants`.
+- Run scripts as `python ~/.claude/skills/pr-converge/scripts/<script>.py --owner <O> --repo <R> --pr-number <N>`.
+- The `reflow_skill_md.py` script targets `SKILL.md` in the parent skill directory (resolved via `TARGET_SKILL_PATH` in `pr_converge_scripts_constants/reflow_skill_md_constants.py`).

package/skills/pr-converge/scripts/pr_converge_scripts_constants/CLAUDE.md

@@ -0,0 +1,17 @@
+# pr_converge_scripts_constants
+
+Constants module for the `pr-converge` skill's Python scripts. Re-exports all runtime/API constants from the skill-level module and adds script-specific constants for CLI arguments, markdown patterns, and reflow settings.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
+| `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
+
+## Conventions
+
+- `pr_converge_constants.py` uses `from pr_converge_skill_constants.constants import ...` (with `# noqa: F401`) to re-export everything so script files can import from one location.
+- `reflow_skill_md_constants.py` resolves `TARGET_SKILL_PATH` from its own `__file__` path, pointing to `SKILL.md` three directories up.
+- Script-specific regex patterns (ordered list items, bullet list items, unfinished markdown link targets, markdown reference definitions) live in `reflow_skill_md_constants.py`.

package/skills/pr-converge/workflows/CLAUDE.md

@@ -0,0 +1,16 @@
+# pr-converge/workflows
+
+Pacing workflow specification for the `pr-converge` loop.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `schedule-wakeup-loop.md` | Specifies `ScheduleWakeup` call parameters, delays, and stop/convergence conditions for each tick |
+
+## Conventions
+
+- `per-tick.md` (in `../reference/`) references this file for Step 4 (schedule next wakeup). Read it before running Step 4.
+- Default delay: `delaySeconds: 360`. Exception: BUGBOT inline-lag branch uses `delaySeconds: 90`.
+- On convergence or a hard stop condition, omit the `ScheduleWakeup` call entirely.
+- The `reason` field in each `ScheduleWakeup` call names what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.