@olegkoval/agent-skills 1.23.0 → 1.25.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -32,6 +32,7 @@
     "./packages/software-development/macos-menubar-app",
     "./packages/software-development/skill-budget-audit",
     "./packages/software-development/crash-course",
+    "./packages/software-development/pr-finalize",
     "./packages/software-development/qodoloop",
     "./packages/wearables/garmin-watchface",
     "./packages/software-development/coderabbitloop",

package/.cursor-plugin/index.json

@@ -106,6 +106,11 @@
       "source": "./packages/software-development/crash-course/adapters/cursor",
       "description": "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes."
     },
+    {
+      "name": "olko:pr-finalize",
+      "source": "./packages/software-development/pr-finalize/adapters/cursor",
+      "description": "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+    },
     {
       "name": "olko:qodoloop",
       "source": "./packages/software-development/qodoloop/adapters/cursor",

package/.grok-plugin/index.json

@@ -116,6 +116,11 @@
       "source": "./packages/software-development/crash-course/adapters/grok",
       "description": "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes."
     },
+    {
+      "name": "olko:pr-finalize",
+      "source": "./packages/software-development/pr-finalize/adapters/grok",
+      "description": "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+    },
     {
       "name": "olko:qodoloop",
       "source": "./packages/software-development/qodoloop/adapters/grok",

package/.kiro/steering/garmin-watchface.md

@@ -22,6 +22,7 @@ looked like success first.
 | `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
 | `references/devices.md` | Adding device support, launcher icons, API levels |
 | `references/store.md` | Publishing, listing copy, IP questions |
+| `references/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
 
 ## Tools
 
@@ -34,8 +35,14 @@ Run these rather than reinventing them. All are standalone.
 <skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
 <skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
 <skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+<skill-dir>/scripts/ciq-release       # pre-submission check: package, screenshots, icon, keys, copy
 ```
 
+`<skill-dir>/scripts/ciq-release` is what you run before opening the store
+portal. Every check in it is something otherwise discovered halfway through the
+submission form -- a stale screenshot set, an icon still copied from the last
+project, or copy containing a character the description validator rejects.
+
 `<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
 a window: without a frontmost check it silently photographs whatever is on top,
 and the window moves between simulator restarts. Both failure modes produce a

package/.kiro/steering/pr-finalize.md

@@ -0,0 +1,140 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+---
+
+# PR Finalize
+
+One PR, taken all the way to merge-ready. The job is not "make the bots stop talking" — it is **land the change in a state a careful reviewer would sign off on**, with evidence for every claim.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): do everything except the final push. Use when the repo auto-merges and the user wants to eyeball first.
+
+## Non-negotiables
+
+These are the failure modes this skill exists to prevent. Violating one makes the whole run worthless:
+
+- **Never report a gate as passing without having run it.** Paste the real output. "Tests should pass" is not a result.
+- **Never resolve or claim-fix a finding you didn't actually fix.** Blocked is an honest outcome; a false "done" is not.
+- **Never `git add -A`.** Stage only the files your fixes touched. Start from a clean tree so that's safe.
+- **Never invent test coverage.** If the change has no browser-reachable surface, say so explicitly and name the suite that *is* the real gate. Do not add a hollow E2E test to look thorough.
+- **A green CI badge is not proof.** Many repos split their required check from the full suite (browser-free half only, etc.). Find out what the required check actually runs.
+
+## Instructions
+
+### 1. Establish the ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup,url
+```
+
+Record four things before touching code:
+
+- **`mergeable`** — `CONFLICTING` means step 2 is mandatory.
+- **Which checks are failing**, and for each, whether it is *required*. Check branch protection (`gh api repos/{owner}/{repo}/branches/<base>/protection`) rather than assuming — a red optional job (a flaky bot-review runner, a nightly) is not a blocker, and burning the run waiting on one is a classic waste.
+- **Whether the repo auto-merges.** Look for a shepherd/automerge workflow in `.github/workflows/` and read its *gating conditions* (required labels, required checks). If pushing could trigger an immediate merge, decide deliberately: either satisfy the review sweep first, or tell the user before you push. Never let an auto-merge race a review you were asked to complete.
+- **Whether a bot review actually ran.** A `SUCCESS` status from a review bot can still mean "rate-limited, never reviewed" — read its comment body, not just the check state.
+
+### 2. Rebase onto the base branch
+
+Require a clean tree first (`git status --porcelain` empty), then:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by **understanding both sides**, not by picking one. Read the base-side commit that introduced the conflicting hunk (`git log -1 --format=%s <base> -- <file>`, then the diff) — a conflict usually means main changed an invariant your branch is unaware of, and blindly keeping "your" side silently reverts it. State in the PR comment which invariant you preserved and why.
+
+After resolving, re-run the tests before continuing — a rebase that compiles is not a rebase that works.
+
+### 3. Sweep every review source
+
+Collect findings from all of these; do not stop at the first:
+
+```bash
+# inline review threads (all bots + humans), with resolution state
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+# rollup issue comments (where CodeRabbit/Qodo post summaries and rate-limit notices)
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+# formal reviews
+gh pr view <PR> --json reviews
+```
+
+**Delegate to the dedicated loop skill when one exists** rather than reimplementing its bot's protocol — `qodoloop` for Qodo, `coderabbitloop` for CodeRabbit, `greploop` for Greptile. Each already encodes that bot's posting shape, its ready-made per-finding fix prompt, and its real terminal states. Use this skill's own sweep for human comments and for bots without a dedicated loop.
+
+Triage every finding into exactly one bucket:
+
+| Bucket | Action |
+|---|---|
+| **Real defect** | Fix it. This is the point of the exercise. |
+| **Legitimate improvement** | Fix it if it's in scope for this PR. |
+| **False positive** | Reply explaining *specifically* why the bot is wrong. Do not resolve silently. |
+| **Needs a human call** | Reply, leave open, surface in the final report. |
+
+Bot findings are suggestions from something that has not run the code. A "🐞 Bug" label is a hypothesis — verify it against the actual source before fixing, and against the actual behavior before dismissing.
+
+### 4. Close the coverage gap
+
+Ask, for the change as a whole, what would catch a regression here — then check whether the PR actually has it.
+
+- **Unit / integration tests:** does every new branch have a test that fails if you invert it? Bots frequently and correctly flag helper functions exercised only *indirectly* through a caller. A direct test per branch is cheap and is usually the right response.
+- **Browser / E2E tests:** determine whether the repo supports them (`playwright.config.*`, `cypress.config.*`, a `test:e2e` script) **and** whether this change has any surface they can reach. Then do one of exactly two things:
+  - it has a reachable surface → add or extend the E2E spec;
+  - it does not → **say so explicitly in the PR comment**, name why (e.g. "this is entirely inside a Durable Object alarm loop; the E2E harness only serves static assets"), and name the suite that is the real gate.
+
+  Silence here reads as an oversight. An explicit "not applicable, because X" reads as diligence — and is checkable.
+
+### 5. Run the real gates
+
+Discover them from the repo (`Makefile`, `package.json` scripts, CI workflow) — do not guess target names. Run, at minimum, the equivalents of:
+
+```bash
+<lint>        # e.g. make lint / npm run lint
+<format>      # check mode first; only write if it reports drift
+<tests>       # the suite covering the changed package
+```
+
+Capture exit codes, not just output. Repo-specific traps worth checking for before you burn a cycle: linters whose cache replays findings from deleted sibling worktrees, formatters whose local toolchain version outruns CI's (churning unrelated files), and test runners that hang when two runs overlap.
+
+If a gate fails, fix it. Do not push red.
+
+### 6. Push and explain
+
+Stage only the files you touched, commit, and push (`--force-with-lease` after a rebase — never bare `--force`).
+
+Then post **one** PR comment that a reviewer can audit without re-reading the diff:
+
+- what the rebase conflict was and which side won, with the reason;
+- each finding, and what you did about it (including the ones you rejected, with the argument);
+- the coverage decision from step 4, including the explicit not-applicable if that's the answer;
+- **verbatim** gate output — real numbers (`# pass 480 / # fail 0`, `0 issues.`), not adjectives.
+
+Re-trigger any bot that never actually reviewed (e.g. `@coderabbitai review`) so the PR gets the pass it was owed.
+
+### 7. Verify and report
+
+Re-read the PR state after the push — confirm `mergeable` flipped, checks went green, and clear now-stale labels (`needs-rebase`, etc.). Poll re-triggered bots for their new pass and handle anything it raises.
+
+```text
+PR #965 finalized.
+  Rebase:      1 conflict resolved (kept main's #834 D1-first ordering)
+  Findings:    2 addressed, 0 rejected, 0 blocked
+  Coverage:    +5 unit tests; E2E not applicable (no browser surface) — stated on the PR
+  Gates:       tests 480/480, lint 0 issues, format clean
+  State:       MERGEABLE, checks green
+  Needs human: none
+```
+
+If anything is left, say precisely what and why — an honest "blocked on X" is the deliverable when X is genuinely a human call.
+
+## Related skills
+
+- `qodoloop` — full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- `coderabbitloop` — full CodeRabbit protocol.
+- `greploop` — drives a PR to a 5/5 Greptile confidence score.
+- `ci-fix-loop` — when the blocker is a failing pipeline rather than review feedback.

package/.windsurf/rules/garmin-watchface.md

@@ -21,6 +21,7 @@ looked like success first.
 | `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
 | `references/devices.md` | Adding device support, launcher icons, API levels |
 | `references/store.md` | Publishing, listing copy, IP questions |
+| `references/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
 
 ## Tools
 
@@ -33,8 +34,14 @@ Run these rather than reinventing them. All are standalone.
 <skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
 <skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
 <skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+<skill-dir>/scripts/ciq-release       # pre-submission check: package, screenshots, icon, keys, copy
 ```
 
+`<skill-dir>/scripts/ciq-release` is what you run before opening the store
+portal. Every check in it is something otherwise discovered halfway through the
+submission form -- a stale screenshot set, an icon still copied from the last
+project, or copy containing a character the description validator rejects.
+
 `<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
 a window: without a frontmost check it silently photographs whatever is on top,
 and the window moves between simulator restarts. Both failure modes produce a

package/.windsurf/rules/pr-finalize.md

@@ -0,0 +1,139 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+---
+
+# PR Finalize
+
+One PR, taken all the way to merge-ready. The job is not "make the bots stop talking" — it is **land the change in a state a careful reviewer would sign off on**, with evidence for every claim.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): do everything except the final push. Use when the repo auto-merges and the user wants to eyeball first.
+
+## Non-negotiables
+
+These are the failure modes this skill exists to prevent. Violating one makes the whole run worthless:
+
+- **Never report a gate as passing without having run it.** Paste the real output. "Tests should pass" is not a result.
+- **Never resolve or claim-fix a finding you didn't actually fix.** Blocked is an honest outcome; a false "done" is not.
+- **Never `git add -A`.** Stage only the files your fixes touched. Start from a clean tree so that's safe.
+- **Never invent test coverage.** If the change has no browser-reachable surface, say so explicitly and name the suite that *is* the real gate. Do not add a hollow E2E test to look thorough.
+- **A green CI badge is not proof.** Many repos split their required check from the full suite (browser-free half only, etc.). Find out what the required check actually runs.
+
+## Instructions
+
+### 1. Establish the ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup,url
+```
+
+Record four things before touching code:
+
+- **`mergeable`** — `CONFLICTING` means step 2 is mandatory.
+- **Which checks are failing**, and for each, whether it is *required*. Check branch protection (`gh api repos/{owner}/{repo}/branches/<base>/protection`) rather than assuming — a red optional job (a flaky bot-review runner, a nightly) is not a blocker, and burning the run waiting on one is a classic waste.
+- **Whether the repo auto-merges.** Look for a shepherd/automerge workflow in `.github/workflows/` and read its *gating conditions* (required labels, required checks). If pushing could trigger an immediate merge, decide deliberately: either satisfy the review sweep first, or tell the user before you push. Never let an auto-merge race a review you were asked to complete.
+- **Whether a bot review actually ran.** A `SUCCESS` status from a review bot can still mean "rate-limited, never reviewed" — read its comment body, not just the check state.
+
+### 2. Rebase onto the base branch
+
+Require a clean tree first (`git status --porcelain` empty), then:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by **understanding both sides**, not by picking one. Read the base-side commit that introduced the conflicting hunk (`git log -1 --format=%s <base> -- <file>`, then the diff) — a conflict usually means main changed an invariant your branch is unaware of, and blindly keeping "your" side silently reverts it. State in the PR comment which invariant you preserved and why.
+
+After resolving, re-run the tests before continuing — a rebase that compiles is not a rebase that works.
+
+### 3. Sweep every review source
+
+Collect findings from all of these; do not stop at the first:
+
+```bash
+# inline review threads (all bots + humans), with resolution state
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+# rollup issue comments (where CodeRabbit/Qodo post summaries and rate-limit notices)
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+# formal reviews
+gh pr view <PR> --json reviews
+```
+
+**Delegate to the dedicated loop skill when one exists** rather than reimplementing its bot's protocol — `qodoloop` for Qodo, `coderabbitloop` for CodeRabbit, `greploop` for Greptile. Each already encodes that bot's posting shape, its ready-made per-finding fix prompt, and its real terminal states. Use this skill's own sweep for human comments and for bots without a dedicated loop.
+
+Triage every finding into exactly one bucket:
+
+| Bucket | Action |
+|---|---|
+| **Real defect** | Fix it. This is the point of the exercise. |
+| **Legitimate improvement** | Fix it if it's in scope for this PR. |
+| **False positive** | Reply explaining *specifically* why the bot is wrong. Do not resolve silently. |
+| **Needs a human call** | Reply, leave open, surface in the final report. |
+
+Bot findings are suggestions from something that has not run the code. A "🐞 Bug" label is a hypothesis — verify it against the actual source before fixing, and against the actual behavior before dismissing.
+
+### 4. Close the coverage gap
+
+Ask, for the change as a whole, what would catch a regression here — then check whether the PR actually has it.
+
+- **Unit / integration tests:** does every new branch have a test that fails if you invert it? Bots frequently and correctly flag helper functions exercised only *indirectly* through a caller. A direct test per branch is cheap and is usually the right response.
+- **Browser / E2E tests:** determine whether the repo supports them (`playwright.config.*`, `cypress.config.*`, a `test:e2e` script) **and** whether this change has any surface they can reach. Then do one of exactly two things:
+  - it has a reachable surface → add or extend the E2E spec;
+  - it does not → **say so explicitly in the PR comment**, name why (e.g. "this is entirely inside a Durable Object alarm loop; the E2E harness only serves static assets"), and name the suite that is the real gate.
+
+  Silence here reads as an oversight. An explicit "not applicable, because X" reads as diligence — and is checkable.
+
+### 5. Run the real gates
+
+Discover them from the repo (`Makefile`, `package.json` scripts, CI workflow) — do not guess target names. Run, at minimum, the equivalents of:
+
+```bash
+<lint>        # e.g. make lint / npm run lint
+<format>      # check mode first; only write if it reports drift
+<tests>       # the suite covering the changed package
+```
+
+Capture exit codes, not just output. Repo-specific traps worth checking for before you burn a cycle: linters whose cache replays findings from deleted sibling worktrees, formatters whose local toolchain version outruns CI's (churning unrelated files), and test runners that hang when two runs overlap.
+
+If a gate fails, fix it. Do not push red.
+
+### 6. Push and explain
+
+Stage only the files you touched, commit, and push (`--force-with-lease` after a rebase — never bare `--force`).
+
+Then post **one** PR comment that a reviewer can audit without re-reading the diff:
+
+- what the rebase conflict was and which side won, with the reason;
+- each finding, and what you did about it (including the ones you rejected, with the argument);
+- the coverage decision from step 4, including the explicit not-applicable if that's the answer;
+- **verbatim** gate output — real numbers (`# pass 480 / # fail 0`, `0 issues.`), not adjectives.
+
+Re-trigger any bot that never actually reviewed (e.g. `@coderabbitai review`) so the PR gets the pass it was owed.
+
+### 7. Verify and report
+
+Re-read the PR state after the push — confirm `mergeable` flipped, checks went green, and clear now-stale labels (`needs-rebase`, etc.). Poll re-triggered bots for their new pass and handle anything it raises.
+
+```text
+PR #965 finalized.
+  Rebase:      1 conflict resolved (kept main's #834 D1-first ordering)
+  Findings:    2 addressed, 0 rejected, 0 blocked
+  Coverage:    +5 unit tests; E2E not applicable (no browser surface) — stated on the PR
+  Gates:       tests 480/480, lint 0 issues, format clean
+  State:       MERGEABLE, checks green
+  Needs human: none
+```
+
+If anything is left, say precisely what and why — an honest "blocked on X" is the deliverable when X is genuinely a human call.
+
+## Related skills
+
+- `qodoloop` — full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- `coderabbitloop` — full CodeRabbit protocol.
+- `greploop` — drives a PR to a 5/5 Greptile confidence score.
+- `ci-fix-loop` — when the blocker is a failing pipeline rather than review feedback.

package/README.md

@@ -162,6 +162,7 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [open-source-publisher](packages/software-development/open-source-publisher/SKILL.md) | Prepares an open-source repository for public publishing with branding, CI/CD, and release hygiene | Releasing a private project publicly with proper GitHub Pages, README, and social preview |
 | [product-builder](packages/software-development/product-builder/SKILL.md) | Builds a full-stack web app or SaaS product from a user description using production-oriented defaults | Building a complete app, SaaS, dashboard, or product rather than a prototype |
 | [pr-description-writer](packages/software-development/pr-description-writer/SKILL.md) | Drafts and posts a GitHub PR title and body from git diff and commit history, respecting existing PR templates | Opening a PR after pushing a branch or wanting a structured PR description written automatically |
+| [pr-finalize](packages/software-development/pr-finalize/SKILL.md) | Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment, verifies unit and E2E coverage really exists, and runs the repo's own lint/format/test gates before pushing | Finalizing a PR, clearing all outstanding review comments, or getting a branch merge-ready in one pass |
 | [promptctl](packages/software-development/promptctl/SKILL.md) | Uses `promptctl` for reusable prompt templates, scoring, and workflow automation | A project needs prompt conventions, review, scoring, or reusable prompt workflows |
 | [qodoloop](packages/software-development/qodoloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved Qodo findings, reading each finding's own Agent Prompt, replying to the thread, and resolving it | Fully addressing a PR against Qodo's code review before merging |
 | [relay](packages/software-development/relay/SKILL.md) | Uses `claude-relay` to run long or rate-limit-prone tasks autonomously across subscription accounts | A task will outlive one session or hit rate limits partway through |

package/catalog/skills.json

@@ -399,7 +399,7 @@
       "lookupName": "olko:obsidian-pr-sync",
       "category": "software-development",
       "path": "packages/software-development/obsidian-pr-sync",
-      "description": "Fetch open GitHub PRs assigned to you or requesting your review, and write a grouped, age-sorted '## PRs to review' section into today's Obsidian daily note. Idempotent \u2014 re-running replaces the section.",
+      "description": "Fetch open GitHub PRs assigned to you or requesting your review, and write a grouped, age-sorted '## PRs to review' section into today's Obsidian daily note. Idempotent — re-running replaces the section.",
       "tags": [
         "github",
         "obsidian",
@@ -470,7 +470,7 @@
       "lookupName": "olko:macos-menubar-app",
       "category": "software-development",
       "path": "packages/software-development/macos-menubar-app",
-      "description": "Build a production-quality macOS menubar or notch app in SwiftUI \u2014 MenuBarExtra, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and App Store preparation.",
+      "description": "Build a production-quality macOS menubar or notch app in SwiftUI — MenuBarExtra, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and App Store preparation.",
       "tags": [
         "macos",
         "swiftui",
@@ -495,7 +495,7 @@
       "lookupName": "olko:skill-budget-audit",
       "category": "software-development",
       "path": "packages/software-development/skill-budget-audit",
-      "description": "Diagnose and fix Claude Code skill context budget overflow \u2014 identify heavy plugin bundles, remove domain-specific ones, and restore skill discoverability.",
+      "description": "Diagnose and fix Claude Code skill context budget overflow — identify heavy plugin bundles, remove domain-specific ones, and restore skill discoverability.",
       "tags": [
         "claude-code",
         "skills",
@@ -533,12 +533,36 @@
         "grok"
       ]
     },
+    {
+      "name": "pr-finalize",
+      "lookupName": "olko:pr-finalize",
+      "category": "software-development",
+      "path": "packages/software-development/pr-finalize",
+      "description": "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human.",
+      "tags": [
+        "code-review",
+        "pull-requests",
+        "github",
+        "testing",
+        "automation",
+        "agents"
+      ],
+      "adapters": [
+        "claude",
+        "codex",
+        "cursor",
+        "copilot",
+        "grok",
+        "windsurf",
+        "kiro"
+      ]
+    },
     {
       "name": "qodoloop",
       "lookupName": "olko:qodoloop",
       "category": "software-development",
       "path": "packages/software-development/qodoloop",
-      "description": "Iteratively drives a GitHub PR to zero unresolved Qodo findings \u2014 reads each finding's own Agent Prompt, applies the fix, replies to the thread, resolves it, pushes, and waits for Qodo's next pass.",
+      "description": "Iteratively drives a GitHub PR to zero unresolved Qodo findings — reads each finding's own Agent Prompt, applies the fix, replies to the thread, resolves it, pushes, and waits for Qodo's next pass.",
       "tags": [
         "code-review",
         "qodo",
@@ -586,7 +610,7 @@
       "lookupName": "olko:coderabbitloop",
       "category": "software-development",
       "path": "packages/software-development/coderabbitloop",
-      "description": "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings \u2014 reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit.",
+      "description": "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit.",
       "tags": [
         "code-review",
         "coderabbit",
@@ -678,7 +702,7 @@
       "lookupName": "olko:wikipedia-uk-editor",
       "category": "software-development",
       "path": "packages/software-development/wikipedia-uk-editor",
-      "description": "Draft policy-compliant Ukrainian Wikipedia edits \u2014 translate an English article into uk, expand or source an existing uk article, or fix a maintenance backlog item \u2014 and return ready-to-paste wikitext plus an edit summary.",
+      "description": "Draft policy-compliant Ukrainian Wikipedia edits — translate an English article into uk, expand or source an existing uk article, or fix a maintenance backlog item — and return ready-to-paste wikitext plus an edit summary.",
       "tags": [
         "wikipedia",
         "ukrainian",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/packages/software-development/pr-finalize/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: pr-finalize
+description: >
+  Drives a single GitHub PR from "open with loose ends" to genuinely ready-to-merge: rebases off the
+  base branch and resolves conflicts, sweeps every review bot (Qodo, CodeRabbit, Greptile) plus human
+  comments to zero unaddressed findings, verifies that unit AND browser/E2E coverage was actually
+  added for the change, runs the repo's real lint/format/test gates before pushing, and reports what
+  still needs a human. Use when the user gives a PR URL or number and says "finalize this PR",
+  "fix all outstanding comments", "address the review feedback and push", "get this PR merge-ready",
+  or asks to clear what Qodo/CodeRabbit/Greptile could still comment on.
+compatibility: Requires git and gh (GitHub CLI) authenticated. Review-bot sweeps only cover bots actually installed on the repo.
+metadata:
+  version: "1.0"
+allowed-tools: Bash(gh:*) Bash(git:*)
+---
+
+# PR Finalize
+
+One PR, taken all the way to merge-ready. The job is not "make the bots stop talking" — it is **land the change in a state a careful reviewer would sign off on**, with evidence for every claim.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): do everything except the final push. Use when the repo auto-merges and the user wants to eyeball first.
+
+## Non-negotiables
+
+These are the failure modes this skill exists to prevent. Violating one makes the whole run worthless:
+
+- **Never report a gate as passing without having run it.** Paste the real output. "Tests should pass" is not a result.
+- **Never resolve or claim-fix a finding you didn't actually fix.** Blocked is an honest outcome; a false "done" is not.
+- **Never `git add -A`.** Stage only the files your fixes touched. Start from a clean tree so that's safe.
+- **Never invent test coverage.** If the change has no browser-reachable surface, say so explicitly and name the suite that *is* the real gate. Do not add a hollow E2E test to look thorough.
+- **A green CI badge is not proof.** Many repos split their required check from the full suite (browser-free half only, etc.). Find out what the required check actually runs.
+
+## Instructions
+
+### 1. Establish the ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup,url
+```
+
+Record four things before touching code:
+
+- **`mergeable`** — `CONFLICTING` means step 2 is mandatory.
+- **Which checks are failing**, and for each, whether it is *required*. Check branch protection (`gh api repos/{owner}/{repo}/branches/<base>/protection`) rather than assuming — a red optional job (a flaky bot-review runner, a nightly) is not a blocker, and burning the run waiting on one is a classic waste.
+- **Whether the repo auto-merges.** Look for a shepherd/automerge workflow in `.github/workflows/` and read its *gating conditions* (required labels, required checks). If pushing could trigger an immediate merge, decide deliberately: either satisfy the review sweep first, or tell the user before you push. Never let an auto-merge race a review you were asked to complete.
+- **Whether a bot review actually ran.** A `SUCCESS` status from a review bot can still mean "rate-limited, never reviewed" — read its comment body, not just the check state.
+
+### 2. Rebase onto the base branch
+
+Require a clean tree first (`git status --porcelain` empty), then:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by **understanding both sides**, not by picking one. Read the base-side commit that introduced the conflicting hunk (`git log -1 --format=%s <base> -- <file>`, then the diff) — a conflict usually means main changed an invariant your branch is unaware of, and blindly keeping "your" side silently reverts it. State in the PR comment which invariant you preserved and why.
+
+After resolving, re-run the tests before continuing — a rebase that compiles is not a rebase that works.
+
+### 3. Sweep every review source
+
+Collect findings from all of these; do not stop at the first:
+
+```bash
+# inline review threads (all bots + humans), with resolution state
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+# rollup issue comments (where CodeRabbit/Qodo post summaries and rate-limit notices)
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+# formal reviews
+gh pr view <PR> --json reviews
+```
+
+**Delegate to the dedicated loop skill when one exists** rather than reimplementing its bot's protocol — `qodoloop` for Qodo, `coderabbitloop` for CodeRabbit, `greploop` for Greptile. Each already encodes that bot's posting shape, its ready-made per-finding fix prompt, and its real terminal states. Use this skill's own sweep for human comments and for bots without a dedicated loop.
+
+Triage every finding into exactly one bucket:
+
+| Bucket | Action |
+|---|---|
+| **Real defect** | Fix it. This is the point of the exercise. |
+| **Legitimate improvement** | Fix it if it's in scope for this PR. |
+| **False positive** | Reply explaining *specifically* why the bot is wrong. Do not resolve silently. |
+| **Needs a human call** | Reply, leave open, surface in the final report. |
+
+Bot findings are suggestions from something that has not run the code. A "🐞 Bug" label is a hypothesis — verify it against the actual source before fixing, and against the actual behavior before dismissing.
+
+### 4. Close the coverage gap
+
+Ask, for the change as a whole, what would catch a regression here — then check whether the PR actually has it.
+
+- **Unit / integration tests:** does every new branch have a test that fails if you invert it? Bots frequently and correctly flag helper functions exercised only *indirectly* through a caller. A direct test per branch is cheap and is usually the right response.
+- **Browser / E2E tests:** determine whether the repo supports them (`playwright.config.*`, `cypress.config.*`, a `test:e2e` script) **and** whether this change has any surface they can reach. Then do one of exactly two things:
+  - it has a reachable surface → add or extend the E2E spec;
+  - it does not → **say so explicitly in the PR comment**, name why (e.g. "this is entirely inside a Durable Object alarm loop; the E2E harness only serves static assets"), and name the suite that is the real gate.
+
+  Silence here reads as an oversight. An explicit "not applicable, because X" reads as diligence — and is checkable.
+
+### 5. Run the real gates
+
+Discover them from the repo (`Makefile`, `package.json` scripts, CI workflow) — do not guess target names. Run, at minimum, the equivalents of:
+
+```bash
+<lint>        # e.g. make lint / npm run lint
+<format>      # check mode first; only write if it reports drift
+<tests>       # the suite covering the changed package
+```
+
+Capture exit codes, not just output. Repo-specific traps worth checking for before you burn a cycle: linters whose cache replays findings from deleted sibling worktrees, formatters whose local toolchain version outruns CI's (churning unrelated files), and test runners that hang when two runs overlap.
+
+If a gate fails, fix it. Do not push red.
+
+### 6. Push and explain
+
+Stage only the files you touched, commit, and push (`--force-with-lease` after a rebase — never bare `--force`).
+
+Then post **one** PR comment that a reviewer can audit without re-reading the diff:
+
+- what the rebase conflict was and which side won, with the reason;
+- each finding, and what you did about it (including the ones you rejected, with the argument);
+- the coverage decision from step 4, including the explicit not-applicable if that's the answer;
+- **verbatim** gate output — real numbers (`# pass 480 / # fail 0`, `0 issues.`), not adjectives.
+
+Re-trigger any bot that never actually reviewed (e.g. `@coderabbitai review`) so the PR gets the pass it was owed.
+
+### 7. Verify and report
+
+Re-read the PR state after the push — confirm `mergeable` flipped, checks went green, and clear now-stale labels (`needs-rebase`, etc.). Poll re-triggered bots for their new pass and handle anything it raises.
+
+```text
+PR #965 finalized.
+  Rebase:      1 conflict resolved (kept main's #834 D1-first ordering)
+  Findings:    2 addressed, 0 rejected, 0 blocked
+  Coverage:    +5 unit tests; E2E not applicable (no browser surface) — stated on the PR
+  Gates:       tests 480/480, lint 0 issues, format clean
+  State:       MERGEABLE, checks green
+  Needs human: none
+```
+
+If anything is left, say precisely what and why — an honest "blocked on X" is the deliverable when X is genuinely a human call.
+
+## Related skills
+
+- `qodoloop` — full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- `coderabbitloop` — full CodeRabbit protocol.
+- `greploop` — drives a PR to a 5/5 Greptile confidence score.
+- `ci-fix-loop` — when the blocker is a failing pipeline rather than review feedback.

package/packages/software-development/pr-finalize/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-pr-finalize",
+  "description": "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human.",
+  "skills": "./skills"
+}