rk-skills 1.0.0

package/skills/fix-pr-review/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: fix-pr-review
+description: Use when the user asks to fix, address, or respond to a PR review — "fix the PR review", "address the review comments", "/fix-pr-review". Takes an optional PR number/URL (defaults to the current branch's PR). Fetches all unaddressed review feedback on the PR (formal reviews, review-style issue comments, and inline diff comments), RE-VALIDATES every finding against the actual code before touching anything (never blind-implements), fixes the findings that survive validation, and for judgment calls and optional improvements derives and implements the absolute-best solution autonomously without pausing, then commits and pushes, posts a per-finding disposition comment back to the PR, and triggers a fresh @claude re-review.
+---
+
+# fix-pr-review
+
+Take all unaddressed review feedback on a pull request and resolve it fully and autonomously: re-validate each finding against the code, fix the ones that are real, push back on the ones that aren't, and for the judgment calls the reviewer couldn't make — and for the optional improvements — derive and implement the absolute-best solution rather than pausing. Then report back on the PR and request a re-review. Don't stop to ask the user; do the work.
+
+**The review is a hypothesis, not a work order.** A reviewer (human or `@claude`) can cite a stale line, misread a conditional, or flag a non-bug. Implementing a wrong suggestion ships a regression with a reviewer's blessing. So every finding is traced to current `file:line` and confirmed *before* you change anything. You are not performing agreement — you are verifying claims and acting only on the ones that hold.
+
+## Input
+
+The user provides one of:
+- Nothing — **default to the PR for the current branch** (`gh pr view`).
+- `#<N>` / `<N>` / full URL / `owner/repo#N`.
+
+If the current branch has no PR and none was given, say so and stop — there's nothing to fix.
+
+## Steps
+
+### 0. Resolve the PR and sync the branch
+
+```bash
+gh pr view <N|--> --json number,headRefName,headRepositoryOwner,baseRefName,url,state,isDraft
+git fetch origin
+git branch --show-current
+```
+
+- Confirm you are **on the PR's head branch** (`headRefName`). If not, check it out with `gh pr checkout <N>` — it handles fork-hosted head branches and sets upstream tracking. Fixes must land on the branch the PR tracks, never on `main` or a divergent branch. Never fix a review by committing to the base branch.
+- Note whether the PR is from a **fork** (`headRepositoryOwner` differs from the base repo's owner) — the head branch then lives in the fork, so pulls and pushes go to the branch's tracked upstream, not `origin`.
+- Pull the latest head so you fix against what the reviewer saw: `git pull --ff-only` on the tracked upstream (if it can't fast-forward, stop and tell the user the branch diverged).
+- Note the PR state. If it's already `merged` or `closed`, stop and report — don't reopen work on a closed PR without the user.
+
+### 1. Fetch all unaddressed review feedback
+
+Review feedback arrives through three channels: formal GitHub PR reviews, plain issue comments (the `@claude` bot posts the verdict-and-sections format as an issue comment), and **inline diff comments** (line-level threads, where human reviewers most often comment). Fetch all three:
+
+```bash
+# PR reviews (formal review events) — state included so DISMISSED reviews can be skipped
+gh api repos/{owner}/{repo}/pulls/<N>/reviews --paginate --jq '.[] | {id, user: .user.login, state, submitted_at, body}'
+# Issue comments on the PR (where @claude review output usually lands) — REST + --paginate for completeness
+gh api repos/{owner}/{repo}/issues/<N>/comments --paginate --jq '.[] | {author: .user.login, created_at, body}'
+# Inline diff threads WITH resolution state — REST can't report isResolved, so use GraphQL
+gh api graphql -F owner='{owner}' -F repo='{repo}' -F pr=<N> -f query='
+  query($owner:String!,$repo:String!,$pr:Int!){ repository(owner:$owner,name:$repo){ pullRequest(number:$pr){
+    reviewThreads(first:100){ pageInfo{hasNextPage endCursor} nodes{ isResolved isOutdated path line
+      comments(first:50){ nodes{ databaseId author{login} createdAt body } } } } } } }'
+```
+
+(If `hasNextPage` is true, paginate with `endCursor` — don't silently drop threads past 100.)
+
+Determine the **cutoff**: the timestamp of your most recent disposition comment on the PR (or the last commit you pushed addressing a review). Then collect:
+
+- Every formal review or review-formatted issue comment **newer than the cutoff** (no cutoff → everything since the PR opened) — it opens with a `LGTM` / `Needs Updates` verdict, contains review sections like `### Needs Fixing`, or is otherwise clearly review feedback. **If multiple reviews landed — e.g. two reviewers — address all of them**, not just the latest. Skip `DISMISSED` reviews.
+- Every **unresolved** inline thread (`isResolved: false`), **regardless of age** — resolution state, not timestamp, decides whether a thread is open work. A thread from before the cutoff that the reviewer never resolved is still open. Exception: if the thread's last comment is your own disposition reply and no one has responded since, it's awaiting the reviewer — skip it. `isOutdated` alone doesn't mean resolved. Treat each thread as one finding.
+- Ignore your own prior disposition comments and `@claude review` trigger comments.
+
+State what you picked (authors + timestamps) so the user can confirm it's the right set.
+
+**Note whether the collected set contains any blocking finding** — a `Needs Fixing` or `Requires Human Review` item from any review, or an inline thread asserting a real defect (classified in step 2). This drives the re-review routing in step 7.
+
+**If the only new feedback is `LGTM` with no blocking sections:** there's nothing blocking, but still address any non-blocking items the review raised — implement each `Recommended Optional` item with the absolute-best-solution standard (step 4), and file each `Create Follow-up Issue` item as a GitHub issue. Don't invent work the review never raised; if the feedback is a bare `LGTM` with no items at all and no open inline threads, report that the PR is approved and stop.
+
+### 2. Extract findings
+
+Parse all collected feedback — structured reviews and inline diff threads alike — into discrete findings, tagged by section:
+- **Needs Fixing** — blocking; reviewer asserts a real defect.
+- **Requires Human Review** — blocking; reviewer couldn't decide (a genuine tradeoff or missing context).
+- **Recommended Optional** — non-blocking improvement.
+- **Create Follow-up Issue** — out-of-scope, track separately.
+
+For free-form feedback with no sections — including inline diff comments — classify each point yourself into the same four buckets by its substance. Keep each finding atomic — split compound feedback ("fix X and also Y") into separate findings so each gets its own verdict. When the same defect is raised by more than one reviewer or thread, merge into one finding and note all sources.
+
+### 3. Re-validate each finding against the code (the core step)
+
+For **every** finding — including ones that read as obviously correct — trace the claim to current code and assign a verdict. Endorsement is a verification act, not a relay: re-derive the finding from the code with your own `file:line`, don't transcribe the reviewer's reasoning.
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| ✅ **Confirmed** | Code at `file:line` matches the finding; the defect/improvement is real | Fix it (step 4) |
+| ❌ **Refuted** | Code does not do what the finding claims, or the suggested change would itself be wrong/regressive | Do **not** change; record a one-line, code-grounded rebuttal for the reply |
+| ⚠️ **Partial** | Real but narrower/broader than stated, or true only on one path | Fix the true part; note the correction |
+| ❓ **Judgment** | A real tradeoff or a decision the reviewer couldn't make (most `Requires Human Review` items) | Derive the absolute-best solution and **implement it** (see below) — don't pause, don't guess blindly, don't punt empty-handed |
+
+Validation discipline (this is where fixing a review goes wrong):
+- **Read the body, not just the cited line.** A name states intent; open the function and trace the conditional fully before agreeing.
+- **Prove negatives by reading the path.** "X is never validated / never freed / not awaited" — confirm the absence across *all* relevant paths, not the one the reviewer looked at; the behavior may be produced elsewhere.
+- **A suggested fix is its own claim.** "Just add a lock here" can deadlock; "default it to N" can break a caller. Verify the *remedy* is correct for this codebase, not only that the *problem* exists. Derive the right fix from first principles if the suggested one is suboptimal — correctness and safety outrank matching the reviewer's wording.
+- **Safety carve-out:** any finding touching money, data integrity, security, or an auto-protective mechanism gets fixed or escalated to the user even at low confidence — never silently dropped as Refuted unless you can prove from code it's a non-issue.
+
+**For every ❓ Judgment finding, do the analysis the reviewer couldn't and implement the result — don't hand the tradeoff back.** Trace the code, enumerate the viable approaches, and derive the **absolute-best solution**, evaluated as if cost, effort, time, resources, token spend, and code volume were unlimited — they are *not* factors and must never narrow the option space. The only things that can override "best" are correctness and safety. Choose the most correct, most robust design even when it's far more work, then implement it (step 4) in this same run. Do **not** pause to ask the user. Record the decision in the disposition comment — the chosen solution, the code-grounded reasoning (`file:line`), and the rejected alternatives in one line each — so the human can override after the fact if they disagree.
+
+This same absolute-best-solution standard governs `Recommended Optional` improvements: implement them too, choosing the best design with cost/effort/time/resources treated as non-factors.
+
+### 3.5 Select the working model from the validated findings
+
+Steps 2–3 always run inline in this session — validation is the hard thinking and doubles as the model-selection signal, so it never gets delegated. Now choose who implements, keyed to the **implementation complexity of the surviving work** — not its blocking/optional category (a blocking fix can be a trivial one-liner; an optional refactor can be genuinely hard).
+
+First, two absolute inline gates that override any complexity read:
+- Any ❓ Judgment call whose remedy is still open-ended, or any finding under the safety carve-out (money, data integrity, security, auto-protective mechanisms) — open decisions and high blast radius never get delegated.
+
+Otherwise, rate each surviving fix's complexity from your validation (you just traced the code, so you know): **scope** (files/layers touched, cross-cutting vs. local), **subtlety** (concurrency, ordering, invariants, edge-case reasoning vs. mechanical edits), and **verification difficulty** (needs careful test design vs. existing suite covers it). The **most complex fix** sets the tier for the whole set (never the average, never split across subagents):
+
+- **Opus subagent (`model: "opus"`)** — any fix is non-trivial: multi-file or cross-layer, touches subtle logic, or its correctness needs real reasoning to preserve.
+- **Sonnet subagent (`model: "sonnet"`)** — every fix is simple and mechanical: localized edits with a pinned-down remedy, plus any `Create Follow-up Issue` filings and Refuted rebuttals to write up.
+
+When in doubt between tiers, take the higher one — misrouting hard work down costs correctness; misrouting easy work up costs nothing that matters.
+
+When dispatching, use the Agent tool (`subagent_type: general-purpose`, synchronous — `run_in_background: false`) with a prompt that tells the subagent to: read this SKILL.md file and execute steps 4 through 8 exactly (skipping steps 0–3.5 — no re-validation, no recursive dispatch), for PR `<N>`, using the validated findings and per-finding verdicts you produced in steps 2–3 (paste them into the prompt, including the pinned-down remedies for Confirmed/Partial findings and the derived best-solution designs for any Optional items, so it implements your analysis rather than re-deciding). The subagent's **LLM Attribution Footers** (commit + disposition comment) must name the model actually doing the work (e.g. `Opus 4.8` / `Sonnet 5`), not the session model. When the subagent returns, relay its step-8 report to the user verbatim plus which model ran; don't redo its work.
+
+If the Agent tool's model override is unavailable in the current harness, fall back to running inline and note the intended model in the report.
+
+### 4. Implement the fixes
+
+Implement every finding that calls for a change: ✅ Confirmed, ⚠️ Partial (the true part), ❓ Judgment (the absolute-best solution you derived), and `Recommended Optional` (best-solution standard). Skip only ❌ Refuted and `Create Follow-up Issue` items.
+
+- Read the surrounding code and follow existing conventions before editing.
+- Keep each fix scoped to its finding; don't smuggle in unrelated refactors. (Scope ≠ minimalism: for Judgment and Optional items, pick the *best* design, not the smallest diff — correctness and robustness outrank brevity.)
+- After all fixes, **verify**: run the project's tests/build/lint (check the repo's `CLAUDE.md` / `package.json` / Makefile for the commands — e.g. `bun test`, `go test -race ./...`, `bun run build`). Evidence before assertions: do not claim a fix works without running verification, and report any failures honestly rather than papering over them.
+- If a fix turns out infeasible or reveals the finding was actually Refuted, move it to the Refuted bucket with the reason.
+
+### 5. Commit and push
+
+Only after verification passes:
+
+```bash
+git status                      # confirm only the files you edited are dirty
+git add <specific files>        # stage each file you changed for the fixes — never `git add -A` or `git add .`
+git commit -F <msg-file>        # see footer below
+git push                        # to the branch's tracked upstream — for a fork PR the head lives in the fork, so `git push origin <headRefName>` would be wrong
+```
+
+If the branch has no upstream set (manual checkout instead of `gh pr checkout`), push explicitly to the PR's **head repository** remote — never assume `origin`.
+
+Staging explicitly prevents sweeping in unrelated dirty files, scratch files, or untracked artifacts. If `git status` shows changes you didn't make, leave them unstaged and mention them in the report.
+
+Commit message: a concise summary of what review findings were addressed (reference the PR, e.g. "Address review on #<N>: <one-line summary>"). This is a revision to an existing PR, so the footer uses the **Updated** verb:
+
+```
+---
+Updated with LLM: <current model> | <effort> | Harness: Claude Code
+```
+
+Fill `<current model>` (e.g. `Opus 4.8`) and `<effort>` (`high` by default). Per the user's workflow, never include time/effort estimates in the message body.
+
+### 6. Post the disposition comment back to the PR
+
+Post one comment that tells the reviewer exactly what happened to each finding — this is how a refuted finding gets its pushback on the record. Write it as direct, scannable status:
+
+```
+Addressed review feedback (<reviewer(s)> · <timestamp(s)>) in <commit-sha>.
+
+### Fixed
+1. **<finding title>** — <what changed> (`file:line`).
+
+### Corrected scope (partial)
+1. **<finding title>** — <what was real and fixed vs. what wasn't> (`file:line`).
+
+### Not changed (refuted)
+1. **<finding title>** — <code-grounded reason the suggestion doesn't apply> (`file:line`).
+
+### Resolved judgment calls (was Requires Human Review)
+1. **<finding title>** — implemented <the absolute-best solution and why, `file:line`>. Alternatives rejected: <one line each>. Override if you'd prefer one of these.
+
+### Deferred to follow-up
+1. **<finding title>** — <why it's out of scope; issue link filed>.
+```
+
+Omit any empty section. Keep each item one line with a `file:line` anchor. For findings that came from inline diff threads, also post a one-line reply in the thread itself — use the root comment's `databaseId` from step 1's thread query: `gh api repos/{owner}/{repo}/pulls/<N>/comments/<databaseId>/replies -f body=...` — that's where the reviewer is watching. Post the main comment via:
+
+```bash
+gh pr comment <N> --body-file <file>
+```
+
+Footer on the comment uses the **Created** verb (it's a new comment):
+
+```
+---
+Created with LLM: <current model> | <effort> | Harness: Claude Code
+```
+
+### 7. Trigger the @claude re-review
+
+Route the re-review by whether the set you addressed contained **any blocking finding** (noted in step 1) — never by the newest review's verdict alone: with multiple reviewers, a later `LGTM` from one does not erase another's `Needs Updates`.
+
+- **Any blocking finding addressed** (`Needs Fixing` / `Requires Human Review` from any review, or an inline thread that validated as a real defect): trigger plain — this repo's default (Opus) reviews the fix.
+- **Only non-blocking items** (optional improvements / follow-ups): the PR was already in good shape, so route the re-review to Sonnet via the `@claude sonnet` shorthand instead.
+
+Post a **separate** comment so the bot triggers cleanly on its own line:
+
+```bash
+# blocking findings were addressed
+gh pr comment <N> --body "@claude review"
+
+# only non-blocking items were addressed
+gh pr comment <N> --body "@claude sonnet review"
+```
+
+(If this repo uses a different review trigger phrase or model-shorthand syntax, match it — check the repo's `.github/workflows/claude.yml` for how it resolves `@claude <shorthand>`, and recent PR comments for the convention.) A trigger comment is a one-line mention, not authored content — no footer.
+
+### 8. Report to the user
+
+Terse summary: which reviews/threads you acted on, counts per disposition (fixed / partial / refuted / judgment-resolved / optional / deferred), the commit SHA, verification result, and that a re-review was requested (note which model it was routed to). Flag the resolved judgment calls so the user can override if they disagree — but the work is already done, not waiting on them.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|-----------|--------|
+| Finding cites a line that no longer matches current code | Re-validate against current `file:line`; it may already be fixed — mark Refuted with the reason |
+| Suggested fix would touch money/data/security/auto-protective logic | Never blind-apply; verify the remedy from first principles and implement the safest correct design |
+| Reviewer's remedy is plausible but you can't confirm it's correct here | Don't implement on faith — trace it, then implement the absolute-best solution you can stand behind from the code |
+| A collected "review" is actually your own prior disposition comment or an `@claude review` trigger | Skip it; act only on *actual* review feedback |
+| Only some feedback channels checked (e.g. formal reviews but not inline diff threads) | Fetch all three sources before extracting findings — inline threads are where human reviewers usually comment |
+| `git status` shows dirty files you didn't edit | Stage only your fix files; leave the rest and mention them in the report |
+| You're on `main` or a divergent branch, not the PR head | Check out the PR head first; never commit review fixes to the base branch |
+| Branch can't fast-forward to its upstream head | Stop — the branch diverged; surface to the user, don't force anything |
+| PR is from a fork | Check out with `gh pr checkout` and push to the tracked upstream — `origin` is the wrong remote for the head branch |
+| All findings refuted | Still post the disposition comment with the rebuttals and request re-review — don't silently no-op |
+| `Requires Human Review` item | Derive and **implement** the absolute-best solution (ignore cost/effort/time/resources; only correctness and safety override "best"); document the decision + rejected alternatives in the comment so the user can override. Never pause for confirmation, punt the bare tradeoff, or guess blindly |
+| Tests/build fail after fixes | Report the failure; don't push or claim success |
+
+## Common Mistakes
+
+- **Blind-implementing the review.** Performative agreement ships regressions. Validate first, every time.
+- **Delegating validation.** Steps 2–3 always run inline — the model-selection gate keys off *validated* verdicts, and a lighter model triaging its own workload defeats the gate. Dispatch only steps 4–8, tiered by the most complex surviving fix (open judgment/safety → inline, any non-trivial fix → Opus, all-mechanical → Sonnet), and never split one review across subagents. The subagent's footers must name the model that actually ran, not the session model.
+- **Missing inline diff comments.** Fetching only formal reviews and issue comments skips the line-level threads where human reviewers usually comment. Fetch all three channels.
+- **Addressing only the latest review when several landed.** Every review newer than your last disposition and every unresolved inline thread (any age) gets addressed.
+- **Routing the re-review by the newest verdict.** A later `LGTM` from one reviewer doesn't erase another's blocking findings — route by whether any blocking finding was addressed.
+- **`git add -A`.** Stage the fix files explicitly; a blanket add can commit unrelated dirty or untracked files.
+- **Dropping a refuted finding silently.** Push back on the record in the comment with a code-grounded reason — that's how the reviewer learns it was wrong.
+- **Committing to the base branch.** Fixes land on the PR head branch only.
+- **Skipping verification before push.** Run the tests/build; report real results.
+- **Pausing or punting on a judgment call.** Do the analysis the reviewer couldn't and *implement* the absolute-best solution (cost/effort/time/resources are not factors; only correctness and safety override it); document it for override. Don't stop to ask, don't relay the bare tradeoff, don't guess blindly.
+- **Skipping the optional improvements.** `Recommended Optional` items get implemented to the same best-solution standard, not deferred.
+- **Bundling the re-review trigger into the disposition comment.** Keep `@claude review` as its own comment so the bot fires reliably.

package/skills/fix-pr-review-loop/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: fix-pr-review-loop
+description: Use when the user asks to fix a PR review and drive it to approval autonomously — "fix the PR review and loop until approved", "fix-pr-review-loop", "keep addressing review comments until this PR is approved", or as the standalone counterpart to work-on-issue-loop's polling/resolving steps for a PR that already exists. Takes an optional PR number/URL (defaults to the current branch's PR). Repeatedly calls fix-pr-review to resolve the latest review, waits for the resulting @claude re-review, and repeats. Stops on a bare LGTM with nothing left to fix; once past 5 review cycles it stops at the first LGTM it sees even if non-blocking findings remain, rather than continuing to chase them.
+---
+
+# fix-pr-review-loop
+
+Drive an already-open PR from "has review feedback" to "reviewed to convergence" without stopping in between: resolve the latest review (fix-pr-review), wait for the bot's re-review, and repeat. Past 5 cycles the bar for "done" relaxes — any LGTM ends the loop — so a PR with recurring minor findings doesn't get fix-pr-review'd forever. This is the same convergence loop work-on-issue-loop runs after it opens a PR, factored out so it can be pointed at any PR directly.
+
+## Input
+
+- Nothing — default to the PR for the current branch (`gh pr view`).
+- `#<N>` / `<N>` / full URL / `owner/repo#N`.
+
+## Steps
+
+### 1. Resolve the PR and establish the starting state
+
+```bash
+gh pr view <N|--> --json number,headRefName,headRepositoryOwner,baseRefName,url,state,isDraft
+```
+
+- If the PR is already `merged` or `closed`, stop and report — there's nothing to drive.
+- Fetch the current review feedback using fix-pr-review step 1's three-channel query (formal reviews, issue comments, inline diff threads) to see what has already landed.
+- **Unaddressed feedback is already present** (a review/comment newer than any prior disposition comment, or an unresolved inline thread): treat it as the first landed review. Set `review_count = 1`, note its timestamp, and skip straight to step 3 — don't wait for a review that already arrived.
+- **No review feedback at all yet** (fresh PR, or every existing comment is your own prior disposition/trigger): trigger one yourself:
+  ```bash
+  gh pr comment <N> --body "@claude review"
+  ```
+  Record the trigger timestamp, set `review_count = 1`, and go to step 2 to wait for it.
+
+### 2. Wait for the review to land
+
+Poll the PR for a new review or issue comment posted **after** the last trigger timestamp — reviews can land as a formal PR review or as an issue comment (the `@claude` bot usually posts as an issue comment; see fix-pr-review step 1 for the `gh` calls to check — it also fetches inline diff threads, which matter when a human reviewer weighs in). An until-loop is the right shape here — you want to be notified once the condition is true, not to busy-poll inline:
+
+```bash
+until gh pr view <N> --json comments,reviews --jq '
+  ([.comments[] | select(.createdAt > "<trigger_ts>")] |
+   any(.body | test("(^|\\n)(LGTM|Needs Updates)"))) or
+  ([.reviews[] | select(.submittedAt > "<trigger_ts>")] | length > 0)
+' | grep -q true; do sleep 60; done
+```
+
+Two load-bearing details in that condition (both have silently broken monitors before — a wrong filter here reads as "no review yet" forever):
+
+- **Match the verdict with `(^|\\n)`, not `^` + the `m` flag.** In jq's regex (Oniguruma), `m` means dot-matches-newline, NOT multiline anchoring — `^` only matches the very start of the body. The `@claude` GitHub Action buries its verdict below a `**Claude finished …**` header and a `---`, so an anchored-at-start pattern never matches. (The bot also *edits* its placeholder comment in place rather than posting a new one; `createdAt` stays at placeholder time, which is still after your trigger, so the timestamp filter is fine.)
+- **Pipe through `grep -q true`.** `gh --jq` prints `true`/`false` but exits 0 either way, so a bare `until gh …; do` would exit the loop on the first poll regardless of the value.
+
+Run this as a background until-loop (e.g. via the Monitor tool) so you're notified on completion instead of blocking synchronously. Cap the wait at roughly 30 minutes; if no review appears in that window, stop and report to the user that the `@claude` bot didn't respond — don't loop indefinitely on a bot that may be down or misconfigured. Before trusting a freshly armed monitor, sanity-check its condition once inline against the live PR — if a review is already present it must print `true`.
+
+### 3. Check the review against the stop conditions
+
+Fetch the latest review and classify it exactly like fix-pr-review steps 1–2: verdict (`LGTM` / `Needs Updates`) and which sections are present (`Needs Fixing`, `Requires Human Review`, `Recommended Optional`, `Create Follow-up Issue`).
+
+Evaluate in this order:
+
+1. **Clean pass — stop, success.** Verdict is `LGTM` and **no sections at all** — nothing under Recommended Optional or Create Follow-up Issue either. Nothing left to fix, at any `review_count`. Go to step 5.
+2. **Past the cap and it's an LGTM — stop, first one wins.** `review_count > 5` **and** verdict is `LGTM` (even with Recommended Optional / Create Follow-up Issue items still listed). Once the loop has run more than 5 cycles, the first LGTM it sees ends it — don't spend a 6th+ fix-pr-review cycle chasing non-blocking findings. Go to step 5.
+3. **Otherwise — keep going.** Verdict is `Needs Updates` (at any `review_count` — there is no cycle count that alone stops a `Needs Updates` PR; only an LGTM does, per rules 1–2), or verdict is `LGTM` with findings still listed and `review_count <= 5`. Continue to step 4.
+
+### 4. Resolve the review and loop
+
+Invoke the `fix-pr-review` skill for the PR (Skill tool, `skill: fix-pr-review`). It re-validates every finding against the code, fixes what's real, implements the judgment calls and optional improvements to the best-solution standard, commits, pushes, posts the disposition comment, and triggers a fresh `@claude` review itself (routed to Sonnet when it addressed only non-blocking items, otherwise to the repo default, per fix-pr-review step 7).
+
+fix-pr-review also picks its own working model dynamically (its step 3.5): it always validates the findings inline on the session model, then tiers implementation by the complexity of the most complex surviving fix — open judgment calls and safety-class findings stay inline, any non-trivial fix routes the set to an Opus subagent, and all-mechanical work goes to a Sonnet subagent. It decides from the validated findings itself, so don't override its choice — just record which model each cycle reported running on, for the step 5 report.
+
+Increment `review_count`, record the new trigger timestamp from that comment, and go back to step 2.
+
+### 5. Report
+
+Stop the loop and report the terminal state — don't claim blanket success:
+
+| Terminal state | Report as |
+|---|---|
+| Clean `LGTM`, no findings, at or before `review_count` 5 | **Done.** PR is approved with nothing outstanding. |
+| `review_count > 5` and an `LGTM` (with non-blocking items remaining) ended the loop | **Done, with leftovers.** PR is approved; note the remaining optional/follow-up items that were left unaddressed once the loop passed 5 cycles. |
+| Bot never responded within the wait window | **Escalate.** Report that the PR is pushed but review never landed; the user should check the `@claude` GitHub Action / bot status. |
+| PR was already `merged`/`closed` when the skill started | **Nothing to drive.** Report the state; zero review cycles ran. |
+
+There is no "stuck on `Needs Updates` past the cap" case to report — per step 3, `Needs Updates` never stops the loop by cycle count alone; it keeps calling fix-pr-review until an LGTM appears (or the bot stops responding, the row above).
+
+In every case, give: PR URL, number of review cycles run, final verdict, which model each fix cycle ran on (per fix-pr-review's findings-based selection), and (if escalating) exactly what's left.
+
+**Cap the report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase or its internals.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|---|---|
+| `review_count > 5` and the latest verdict is `LGTM` | Stop right there — don't invoke fix-pr-review again just because non-blocking findings remain; report per step 5 |
+| `review_count > 5` and the latest verdict is still `Needs Updates` | Keep going — invoke fix-pr-review and loop again; the cap only changes what counts as "done" on an LGTM, it never force-stops a `Needs Updates` PR |
+| Latest "review" is your own prior fix-pr-review disposition comment or an `@claude review` trigger comment, not an actual review | Skip it — keep waiting/polling for the real next review, same rule as fix-pr-review step 1 |
+| Review bot hasn't responded after ~30 minutes | Stop waiting; report that review didn't land rather than polling forever |
+| Tempted to treat "LGTM with Recommended Optional items" as terminal at `review_count <= 5` | It isn't — below the cap, LGTM-with-findings still goes through fix-pr-review; only past the cap does the first LGTM end it regardless of findings |
+| PR gets closed or merged mid-loop (e.g. by the user) | Stop immediately; don't keep pushing fixes to a closed/merged PR |
+| PR already has unaddressed feedback when the skill starts | Don't trigger a redundant `@claude review` — step 1 evaluates existing feedback first and only triggers when none exists |
+
+## Common Mistakes
+
+- **Treating any LGTM at or below `review_count` 5 as terminal.** Below the cap, only a *bare* LGTM (no sections) stops the loop; an LGTM with leftover optional/follow-up findings still goes through another fix-pr-review cycle.
+- **Hard-stopping a `Needs Updates` PR once `review_count` passes 5.** There's no such rule — the cap only lowers the bar for what counts as "done" once an LGTM shows up; it never stops the loop on its own.
+- **Losing count across cycles.** Track `review_count` explicitly — it's what distinguishes "full fix cycle" from "first-LGTM-wins" behavior.
+- **Polling synchronously forever.** Use an until-loop with a timeout so a non-responding bot doesn't hang the whole run.
+- **Re-triggering review on top of fix-pr-review's own trigger.** fix-pr-review already posts its own re-review trigger as a separate comment (its step 7) — don't add a second one here.
+- **Triggering `@claude review` when feedback is already sitting on the PR.** Check for existing unaddressed feedback in step 1 first; a redundant trigger just delays convergence.

package/skills/new-issue/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: new-issue
+description: Use when the user says "new issue", "create an issue", "file an issue", "/new-issue", or asks to turn a bug, idea, or discussion into a GitHub issue. Takes an optional description of what the issue should cover; with no input, derives the issue from what was discussed in the current conversation. Verifies claims against the code before filing and produces a complete, complexity-scored issue — never a stub.
+---
+
+# new-issue
+
+Create a fully-specified GitHub issue from the user's prompt — or, when nothing is prompted, from what was just discussed in the conversation. The deliverable is a filed issue that someone (human or agent) could pick up cold and implement correctly: concrete problem statement, goal, approach, acceptance criteria, complexity score, attribution footer. **Never file a placeholder, stub, or empty-bodied issue — no exceptions.**
+
+**Spec the absolute-best solution — full stop.** When the issue proposes an approach, derive it from first principles as if cost, compute, time, effort, manpower, token spend, code volume, and blast radius were unlimited — none of these are factors and none may narrow the option space. The only constraints that override "best" are correctness and safety (money, data integrity, security, auto-protective mechanisms — safety-class gaps are never acceptable, however "low-risk"). Don't spec the tidier/less-code design when it leaves a correctness or safety gap, and don't scope the issue down to what seems cheap to build.
+
+## Input
+
+The user provides one of:
+- A description of the bug/feature/task to file — use it as the source, but still ground it in code (below).
+- **Nothing** — derive the issue from the current conversation: the bug just diagnosed, the design just discussed, the follow-up just named. If the conversation contains several distinct candidates, file the one the discussion converged on; name the others and offer to file them (each fully specified) rather than bundling.
+- Optionally `owner/repo` or a repo path when the issue belongs somewhere other than the current checkout (`gh issue create -R owner/repo`).
+
+## Steps
+
+### 1. Establish the repo and check for duplicates
+
+Confirm which repo the issue belongs to (`gh repo view --json nameWithOwner`). Then search for an existing issue or PR already covering it — filing a duplicate wastes a cycle:
+
+```bash
+gh issue list --state open --search "<keywords>"
+gh pr list --state open --search "<keywords>"
+```
+
+A genuine hit → stop and surface it (offer to update/comment on the existing issue instead). A passing mention doesn't count.
+
+### 2. Ground every claim in the code — before writing a word
+
+The issue's factual claims about *current* behavior are claims, not notes — the same standard validate-issue holds authors to applies to you as the author. For each behavior the issue will assert, trace the code path and keep the `file:line`; a claim you can't trace is phrased as unverified ("appears to…", "needs confirmation"), never stated as fact. If the issue came from this conversation, don't transcribe from memory — re-check the load-bearing citations against the actual files; conversation recollection goes stale exactly like an author's prose does.
+
+If the working tree is on a divergent or stale branch, trace against `origin/<default>` (`git show "origin/$DEFAULT":<path>`) so citations match what an implementer will check out.
+
+### 3. Design the approach (non-trivial issues)
+
+For anything beyond a localized bugfix, spec the approach the way validate-issue's architecture pass would judge it — so the issue passes its own future validation:
+
+- **Placement and ownership** — which layer/component owns the change; for shared state name the owner, lifetime, medium, population timing, consumer contract, and failure policy.
+- **Touch-set** — grep the affected symbols and name *every* site that must change (read/write/default/validate/serialize), not just the obvious one.
+- **Conventions** — match the repo's existing patterns (`CLAUDE.md`, guardrails, existing helpers) over new infrastructure; respect documented invariants (single-writer, fail-closed, "X never into Y").
+- **Best over cheap** — per the principle above: if the correct design is bigger than the convenient one, spec the correct design and let the complexity score say so.
+
+Include **acceptance criteria** an implementer can verify: observable behavior, tests that must exist (regression test for a bug, red → green), parity surfaces that must match.
+
+### 4. Score complexity
+
+Score the work to implement the fix **correctly, including tests** — five axes 0–4 (Scope, Coupling, Risk, Uncertainty, Verification), sum ×5 for a 0–100 base, risk floor: Risk 4 → ≥60, Risk 3 → ≥45. Derive the axes from the concrete touch-set in step 3, not vibes; count the surface that hides from the diff (tests, parity/offline paths, migrations, docs). This is complexity, **not** a time or effort estimate — never put durations in the issue.
+
+### 5. Scope check — one issue or several?
+
+If the deliverables are separable — parts that each land in their own PR, pass their own tests, and deliver value alone — don't bundle: file the core issue and tell the user which parts warrant their own issues (each fully specified before filing, or tracked as a checklist in the parent until ready — never stubs).
+
+### 6. Compose and file
+
+Title: `[C<score>] <title>` — the title is a clear, plain-language sentence understandable to an average 18-year-old (ELI18) — it states the bug or deliverable precisely (component + behavior) without unexplained jargon, no vague "improve X".
+
+Body structure:
+
+```
+**Complexity: <score>/100** — scope: <…>; risk: <…>; uncertainty: <…>
+
+## Problem
+<Current behavior, grounded with file:line citations from step 2. What's wrong or missing and why it matters.>
+
+## Goal
+<The outcome in plain language — what's true after this lands.>
+
+## Approach
+<The optimal design from step 3: placement, touch-set, key decisions. Explicit that correctness/safety outrank diff size.>
+
+## Acceptance criteria
+- <observable behavior / test that must pass>
+- <…>
+
+---
+Created with LLM: <current model> | <effort> | Harness: <harness>
+```
+
+The complexity rationale is the **first line** of the body and matches the title prefix. The footer is the final lines, preceded by `---` on its own line — **Created** verb, `<effort>` one of `medium`/`high`/`xhigh` (default `high`, never low), `<harness>` = `Claude Code` for an interactive session. No `Co-authored-by`. **Project precedence:** a repo `CLAUDE.md` that defines its own issue/footer format overrides this default.
+
+File it:
+
+```bash
+gh issue create --title "[C<score>] <title>" --body-file <body-file>
+```
+
+Add `--label`/`--assignee` only when the repo visibly uses them (`gh label list`) and the fit is unambiguous.
+
+### 7. Report
+
+Terse: issue URL, number, one-line summary of what it covers, complexity score, and any candidate follow-ups you did **not** file (with why). Offer "validate issue" / "work on issue" as next steps in one line.
+
+## Guardrails
+
+| Situation | Action |
+|-----------|--------|
+| Tempted to file with a thin body "to capture it quickly" | Don't — every issue is complete at creation; if it isn't ready to spec, tell the user and track it in notes/parent instead |
+| No prompt and the conversation discussed several things | File the converged one; name the rest, don't bundle |
+| A claim about current behavior you haven't traced | Trace it or phrase it as unverified — never state a guess as fact |
+| Issue derived from conversation memory | Re-verify load-bearing file:line citations against the actual code before filing |
+| An existing open issue/PR already covers it | Stop; surface it and offer to update/comment instead |
+| The cheap design and the correct design diverge | Spec the correct one; cost, effort, and blast radius are not factors — only correctness and safety constrain |
+| Touches money / data integrity / security / auto-protective logic | Spec the safest correct design from first principles; surface the risk in the body and Risk axis |
+| Tempted to include a time/effort estimate | Don't — complexity score only, described via scope/risk/uncertainty |
+| Repo has its own issue template or `CLAUDE.md` issue format | Follow the repo's format; it overrides this default |

package/skills/new-issue-loop/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: new-issue-loop
+description: Use when the user asks to file a GitHub issue and then autonomously drive it all the way to a reviewed PR in one shot — "new-issue-loop", "create the issue and run it to completion", "file this and fully automate it". Runs new-issue to create a fully-specified issue, then hands the new issue number to validate-issue-loop (validate → update → work-on-issue-loop) — stopping instead when new-issue finds a duplicate or the discussion hasn't converged on one issue.
+---
+
+# new-issue-loop
+
+Chain new-issue → validate-issue-loop into one autonomous run, so a bug/idea/discussion goes from "described" to "filed issue with a PR through N rounds of review" without a human in the loop between steps. This is new-issue's normal interactive handoff (`Offer "validate issue" / "work on issue"`) made unattended: the loop takes the issue it just filed and feeds it straight into the validate-and-implement pipeline.
+
+**Do not skip filing a complete issue.** The downstream loop validates and implements *the issue text* — a thin or unverified body propagates straight into the PR. Every step of new-issue still runs (grounding, approach design, complexity score); only the "offer next steps and wait" step is replaced by the handoff.
+
+## Input
+
+Same as new-issue: an optional description of what the issue should cover; with no input, derive it from the current conversation. Optionally `owner/repo` when the issue belongs elsewhere.
+
+## Steps
+
+### 1. Run new-issue
+
+Invoke the `new-issue` skill (Skill tool, `skill: new-issue`) with the user's description (or conversation-derived scope). Let it run its full process — duplicate check, code grounding, approach, complexity score, filing. Capture the created issue number from its report.
+
+### 2. Stop gate — cases the loop can't safely continue
+
+| Condition | Action |
+|---|---|
+| new-issue found an existing open issue/PR already covering it (no issue filed) | **STOP.** Report the duplicate and new-issue's offer to update/comment instead — whether to merge scopes is a human call. |
+| The conversation held several distinct candidates | If one clearly converged, file it and **continue the chain with it**; the unfiled candidates go in the final report. If none clearly converged, **STOP** — report the candidates and ask which to file. Never bundle, never auto-file the extras. |
+| new-issue split the work and named unfiled follow-ups | Continue with the **core issue only**; relay the unfiled follow-ups in the final report. |
+
+Otherwise (one issue filed cleanly), continue.
+
+### 3. Hand off to validate-issue-loop
+
+Invoke the `validate-issue-loop` skill (Skill tool, `skill: validate-issue-loop`) with the issue from step 1 passed explicitly — don't let it default to "latest open issue" and risk racing another just-filed issue. If new-issue filed to a repo other than the current checkout (`-R owner/repo`), pass the full `owner/repo#N` reference, not the bare number — a bare number resolves against the current repo and would target the wrong issue. Its own scope gate (too large / infeasible / already-addressed) still applies and may stop the run; that's the designed behavior, not a failure.
+
+Validating an issue this same session just wrote is not redundant: validate-issue re-traces the claims against the code independently, catching anything the filing pass got wrong.
+
+### 4. Report
+
+Relay validate-issue-loop's final summary (PR URL, review cycles, verdict), prefixed with one line covering the front of the chain: issue number/URL filed, complexity score, and any unfiled follow-ups from step 2.
+
+**Cap the whole report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|---|---|
+| Tempted to skip new-issue's grounding/duplicate check to get to implementation faster | Never — a fabricated or duplicate issue poisons the whole chain |
+| new-issue stopped on a duplicate | Stop and report per step 2 — don't file anyway |
+| Tempted to hand off without an explicit issue reference | Always pass the issue from step 1 — `owner/repo#N` if filed cross-repo — "latest issue" can race |
+| validate-issue-loop's scope gate stops the run | Report its disposition faithfully — don't override and implement anyway |

package/skills/sync-docs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: sync-docs
+description: Use when the user asks to sync, update, or refresh CLAUDE.md, AGENTS.md, SKILL.md, and README.md to reflect recent commits or PRs. Triggers on phrases like "sync docs", "update CLAUDE.md", "update AGENTS.md", "update SKILL.md", "update README", "reflect recent changes", or "document the recent PRs".
+---
+
+# sync-docs
+
+**This skill is a dispatch shim. Do not perform the work yourself.**
+
+Immediately invoke the `sync-docs-runner` subagent via the Agent tool, which runs on Opus and contains the full sync-docs workflow.
+
+## Required invocation
+
+Call the Agent tool with:
+
+- `subagent_type`: `sync-docs-runner`
+- `description`: `Sync docs to recent commits`
+- `prompt`: Pass through the user's request verbatim, plus any context the user already provided in this session (target branch, last-sync SHA, specific files to focus on, etc.). The agent has its own copy of the workflow — do not paste workflow steps into the prompt. Include only the inputs it needs.
+- `model`: Omit by default — the agent runs on Opus via its pinned frontmatter. **Override only if the user explicitly names a different LLM** when invoking the skill (e.g. "sync docs with sonnet", "/sync-docs use haiku"). Map the request to the matching `model` value (`opus`, `sonnet`, or `haiku`) and pass it; the Agent tool's `model` parameter takes precedence over the agent's frontmatter. Do not infer an override from anything other than an explicit model name.
+
+After the agent returns, relay its summary to the user. Do not re-execute its work.
+
+## Why this exists
+
+The full sync-docs workflow lives in `~/.claude/agents/sync-docs-runner.md` with `model: opus` pinned in frontmatter. Routing through the agent keeps doc-sync runs on Opus by default — but an explicit user LLM choice overrides it via the Agent tool's `model` parameter.

package/skills/sync-docs-release/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: sync-docs-release
+description: Use when the user wants to sync docs and then cut a release in one shot. Combines sync-docs → commit → create-release in sequence. Triggers on phrases like "sync docs and release", "sync and cut a release", "update docs and publish a release".
+---
+
+# sync-docs-release
+
+Runs three operations in strict sequence. Do not skip steps or reorder them.
+
+## Step 1 — Sync docs
+
+Invoke the `sync-docs-runner` subagent via the Agent tool:
+
+- `subagent_type`: `sync-docs-runner`
+- `description`: `Sync docs to recent commits`
+- `prompt`: Pass through the user's request verbatim plus any session context (target branch, last-sync SHA, specific files, etc.). Do not paste workflow steps into the prompt.
+- `model`: Omit by default. Override only if the user explicitly names a different LLM.
+
+Wait for the agent to return. Relay its summary to the user before proceeding.
+
+## Step 2 — Commit the doc changes
+
+After sync-docs completes, commit any doc changes it produced using the Haiku model. Spawn an Agent with `model: haiku` and the following prompt:
+
+> Create a git commit for the doc changes just produced by sync-docs. Steps:
+> 1. Run `git status` and `git diff` to see all changes.
+> 2. Run `git log --oneline -10` to understand the commit message style used in this repo.
+> 3. Stage only documentation files changed by sync-docs (CLAUDE.md, AGENTS.md, SKILL.md, README.md, and any other .md files that were modified — never stage .env, secrets, or unrelated files).
+> 4. If there is nothing staged after step 3 (nothing changed), skip the commit and report "no doc changes to commit".
+> 5. Otherwise, draft a concise commit message focused on the "why" and create the commit: `git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"`.
+> 6. Run `git status` to verify.
+> Do not push.
+
+Wait for the agent to return. Relay its result (commit SHA or "no changes") to the user before proceeding.
+
+## Step 3 — Create a release
+
+Invoke the `create-release-runner` subagent via the Agent tool:
+
+- `subagent_type`: `create-release-runner`
+- `description`: `Cut and publish a release`
+- `prompt`: Pass through the user's original request verbatim plus any context they provided (target version or bump type, release-notes specifics, etc.). Do not paste workflow steps.
+- `model`: Omit by default. Override only if the user explicitly names a different LLM.
+
+After the agent returns, relay its summary and the release URL to the user.