claude-dev-env 1.68.0 → 1.69.0

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.

package/skills/pr-review-responder/CLAUDE.md

@@ -0,0 +1,35 @@
+# pr-review-responder
+
+Mandatory systematic protocol for responding to GitHub PR review comments.
+
+**Trigger:** "address feedback", "fix review comments", "respond to code review", "handle PR feedback", "reply to reviewer".
+
+## Purpose
+
+Prevents missed review comments by enforcing a strict fetch-then-checklist-then-fix order. The skill is declared `MANDATORY` — any PR review response that skips it is an automatic failure per the skill body.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — the seven mandatory rules and the final report format |
+| `EXAMPLES.md` | Concrete good and bad reply examples |
+| `PRINCIPLES.md` | Design rationale behind the protocol |
+| `README.md` | Overview for readers new to the skill |
+| `TESTING.md` | Testing guidance for the skill |
+
+## Seven mandatory rules
+
+1. Fetch ALL review comments with `per_page=100` before touching any file.
+2. Create a `TodoWrite` checklist — one item per comment — before any fix.
+3. Fix one comment at a time, marking each todo complete before moving on.
+4. Write reply text for every comment; never post directly.
+5. Create ONE new commit for all fixes from this review round; never squash with the original.
+6. Push — the git pre-push hook fires automatically.
+7. Verify the draft count matches the comment count before reporting done.
+
+## Conventions
+
+- GitHub MCP (`pull_request_read`) with `per_page=100` is the required fetch path.
+- Draft replies are presented for the user to post; Claude never posts them directly.
+- The pre-push hook (`npx claude-dev-env`) runs on `git push` with no manual invocation.

package/skills/pre-compact/CLAUDE.md

@@ -0,0 +1,24 @@
+# pre-compact
+
+Composes the `/compact` focus directive for the current session and copies the full `/compact <directive>` string to the clipboard.
+
+**Trigger:** `/pre-compact` or any request to "prep for compaction".
+
+## Purpose
+
+`/compact [instructions]` accepts a directive that steers the compaction summarizer toward high-signal content. This skill builds that directive from live session state — validated against the actual git branch, PR, HEAD SHA, and worktree path — and delivers it ready to paste.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — five steps (confirm intent, validate live state, write directive, copy to clipboard, hand off). No companion files. |
+
+## How the skill runs
+
+1. Asks the operator what they plan to work on next (via `AskUserQuestion`).
+2. Reads each identifier live (`git branch --show-current`, `git rev-parse --short HEAD`, `gh pr view`, `pwd`) rather than relying on conversation context.
+3. Produces a `Preserve:` block scoped to what the next task actually needs.
+4. Writes the full `/compact <directive>` string to a temp file, copies it via `pwsh Set-Clipboard`, then cleans up.
+
+`disable-model-invocation: true` is set — this skill runs without a secondary LLM call; it is pure procedural text assembly.

package/skills/qbug/CLAUDE.md

@@ -0,0 +1,40 @@
+# qbug
+
+Quick baseline PR audit: one clean-coder subagent loops audit → fix → commit → push until the PR is clean or stuck.
+
+**Trigger:** `/qbug`, "quick bug audit", "solo bug audit", "baseline PR review", "bugteam without a team".
+
+## Purpose
+
+`/qbug` is the required baseline review for every new PR. It runs the same A–N bug category rubric and CODE_RULES gate as `/bugteam` but with a single persistent subagent (no TeamCreate, no per-loop clean-room, no loop cap). Escalate to `/bugteam` when bias isolation across loops matters.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four steps (pre-flight, resolve PR scope, spawn subagent cycle, final report). Self-contained with full subagent XML prompt inline. |
+
+## Shared artifacts (referenced by path, not copied)
+
+The skill references shared scripts from `../_shared/pr-loop/scripts/`:
+
+| Script | Role |
+|---|---|
+| `preflight.py` | Git hooks path check, pytest, optional pre-commit |
+| `code_rules_gate.py` | CODE_RULES gate run before every AUDIT |
+| `post_audit_thread.py` | Posts one GitHub review per loop (APPROVE or REQUEST_CHANGES) |
+| `audit-reply-template.md` | Unified reply body shape for resolved threads |
+
+Bug category rubric A–N lives at `../bugteam/PROMPTS.md`. Audit contract (finding schema, proof-of-absence, Haiku secondary, self-audit) lives at `../bugteam/reference/audit-contract.md`.
+
+## Subagent structure
+
+- **Primary:** `clean-coder` — runs the full audit → fix → commit → push cycle internally.
+- **Secondary:** `code-quality-agent` (Haiku model) — audit-only, read-only; findings merged before FIX step.
+- No `TeamCreate`. No loop cap. Exits on `converged`, `stuck`, or `error`.
+
+## Conventions
+
+- The lead resolves the temp directory via Python's `tempfile.gettempdir()` and passes the absolute path to the subagent.
+- Each loop: one `code_rules_gate.py` pre-audit, one GitHub review posted, one commit on fix.
+- Self-PR toggle: `post_audit_thread.py` detects author-equals-reviewer and switches to an alternate `gh` account automatically.

package/skills/rebase/CLAUDE.md

@@ -0,0 +1,32 @@
+# rebase
+
+Rebase a branch onto its base ref with verification gates that catch logically broken results before pushing.
+
+**Trigger:** `/rebase`, "rebase this branch", "PR has merge conflicts", "rebase onto main", force-push to update remote branch history.
+
+## Purpose
+
+The default failure mode for a rebase is shipping code that compiled but does not run. This skill prevents that by running real import checks, test collection, and symbol scans after every rebase — not just syntax validation.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four phases (pre-rebase analysis, during rebase, verification gates, push). No companion files. |
+
+## Four phases
+
+| Phase | Key actions |
+|---|---|
+| 1 — Pre-rebase analysis | Resolve base via `gh pr view`, classify scenario (stacked/squash/long-lived), fetch fresh, scan commit messages for deleted/renamed symbols |
+| 2 — During rebase | Verify `--skip` with a diff, audit auto-merged files with `git diff --name-only --diff-filter=M ORIG_HEAD` |
+| 3 — Verification gates | `python -m compileall`, `pytest --collect-only -q`, targeted test run, reference scan for removals |
+| 4 — Push | Explicit authorization required; `--force-with-lease=<branch>:<sha>` only; verify mergeability after push |
+
+## Conventions
+
+- Force-push requires explicit operator authorization every time — auto mode does not bypass this.
+- `--force-with-lease=<branch>:<sha>` only; bare `--force` is refused.
+- Never force-push `main`, `master`, `release/*`, `production`, or any multi-author branch.
+- Symbol scans prefer Serena (`find_referencing_symbols`) then the Grep tool, then shell grep as a last resort.
+- `ORIG_HEAD` is the correct ref for auto-merged file audits mid-rebase; `HEAD@{1}` shifts per step.

package/skills/recall/CLAUDE.md

@@ -0,0 +1,30 @@
+# recall
+
+Retrieves prior session context and decisions from the Obsidian vault for the current project.
+
+**Trigger:** `/recall [search query or project name]`.
+
+## Purpose
+
+Surfaces relevant session reports, decision notes, and research from the Obsidian vault before starting work. Prevents repeating decisions already made or missing known gotchas.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (resolve query, frontmatter search, content search, read top matches, present with attribution, handle no results). No companion files. |
+
+## How the skill runs
+
+1. Uses `$ARGUMENTS` as the search query, or infers the project name from conversation context.
+2. Searches by frontmatter first (`mcp__obsidian__search_notes` with `searchFrontmatter: true`) to catch session reports and decision notes tagged with the project.
+3. Falls back to content keyword search when frontmatter search returns few results.
+4. Reads the top 3 most relevant notes via `mcp__obsidian__read_note`, preferring recent notes and decision summaries over raw research.
+5. Reports each note with its path, date, relevant excerpts, and whether any decisions are marked `status: Superseded`.
+6. States clearly when no vault history exists — never infers or invents history.
+
+## Conventions
+
+- `disable-model-invocation: true` is not set; this skill does invoke the model to synthesize results.
+- The skill is read-only: it never writes to the vault.
+- Companion to `/remember` (which writes decisions) and `/session-log` (which writes session reports).