@olegkoval/agent-skills 1.25.0 → 1.27.0

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

@@ -0,0 +1,186 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Confirms a PR is genuinely merge-ready when the work is already believed done: re-checks every review-bot and human finding against the current code, separates stale comments from fixed ones, runs the repo's real lint and test gates, and reports the evidence rather than the assumption."
+---
+
+# PR Finalize Complete
+
+Confirm a PR is genuinely merge-ready -- even when all issues were already addressed -- by verifying the evidence, not trusting the assumption.
+
+## When to use this vs pr-finalize
+
+Use pr-finalize-complete when:
+- The branch owner says "it should be fixed already" and you need to confirm
+- Review bot findings may be stale (comments on old file paths, already-changed code)
+- You need to produce a verification report, not just drive fixes
+-- CI was green before but you need to re-confirm after a rebase
+
+Use pr-finalize when starting from scratch on an unaddressed PR.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): run all verification steps but skip the final push.
+
+## Non-negotiables
+
+- **Never claim a test passed without running it.** Report the actual exit code and test count.
+- **Never resolve a bot comment without checking whether the issue still exists in the current code.** Stale comments are common and silently resolving them is wrong.
+- **Never git add -A.** Start with a clean tree; stage only files your fixes actually touched.
+- **Stale comments are not done -- they are no longer applicable.** Distinguish the two in your report.
+
+## Instructions
+
+### 1. Establish ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,reviews,statusCheckRollup,url
+```
+
+Record before touching anything:
+
+- Is the branch **clean** (`git status --porcelain` empty)?
+- Is the branch **behind** `origin/<base>`?
+- What **checks are currently failing**, and which are required?
+- Which bots have actually posted (completed, not just triggered)?
+
+### 2. Rebase only if needed
+
+If mergeable is CONFLICTING or the branch is behind its base:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by understanding both sides. After resolving, run tests before continuing.
+If there is no conflict, skip this step -- do not rebase speculatively.
+
+### 3. Triage existing review comments
+
+Collect all findings:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+gh pr view <PR> --json reviews
+```
+
+For each unresolved finding, determine its actual current status in the code:
+
+| Status | Meaning | Action |
+|---|---|---|
+| Already fixed | Code the comment targets has been changed and issue no longer exists | Verify in code, reply confirming fix, resolve |
+| Stale | Comment targets a file/line/symbol that no longer exists | Verify, reply noting it is stale, resolve |
+| Still present | Issue exists in current code | Fix it, commit, reply, resolve |
+| False positive | Bot diagnosis is wrong for this codebase | Reply with specific rebuttal, leave open |
+| Needs human | Product/architecture decision required | Reply, leave open, surface in report |
+
+A comment is stale if the file it targets has been deleted or
+renamed, the function or class it names no longer exists, or the
+issue was flagged on an old line that has since been rewritten.
+
+Check for staleness before any fix attempt:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<PR>/files --paginate
+git diff origin/<base>...HEAD =- <file>
+```
+
+For stale comments: verify in current HEAD, reply explaining what changed, then resolve.
+
+### 4. Verify test coverage
+
+Find changed files:
+
+```bash
+gh pr view <PR> --json files -q '.files[].path'
+```
+
+For each changed module: check for a direct unit test file, confirm
+it exercises the specific code paths changed, and run it to verify
+impasses.
+
+If a module has no direct unit tests but is only indirectly covered,
+that is a real gap. Add direct tests unless the coverage gap is
+explicitly justified.
+
+### 5. Run the real gates
+
+Discover from the repo -- do not guess target names:
+
+```bash
+cat package.json | jq '.scripts'
+```
+
+Run in order: lint, format check, full test suite. Capture the actual
+exit code and output. Do not push if any required gate is red.
+
+### 6. Push and report
+
+If there were changes to commit:
+
+```bash
+git add <only files you touched>
+git commit -m "address review feedback and verify tests"
+git push --force-with-lease
+```
+
+Post one PR comment with a verifiable summary: rebase status, each
+finding and its disposition, test coverage decision, and verbatim
+gate output with real numbers.
+
+### 7. Verify final state
+
+```bash
+gh pr view <PR> --json mergeable,mergeStateStatus,statusCheckRollup
+```
+
+Poll until checks complete. If anything that was green went red,
+diagnose and fix before declaring done.
+
+## Common patterns
+
+### Pattern: All issues already fixed
+
+When a bot shows open findings but the branch owner believes they
+are all resolved:
+1. Do not trust the assertion -- verify each one in the current code.
+2. Stale comments are the most common case: the code was refactored
+   and the bot finding path no longer exists.
+3. Distinguish "already fixed before bot ran" from "fixed in a later
+   commit the bot has not re-reviewed yet".
+4. Re-trigger the bot if it has not reviewed current HEAD.
+
+### Pattern: Direct unit tests missing
+
+Bots frequently flag helper functions exercised only through callers.
+Add a direct test for the helper itself -- do not rely on indirect
+coverage through a caller integration test.
+
+### Pattern: Branch conflict with rewritten shared file
+
+When rebase hits a conflict in a file both branches modified:
+1. Run git log to understand what main changed and why.
+2. Read the purpose of the main-side hunk -- it is usually an invariant
+   your branch is unaware of.
+3. Apply main's change to your version of the file, then re-run
+   the affected tests.
+4. Document which invariant you preserved in your PR comment.
+
+### Pattern: CI flaky on first push
+
+Before declaring a gate failure real:
+1. Check if the failure is in a known flaky test.
+2. Check if the failure is in a linter with a stale cache from a
+   different worktree.
+3. Re-run the specific failing check once before fixing.
+4. Only fix if the failure reproduces on re-run.
+
+## Related skills
+
+- pr-finalize -- drive a PR from scratch to merge-ready when comments are unaddressed.
+- qodoloop -- full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- coderabbitloop -- full CodeRabbit thread protocol.
+- ci-fix-loop -- when the blocker is a failing CI pipeline, not review feedback.

package/README.md

@@ -11,6 +11,8 @@
 
 Agent-agnostic skill collection for Codex, Claude, Cursor, Grok, and other skill-aware tools.
 
+**Browse the catalog: [skills.olegkoval.com](https://skills.olegkoval.com)**
+
 These skills are opinionated by design. They encode working defaults, preferred tools, and repeatable workflows instead of trying to be neutral snippets. Treat them as starting points with taste: useful out of the box, easy to inspect, and specific enough for an agent to execute consistently.
 
 ## Structure
@@ -19,6 +21,7 @@ These skills are opinionated by design. They encode working defaults, preferred
 - `catalog/` — machine-readable inventory
 - `collections/` — grouped package bundles
 - `scripts/` — sync and validation helpers
+- `site/` — generator for the browsable catalog at [skills.olegkoval.com](https://skills.olegkoval.com) (`npm run build:site`)
 
 ## Principles
 
@@ -136,11 +139,11 @@ packages/{category}/{skill}/SKILL.md
 
 </details>
 
-## All 29 Skills
+## All 39 Skills
 
 Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup name in a new agent session.
 
-### Software development (27)
+### Software development (34)
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
@@ -151,8 +154,10 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [ci-fix-loop](packages/software-development/ci-fix-loop/SKILL.md) | Diagnoses GitHub Actions CI failures in a loop: fetches failing check logs, applies a targeted fix, pushes, and waits for the next run — repeating until green or a blocker needs a human | CI is red after a push and you want it driven to green automatically |
 | [cloudflare-block-countries](packages/software-development/cloudflare-block-countries/SKILL.md) | Blocks specific countries via Cloudflare WAF Custom Rules using the API | Geo-blocking traffic or setting up WAF country rules across single or multiple zones |
 | [coderabbitloop](packages/software-development/coderabbitloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings, reading each inline comment's own Prompt for AI Agents block, replying to the thread, and resolving it | Fully addressing a PR against CodeRabbit's review before merging |
+| [codexloop](packages/software-development/codexloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved OpenAI Codex comments, but verifies each finding against the real code first and rebuts false positives instead of editing correct code | Clearing a Codex review without cargo-culting its suggestions |
 | [crash-course](packages/software-development/crash-course/SKILL.md) | 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 | Ramping up on an unfamiliar codebase, project, or concept under time pressure |
 | [docs-index-keeper](packages/software-development/docs-index-keeper/SKILL.md) | Keeps a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows | A repo has `docs/` and needs `docs/README.md` updated automatically |
+| [geminiloop](packages/software-development/geminiloop/SKILL.md) | Iteratively drives a GitHub PR to zero unresolved Gemini Code Assist comments, treating each as a claim to verify — fixing the correct ones and rebutting the rest with evidence | Clearing a Gemini Code Assist review whose findings need checking first |
 | [gh-cli](packages/software-development/gh-cli/SKILL.md) | Guides GitHub CLI usage for repos, PRs, Actions, releases, issues, and all related GitHub operations | Working with GitHub from the command line and needing reliable `gh` commands |
 | [git-commit](packages/software-development/git-commit/SKILL.md) | Creates conventional commits with diff-aware staging and message generation | Asking to commit changes or wanting a conventional commit message from the current diff |
 | [macos-menubar-app](packages/software-development/macos-menubar-app/SKILL.md) | Builds a production-quality macOS menubar or notch app in SwiftUI — MenuBarExtra setup, sandbox entitlements, keyboard shortcuts, sound effects | Building a native macOS utility that lives in the menu bar or Dynamic Island notch |
@@ -172,6 +177,10 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [skill-budget-audit](packages/software-development/skill-budget-audit/SKILL.md) | Diagnoses and fixes Claude Code's skill context budget overflow — identifies heavy plugin bundles that exceed the 2% budget | Skills failing to load or Claude hitting context limits from plugin bundles |
 | [starter-rules](packages/software-development/starter-rules/SKILL.md) | Loads and enforces hard rules for every oleg-koval/* starter | Ensuring 300-line files, E2E tests, pre-commit hooks, Vertical Slice architecture, and KISS/DRY/SOLID |
 | [wikipedia-uk-editor](packages/software-development/wikipedia-uk-editor/SKILL.md) | Drafts policy-compliant Ukrainian Wikipedia edits — en→uk translation, stub expansion, sourcing, backlog cleanup — returning ready-to-paste wikitext, an edit summary, and a verified source list | Editing, translating, or sourcing a uk.wikipedia.org article, or planning what to contribute next |
+| [pr-finalize-complete](packages/software-development/pr-finalize-complete/SKILL.md) | Confirms a PR is genuinely merge-ready when the work is believed done: re-checks each finding against current code, separates stale comments from fixed ones, and runs the real lint/test gates before reporting | A branch owner says it's already fixed and you need that verified rather than assumed |
+| [pr-to-green](packages/software-development/pr-to-green/SKILL.md) | Orchestrates a GitHub PR from first push to merge-ready: runs ci-fix-loop until checks are green, detects active AI review bots, runs qodoloop and coderabbitloop in sequence, and confirms zero unresolved threads | Driving a PR to merge-ready in one pass without manually chaining the fix loops |
+| [dependabot-triage](packages/software-development/dependabot-triage/SKILL.md) | Triages open Dependabot and Renovate PRs in bulk: classifies by risk tier, auto-approves safe patch bumps, flags breaking major upgrades for human review, and posts a digest | Clearing a backlog of dependency update PRs during a maintenance window |
+| [store-listing-copy](packages/software-development/store-listing-copy/SKILL.md) | Generates platform-validated App Store, Google Play, and Connect IQ store listing copy (title, subtitle, description, what's new, keywords) from a git changelog | Writing store copy before submitting to apple-store-submit or the garmin-watchface store workflow |
 
 ### Marketing (2)
 
@@ -277,7 +286,7 @@ See [docs/skill-anatomy.md](docs/skill-anatomy.md) for the package format.
 ```text
 agent-skills/
 ├── packages/
-│   ├── software-development/   (19 skills)
+│   ├── software-development/   (22 skills)
 │   ├── marketing/              (2 skills)
 │   ├── music/                  (1 skill)
 │   └── photography/            (1 skill)

package/catalog/skills.json

@@ -557,6 +557,30 @@
         "kiro"
       ]
     },
+    {
+      "name": "pr-finalize-complete",
+      "lookupName": "olko:pr-finalize-complete",
+      "category": "software-development",
+      "path": "packages/software-development/pr-finalize-complete",
+      "description": "Confirms a PR is genuinely merge-ready when the work is already believed done: re-checks every review-bot and human finding against the current code, separates stale comments from fixed ones, runs the repo's real lint and test gates, and reports the evidence rather than the assumption.",
+      "tags": [
+        "code-review",
+        "pull-requests",
+        "github",
+        "testing",
+        "verification",
+        "agents"
+      ],
+      "adapters": [
+        "claude",
+        "codex",
+        "cursor",
+        "copilot",
+        "grok",
+        "windsurf",
+        "kiro"
+      ]
+    },
     {
       "name": "qodoloop",
       "lookupName": "olko:qodoloop",
@@ -629,6 +653,54 @@
         "kiro"
       ]
     },
+    {
+      "name": "codexloop",
+      "lookupName": "olko:codexloop",
+      "category": "software-development",
+      "path": "packages/software-development/codexloop",
+      "description": "Iteratively drives a GitHub PR to zero unresolved OpenAI Codex review comments — but verifies every finding against the real code first, fixes only the correct ones, and rebuts false positives without changing correct code.",
+      "tags": [
+        "code-review",
+        "codex",
+        "github",
+        "pull-requests",
+        "automation",
+        "agents"
+      ],
+      "adapters": [
+        "claude",
+        "codex",
+        "cursor",
+        "copilot",
+        "grok",
+        "windsurf",
+        "kiro"
+      ]
+    },
+    {
+      "name": "geminiloop",
+      "lookupName": "olko:geminiloop",
+      "category": "software-development",
+      "path": "packages/software-development/geminiloop",
+      "description": "Iteratively drives a GitHub PR to zero unresolved Gemini Code Assist comments — treats each one as a claim to verify, fixes only the genuinely-correct findings, and rebuts the rest with evidence instead of editing correct code.",
+      "tags": [
+        "code-review",
+        "gemini",
+        "github",
+        "pull-requests",
+        "automation",
+        "agents"
+      ],
+      "adapters": [
+        "claude",
+        "codex",
+        "cursor",
+        "copilot",
+        "grok",
+        "windsurf",
+        "kiro"
+      ]
+    },
     {
       "name": "add-to-my-skills",
       "lookupName": "olko:add-to-my-skills",
@@ -766,6 +838,80 @@
         "copilot",
         "grok"
       ]
+    },
+    {
+      "name": "pr-to-green",
+      "lookupName": "olko:pr-to-green",
+      "category": "software-development",
+      "path": "packages/software-development/pr-to-green",
+      "description": "Orchestrate a GitHub PR from first push to merge-ready: run ci-fix-loop until checks are green, detect active AI review bots, run qodoloop and coderabbitloop in sequence, and confirm zero unresolved threads.",
+      "tags": [
+        "github",
+        "pr",
+        "ci",
+        "loop",
+        "qodoloop",
+        "coderabbitloop",
+        "ci-fix-loop",
+        "workflow",
+        "automation"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "grok"
+      ]
+    },
+    {
+      "name": "dependabot-triage",
+      "lookupName": "olko:dependabot-triage",
+      "category": "software-development",
+      "path": "packages/software-development/dependabot-triage",
+      "description": "Triage open Dependabot and Renovate PRs in bulk: classify by risk tier, auto-approve and merge safe patch bumps, flag breaking major upgrades for human review, and post a digest.",
+      "tags": [
+        "dependabot",
+        "renovate",
+        "dependencies",
+        "security",
+        "automation",
+        "triage",
+        "github"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "grok"
+      ]
+    },
+    {
+      "name": "store-listing-copy",
+      "lookupName": "olko:store-listing-copy",
+      "category": "software-development",
+      "path": "packages/software-development/store-listing-copy",
+      "description": "Generate platform-validated App Store, Google Play, and Connect IQ store listing copy (title, subtitle, description, what's new, keywords) from a git changelog or release notes.",
+      "tags": [
+        "app-store",
+        "google-play",
+        "connect-iq",
+        "garmin",
+        "store",
+        "listing",
+        "copy",
+        "release-notes",
+        "ios",
+        "android"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "grok"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -30,13 +30,15 @@
     ".kiro",
     "scripts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "site"
   ],
   "scripts": {
     "build": "sh ./scripts/build-adapters.sh",
     "test": "sh ./scripts/validate-catalog.sh",
     "semantic-release": "semantic-release",
-    "release:dry-run": "semantic-release --dry-run --no-ci --verify-conditions=@semantic-release/changelog --verify-conditions=@semantic-release/git --verify-conditions=@semantic-release/github"
+    "release:dry-run": "semantic-release --dry-run --no-ci --verify-conditions=@semantic-release/changelog --verify-conditions=@semantic-release/git --verify-conditions=@semantic-release/github",
+    "build:site": "node site/build.mjs"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",