@olegkoval/agent-skills 1.26.0 → 1.28.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.25.0",
+  "version": "1.27.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -9,6 +9,7 @@
   "repository": "https://github.com/oleg-koval/agent-skills",
   "license": "MIT",
   "skills": [
+    "./packages/software-development/lekker-review",
     "./packages/software-development/self-critique",
     "./packages/software-development/docs-index-keeper",
     "./packages/software-development/semantic-release-beta",

package/README.md

@@ -3,7 +3,7 @@
   <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, and other skill-aware tools.</strong></p>
   <p>
     <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
-    <img src="https://img.shields.io/badge/skills-24-2563eb" alt="24 skills">
+    <img src="https://img.shields.io/badge/skills-40-2563eb" alt="40 skills">
     <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Grok%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro-111827" alt="Codex Claude Cursor Grok Copilot Windsurf Kiro">
     <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
   </p>
@@ -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 39 Skills
+## All 40 Skills
 
 Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup name in a new agent session.
 
-### Software development (34)
+### Software development (35)
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
@@ -157,6 +160,7 @@ Each entry links to its `SKILL.md`. Reference any skill by its `olko:*` lookup n
 | [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 |
+| [lekker-review](packages/software-development/lekker-review/SKILL.md) | Runs a FAANG-quality PR review in an isolated worktree: 5 parallel specialist agents, adversarial finding verification, proof-of-bug tests for Criticals, and an optional --fix mode that applies and commits its own findings (Claude Code only — needs the Workflow tool) | Reviewing a GitHub PR beyond what a single-pass review or a bot reviewer catches |
 | [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 |
 | [mvp-oneshot](packages/software-development/mvp-oneshot/SKILL.md) | Takes a rough product idea and produces a scoped, testable MVP plan and initial implementation in a single pass | Going from idea to a shippable one-week MVP without losing scope |
 | [obsidian-pr-sync](packages/software-development/obsidian-pr-sync/SKILL.md) | Fetches open GitHub PRs assigned to you or requesting review and writes a grouped age-sorted section into today's Obsidian daily note | Syncing GitHub review queue to Obsidian at the start of the day or on demand |

package/catalog/skills.json

@@ -1,6 +1,24 @@
 {
   "name": "agent-skills",
   "packages": [
+    {
+      "name": "lekker-review",
+      "lookupName": "olko:lekker-review",
+      "category": "software-development",
+      "path": "packages/software-development/lekker-review",
+      "description": "FAANG-quality PR code review: isolated worktree checkout, context gathering from your issue tracker/chat/docs/CI/monitoring, 5 parallel specialist review agents, adversarial finding verification, proof-of-bug tests for Criticals, and an optional --fix mode that applies and commits its own findings.",
+      "tags": [
+        "code-review",
+        "pull-request",
+        "github",
+        "multi-agent",
+        "workflow",
+        "quality"
+      ],
+      "adapters": [
+        "claude"
+      ]
+    },
     {
       "name": "self-critique",
       "lookupName": "olko:self-critique",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.26.0",
+  "version": "1.28.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",

package/packages/software-development/lekker-review/SKILL.md

@@ -0,0 +1,519 @@
+---
+name: lekker-review
+description: >
+  FAANG-quality PR code review, adaptable to any team. Checks out the branch in an
+  isolated worktree, gathers context from your issue tracker, chat, docs, CI
+  checks, and (optionally) production monitoring, runs 5 parallel specialized
+  review agents (quality/implementation/simplification/conventions/test-quality),
+  verifies every finding against the diff, then outputs a single unified markdown
+  review — file + risk + bad code + why it's wrong + fix — ready to paste directly
+  into GitHub. Saves every review to ~/code-reviews/*.md. Covers business logic,
+  scalability, complexity, data integrity, security, integration contracts, error
+  handling, and migration safety. Critical findings come with PROOF: a prover
+  agent writes a failing test in the worktree demonstrating each bug, and fix
+  mode later re-runs it to show the fix flips it green. Every review also
+  publishes a private living artifact page whose URL stays stable across
+  re-reviews, so the author watches findings close commit by commit.
+  With --fix (or by accepting the post-review offer) it also APPLIES its own
+  Critical/Important findings as real code in the worktree, verifies each edit,
+  commits them, and pushes to the PR branch only after explicit confirmation.
+  Use when the user says "review this PR", "lekker review", "check this PR",
+  "do a code review on PR #N", "review and fix this PR", "apply the review
+  fixes", provides a GitHub PR URL, or asks for a pull request review in any
+  form.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Agent, Workflow, AskUserQuestion, Artifact
+compatibility: Claude Code only. Requires the Workflow tool (multi-agent orchestration)
+  and the Artifact tool (living review page) — other Agent Skills-compatible tools
+  without an equivalent to Workflow cannot run the review/verify/critic pipeline this
+  skill depends on. Requires git and gh (GitHub CLI) authenticated.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - code-review
+    - pull-request
+    - github
+    - multi-agent
+    - workflow
+    - quality
+argument-hint: "<github-pr-url | repo pr-number | repo pr-title> [scan|medium|deep] [--post] [--fix]"
+---
+
+# Lekker Review
+
+FAANG-grade code review. Isolated worktree checkout, full context gathering
+(issue tracker + chat + docs + framework docs + monitoring + CI, whichever
+you have MCP tools configured for), then 5 parallel specialized review
+agents, a finding-verification pass, and one unified markdown output.
+
+Each finding contains: **file + risk** · **bad code verbatim** · **why it's
+wrong** · **fix with code example** - ready to paste directly into GitHub.
+Reviews are saved to `~/code-reviews/` for future reference.
+
+Optionally the skill then **applies** its own findings (`--fix`): fix agents edit
+the worktree, a read-only verifier checks each edit against the real `git diff`,
+static checks run, one commit lands per file, and nothing is pushed until the
+user says so. Procedure in `references/fix-mode.md`.
+
+No nitpicking. Critical and Important findings are reserved for things that
+could cause bugs, outages, data loss, security incidents, or real performance
+problems at scale.
+
+**HARD RULE: the `## 💰 Review Cost` block is mandatory.** Every review MUST
+end with a fully-populated cost block (token + price breakdown, real numbers,
+no `<N>` placeholders). A review without the cost block is incomplete. If you
+are about to present the review without it, stop and compute it first.
+
+---
+
+## Set up before first use
+
+This skill ships with **no** hard rules of its own — `references/house-rules.md`
+is a template. Fill it in with your team's own non-negotiable conventions
+(type safety, pagination, PR-title format, repo-placement taxonomy, stack
+context) before relying on the Critical-severity hard-rule gate. Until then,
+the 5 specialist agents still run and still find real bugs — they just don't
+have a codified "always Critical" rule list to check against.
+
+If any hard rule you define carries a `rule` tag (e.g. `"TS-1"`), reviewer
+agents attach that tag to matching findings and the workflow **skips
+adversarial verification** for them. This is deliberate: the verifier's five
+challenges ask runtime-failure questions ("does this fail on a normal
+execution?", "can you write the failing test?") that a standards violation
+can never answer, so verifying them systematically drops the very findings
+your policy declares non-negotiable. A tagged finding keeps its Critical
+severity; the workflow returns how many were exempted as `hardRuleCount`, and
+each carries a `verifierReasoning` saying so.
+
+`${CLAUDE_PLUGIN_ROOT}` below refers to this skill's own installed directory
+— resolve every `references/...` and script path relative to it.
+
+---
+
+## Step 0 - Parse input
+
+Accept any of:
+- Full GitHub URL: `https://github.com/owner/repo/pull/123`
+- Repo + number: `my-service 42`
+- Repo + partial title: `my-service "add offline orders"`
+
+If the user gives a short repo name without an org/owner, ask once which
+org/owner it belongs to (or use a default you've configured), then build
+`REPO_SLUG` as `<owner>/<name>`.
+
+Derive and carry these variables through every subsequent step:
+- `REPO_SLUG` (e.g. `my-org/my-service`)
+- `PR_NUMBER`
+- `PR_BRANCH` (from `gh pr view`)
+- `PR_URL` = `https://github.com/<REPO_SLUG>/pull/<PR_NUMBER>`
+
+**Depth:** explicit keyword `scan`, `medium`, or `deep` wins. If absent, run
+`gh pr view <PR_NUMBER> --repo <REPO_SLUG> --json additions,deletions,changedFiles`
+and apply AUTO-DEPTH:
+- `scan` if additions+deletions < 150 AND changedFiles <= 5
+- `deep` if additions+deletions > 800 OR changedFiles > 25 OR diff touches
+  `migrations/` or `*.sql`
+- `medium` otherwise
+
+State the chosen depth (and whether it was auto-selected) in the review header.
+
+**`--post` flag:** parse and store as `POST_REVIEW=true`.
+
+**`--fix` flag:** parse and store as `FIX_MODE=true`. Fix mode needs a real
+checkout, so `--fix` forces Track A (worktree setup) to run even when
+depth=scan. If the user did NOT pass `--fix`, leave `FIX_MODE=false` for now -
+Step 4 offers it after the review is printed.
+
+**`--no-artifact` flag:** parse and store as `ARTIFACT=false` (default true).
+Skips Step 3.5 (living review artifact) silently.
+
+**Re-review detection:** run
+`ls ~/code-reviews/*-pr-<PR_NUMBER>-<repo-short-name>.md 2>/dev/null | sort | tail -1`
+to find the newest prior review for this PR (repo-short-name = last segment of
+REPO_SLUG; keeps PR numbers from colliding across repos). If found, grep it for
+`\*\*Head:\*\*` and extract the short sha. Set `PREV_SHA=<sha>` and
+`PREV_REVIEW_FILE=<path>`. If no Head line exists in the file (older format),
+treat as a full review and leave PREV_SHA unset. Also grep the same file for
+`\*\*Artifact:\*\*` and set `PREV_ARTIFACT_URL=<url>` (null when absent) - Step
+3.5 republishes to the SAME url so the artifact stays a living page for this PR.
+
+---
+
+## Depth gate
+
+| Step                        | scan                  | medium              | deep                       |
+|-----------------------------|-----------------------|---------------------|----------------------------|
+| Context: issue-tracker/CI/diff/existing-reviews | always | always | always |
+| Context: chat/docs/framework-docs/monitoring/prior-review-memory (optional, MCP-dependent) | skip | included | included + broader recall |
+| Worktree + static checks    | skip (WORKTREE_PATH=null) unless `--fix` | included | included          |
+| Review agents               | 2 triage (haiku)      | 5 specialists (sonnet) | 5 specialists (sonnet)  |
+| Per-finding verification    | none                  | Criticals only (hard rules exempt) | Criticals + Importants (hard rules exempt) |
+| Completeness critic         | skip                  | skip                | included                   |
+| Proof-of-bug (failing test per Critical) | skip     | included (max 5)    | included (max 5)           |
+| Living review artifact      | included              | included            | included                   |
+| Housekeeping (optional memory/notes writeback) | skip | included            | included                   |
+| `--post`                    | supported             | supported           | supported                  |
+| `--fix` / fix offer         | supported (forces worktree) | supported     | supported                  |
+
+For scan: note `⚡ scan - worktree unavailable, static checks skipped` in the
+review header. When `--fix` forced the worktree at scan depth, drop that note
+and say `⚡ scan - worktree created for --fix` instead.
+
+---
+
+## Step 1 - Context + worktree (concurrent)
+
+Fire both tracks in the same turn.
+
+### Track A - worktree setup (skip when depth=scan, unless `--fix`)
+
+Run via Bash with `run_in_background`:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/scripts/setup-worktree.sh \
+  <REPO_SLUG> <PR_BRANCH> <scratchpad>/worktree.json [PREV_SHA]
+```
+
+On completion, read `worktree.json`. Keys emitted:
+`worktreePath`, `repoRoot`, `headSha`, `headShaShort`, `tscTail`,
+`tscChangedTail`, `tscErrorCount`, `eslintTail`, `eslintScope`, `changedFiles`,
+`baseRef`, `projectRules`, `deltaFile`, `notes`.
+
+Static checks are scoped so you can tell this PR's errors from the repo's
+standing debt - do not try to infer that from the raw tail:
+
+- `eslintTail` is the result of linting only `changedFiles` (`eslintScope` says
+  `changed-files`). Everything in it belongs to this PR. When `eslintScope` is
+  `full-fallback`, base-ref detection failed and the lint is repo-wide again -
+  in that case treat its contents as unattributed and say so rather than
+  blaming the author.
+- `tscTail` is the raw repo-wide tail (tsc needs the whole program, so it cannot
+  be scoped). `tscChangedTail` holds only the errors in files this PR touched -
+  that is the attributable set. `tscErrorCount` is the repo-wide total; a large
+  count with an empty `tscChangedTail` means pre-existing debt, not a finding.
+- If your stack doesn't use tsc/eslint, adapt `setup-worktree.sh`'s static
+  check step to your language's compiler/linter equivalents.
+
+A failing CI build or test = Critical finding input.
+
+When depth=scan: set `WORKTREE_PATH=null` without launching the script - unless
+`FIX_MODE=true`, in which case run the script anyway (fix mode cannot edit code
+from a diff).
+
+### Track B - metadata and signals (all calls fired in parallel)
+
+Run ALL of the following in the same message. Full query details are in
+`references/context-gathering.md` - follow it, do not paste it wholesale into
+agent contexts.
+
+- `gh pr view <PR_NUMBER> --repo <REPO_SLUG>` with fields: `number`, `title`,
+  `body`, `author`, `headRefName`, `baseRefName`, `labels`, `linkedBranches`,
+  `mergeStateStatus`, `additions`, `deletions`, `changedFiles`, `isDraft`,
+  `headRefOid`. Extract `headRefOid` (full sha) and `headShaShort` (first 7).
+- Title/ticket-prefix check (if `house-rules.md` defines one): scan commit log
+  for the ticket pattern; set `PR_TITLE_ISSUE` and `RECOMMENDED_PREFIX`.
+- `gh pr diff <PR_NUMBER> --repo <REPO_SLUG> > <scratchpad>/pr.diff` - fetched
+  ONCE; all agents read this file via `DIFF_FILE`.
+- `gh pr checks <PR_NUMBER> --repo <REPO_SLUG>`
+- `gh pr reviews <PR_NUMBER> --repo <REPO_SLUG>` and review comments
+- Issue-tracker lookup (Linear/Jira/GitHub Issues MCP, if configured) per
+  ticket ID found in title/body/branch; collect ACs as numbered list (`acList`).
+- (medium/deep only, optional) Chat search (Slack/Discord MCP, if configured):
+  PR-title keywords and ticket ID.
+- (medium/deep only, optional) Docs search (Notion/Confluence/wiki MCP, if
+  configured): feature name or ticket title.
+- (medium/deep only, optional, only when relevant) Framework/API docs MCP for
+  the specific framework or third-party API the diff touches.
+- (medium/deep only, optional) Monitoring search (Sentry/Rollbar/etc. MCP, if
+  configured) for filenames or service names from the diff.
+- (medium/deep only, optional) Prior-review-memory recall, if you maintain
+  such a system: patterns and false positives specific to this repo.
+
+### Assemble CONTEXT_FILE
+
+Write `<scratchpad>/context.json` with keys:
+
+```json
+{
+  "acList":          "<numbered ACs from your issue tracker, or empty>",
+  "projectRules":    "<worktree.json projectRules + any recalled review patterns appended under '## Recalled patterns'>",
+  "sentrySignals":   "<monitoring issue summaries, or null>",
+  "ciStatus":        "<passing | failing: <names> | pending | N/A>",
+  "existingReviews": "<prior review summaries>",
+  "deltaFile":       "<worktree.json deltaFile, or null>",
+  "houseRulesFile":  "${CLAUDE_PLUGIN_ROOT}/references/house-rules.md"
+}
+```
+
+Agents read keys from this file. Nothing from CONTEXT_FILE is pasted into
+their prompts wholesale - the workflow script delivers it by path.
+
+---
+
+## Step 2 - Workflow (review + verify + critic)
+
+Invoke the Workflow tool:
+
+```
+scriptPath: ${CLAUDE_PLUGIN_ROOT}/workflow.js
+args: {
+  repoSlug,
+  prNumber,
+  prUrl,
+  depth,
+  diffFile:    "<scratchpad>/pr.diff",
+  contextFile: "<scratchpad>/context.json",
+  worktreePath: <null for scan, else from worktree.json>,
+  promptDir:   "${CLAUDE_PLUGIN_ROOT}/references/agents",
+  prevSha:     <null unless re-review>
+}
+```
+
+The workflow runs three phases:
+
+- **Review:** scan uses `[triage-quality, triage-logic]` on `haiku`; medium/deep
+  use 5 specialists (quality, implementation, simplification, conventions,
+  test-quality) on `sonnet`. Agents receive DIFF_FILE + CONTEXT_FILE by path.
+  All reviewers run to completion before verification starts.
+- **Dedup:** findings are merged across dimensions on `file:line` + title
+  token-similarity, so one issue found by three agents is verified once, not
+  three times. A merge keeps the highest severity and the longest
+  description/badCode/fix of the set - a Critical is never demoted by an
+  Observation someone else filed at the same line - and records every
+  contributing dimension in `agreedBy`.
+- **Verify:** scan verifies nothing; medium verifies Criticals; deep verifies
+  Criticals + Importants. Hard-rule findings (`rule` set) are always exempt.
+  Each verifier runs the five-challenge adversarial refutation from
+  `references/agents/verifier.md` against one finding, returns
+  `{verdict, newSeverity?, reasoning}`.
+- **Critic (deep only):** completeness critic gets the full deduped finding
+  list + DIFF_FILE; its findings go through verifier agents before promotion.
+- **Prove (medium/deep, worktree required):** each non-hard-rule Critical gets
+  one prover agent (`references/agents/prover.md`, sonnet, max 5) that writes a
+  test asserting the CORRECT behavior, runs it in the worktree, and captures it
+  failing because of the bug. The proof rides on the finding as
+  `proof: {attempted, proven, reason, testCode?, testCommand?, redOutput?}`.
+  A proof that comes back GREEN (code behaved correctly) is counter-evidence -
+  Step 3 must downgrade or explicitly justify the finding, never ignore it.
+  Hard-rule findings are never proved (policy violations have no failing test).
+
+Findings have schema:
+`{file, line, severity, title, description, badCode, fix, rule?, precedent?, agreedBy?, verifierReasoning?, proof?}`
+`badCode` and `fix` are schema-required: an empty string is allowed only on
+`observation` / `idiomatic` findings.
+
+Model tiers: triage on `haiku`, specialists on `sonnet`, verifiers + critic +
+provers on `sonnet`, housekeeping on `haiku`. Only the synthesis in Step 3 runs
+on the session model.
+
+Return value from the workflow:
+`{findings, droppedCount, downgradedCount, hardRuleCount, proveAttemptCount, provenCount, agentCount, outputTokens, turnTokensTotal}`
+`outputTokens` is this workflow's own output spend; `turnTokensTotal` is the
+whole turn's shared pool (main loop included).
+
+Wait for the workflow to complete before proceeding to Step 3.
+
+---
+
+## Step 3 - Synthesize and output
+
+**Mindset:** the author's name is not evidence. Bot review scores are not
+anchors. Apply your own judgment to every finding.
+
+**Do NOT flag:**
+- Style preferences or naming taste where no convention is violated
+- Comment wording choices
+- Scenarios requiring multiple simultaneous unrealistic failures
+- Tiny DRY opportunities (2-3 duplicated lines)
+- Pre-existing code not touched by this diff
+- Anything you are not confident about - omit rather than hedge
+
+**Idiomatic & Consistency exception:** the conventions agent raises non-blocking
+suggestions ONLY when a concrete better pattern provably already exists in the
+codebase. Never on taste alone. These land in their own section, not in
+Critical/Important. A finding without a cited precedent from the codebase is
+dropped.
+
+**Format** the review per `references/output-format.md` (read it now). Key
+requirements:
+
+- Header must include `**Head:** <headShaShort>` (enables future delta mode).
+- When `isDraft=true`: add `**DRAFT PR** - findings recorded for when this
+  is ready to merge.` after the header block.
+- When `mergeStateStatus` is not CLEAN: note it (e.g. conflicts, failing
+  required checks).
+- When `PR_TITLE_ISSUE=true`: insert the `⛔ CANNOT MERGE` block before the
+  Summary.
+- When `sentrySignals` is non-empty: include `## 🔥 Production Signals`.
+- When `PREV_SHA` is set: include `## 🔁 Since last review` comparing
+  `PREV_REVIEW_FILE` findings against the new head - list each as fixed or
+  still open, before any new findings.
+- Test Quality section: populate from the test-quality agent's fields
+  (`coverageVerdict`, `mutationSlip`, `mockSmells`).
+- Idiomatic section: populated from severity=idiomatic findings only.
+- **💰 Review Cost block:** `outputTokens` from the workflow return is the
+  ACTUAL output spend of the review workflow's own agents. `turnTokensTotal` is
+  the whole turn's shared pool - report it separately, never as the workflow's
+  cost. Input tokens are estimated (diff tokens x agent passes + context
+  + prompt files). Use the pricing table in `references/output-format.md`.
+  Real numbers only - no `<N>` placeholders.
+
+**Save the review:**
+
+```bash
+mkdir -p ~/code-reviews
+REVIEW_FILE=~/code-reviews/$(date +%Y-%m-%d)-pr-<PR_NUMBER>-<repo-short-name>.md
+# write the review to $REVIEW_FILE
+```
+
+After writing, re-read the file and emit a receipt:
+`✓ Review saved -> <path>`
+
+Also write the workflow's `findings` array verbatim to
+`<scratchpad>/findings.json` - fix mode reads its selection from there (the
+`proof` objects ride along for the Step 5b proof flip), and it is the receipt
+that what was reported equals what was found.
+
+Then print the full review as the response.
+
+---
+
+## Step 3.5 - Living review artifact (skip when ARTIFACT=false)
+
+Immediately after printing the review, follow `references/artifact-page.md`:
+launch ONE background sonnet agent that renders the review as a self-contained
+HTML page and publishes it via the Artifact tool - passing `PREV_ARTIFACT_URL`
+when set, so a re-review UPDATES the same page instead of minting a new URL.
+The page is the living version of the review: verdict header, since-last-review
+timeline, findings with proof panels, all private by default.
+
+Never block on it: the printed review and the saved file are the deliverable;
+the artifact is an enhancement. When the URL comes back, append/refresh the
+`**Artifact:** <url>` header line in the saved review file (re-read to confirm)
+and print one line: `🔗 Living review: <url>`.
+
+---
+
+## Step 4 - Fix mode (after the review is printed)
+
+### Trigger
+
+- `FIX_MODE=true` (the user passed `--fix`) -> go straight to
+  `references/fix-mode.md`.
+- `FIX_MODE=false` and at least one Critical or Important finding has a `fix`
+  field -> ask once, via AskUserQuestion:
+
+  > Apply these fixes to the PR branch?
+  > - **Critical + Important** (N findings) - fix agents edit the worktree,
+  >   verified, committed; push needs your confirmation
+  > - **Critical only** (N findings)
+  > - **No, review only**
+
+  Set `FIX_MODE=true` and `FIX_SCOPE=<critical+important | critical>` from the
+  answer. On "No", skip to Step 5.
+- No fixable findings, or the review found nothing -> do not ask. Say
+  `nothing to auto-fix` in one line and skip to Step 5.
+- **Unattended run** (cron, `/loop`, background agent): never ask. Run fix mode
+  only when `--fix` was passed explicitly, and stop before pushing.
+
+### Procedure
+
+Read `references/fix-mode.md` and follow it. Shape of the run:
+
+1. Preconditions: worktree exists + clean, `origin/<PR_BRANCH>` still at
+   `headSha`, PR open, head repo writable.
+2. Select eligible findings (Critical/Important with a `fix`, real file,
+   non-generated). Never auto-fix Observation, Idiomatic, or a title/process rule.
+3. Invoke the fix workflow:
+   ```
+   scriptPath: ${CLAUDE_PLUGIN_ROOT}/fix-workflow.js
+   args: { repoSlug, prNumber, worktreePath, diffFile, contextFile, promptDir,
+           findings: [<selected findings verbatim>] }
+   ```
+   One `sonnet` fix agent per file (never two on the same file), then a
+   read-only `sonnet` fix-verifier per file reading the actual `git diff`. One
+   retry max on a non-`good` verdict.
+4. Revert every group the verifier did not pass.
+5. Run `scripts/verify-fixes.sh <WORKTREE_PATH> <scratchpad>/fix-verify.json tests`
+   and diff the output against the baseline `tscTail`/`eslintTail` from
+   worktree.json. Newly introduced errors -> revert that group.
+5b. Proof flip: for findings with `proof.proven`, re-run the captured failing
+   test after the fix. Still red -> the fix did not fix the bug: revert the
+   group even if the fix-verifier said `good`. An executed test outranks an
+   agent's opinion. Green -> record `proofFlip: green` in the status table.
+6. Commit one commit per file with an explicit `git add -- <files>`.
+7. Push ONLY after the user confirms, with `git push origin HEAD:refs/heads/<PR_BRANCH>`
+   and a re-fetch sha guard. Never force, never rebase, never push to
+   main/master/staging/develop. Verify via `gh pr view --json headRefOid`.
+8. Print the per-finding status table and append `## 🔧 Fixes applied` to the
+   saved review file.
+
+Fix-agent tokens are additional spend: add a `Fix agents:` line to the
+`## 💰 Review Cost` block.
+
+---
+
+## Step 5 - Post-review (after the review and any fixes)
+
+### If POST_REVIEW=true
+
+Follow `references/github-post.md`:
+- Build a JSON payload with Critical + Important findings as inline comments
+  (only for lines present in the diff hunks).
+- POST via `gh api repos/<REPO_SLUG>/pulls/<PR_NUMBER>/reviews` with NO
+  `event` field (creates PENDING, visible only to you).
+- Verify post-condition: fetch review list, confirm PENDING state exists.
+- Print count + link.
+- Observation and Idiomatic findings go in the review body, never inline.
+- Never submit the review programmatically.
+- When fix mode applied and committed a finding, EXCLUDE it from the inline
+  comments - do not ask for a change you already made. Mention the applied
+  fixes in one line of the review body instead.
+
+### Housekeeping (skip when depth=scan, optional)
+
+If you maintain a persistent notes/memory system across reviews, launch ONE
+background Agent with `model: 'haiku'`, passing the review file path +
+repo-short-name + PR author login, instructed to follow
+`references/post-review.md` if you've written one for your own setup:
+- Log durable patterns (recurring findings, confirmed false positives) scoped
+  to the repo, never to the author.
+- Skip entirely if you have no such system — nothing else in this skill
+  depends on it.
+
+### Cleanup (when a worktree was created)
+
+**Fix-mode override:** if fix mode produced commits that were NOT pushed, do
+NOT clean up. Keep the worktree and the repo clone, print the worktree path and
+the exact push command. Deleting it destroys the only copy of the work. Clean up
+normally when the push succeeded or nothing was committed.
+
+```bash
+git -C <repoRoot> worktree remove --force <worktreePath> \
+  || rm -rf <worktreePath>
+git -C <repoRoot> worktree prune
+```
+
+If `repoRoot` starts with `/tmp/lekker-clone-`, also remove that clone dir.
+Remove the delta file if `deltaFile` was set in worktree.json. Verify with
+`git -C <repoRoot> worktree list` that no `lekker-review` entries remain.
+
+---
+
+## Failure rules
+
+Two identical failures = stop and diagnose, don't loop blindly.
+
+If the Workflow tool is unavailable or the run dies: fall back to launching the
+5 agents via the Agent tool with the same prompt files, do verification inline
+per `references/agents/verifier.md`, and state this fallback in the review
+output under a `**Note:** Workflow tool unavailable - ran agents directly`
+line in the header.
+
+Fix-mode specific:
+- Never claim a fix landed without a `git log` / `git status` receipt from the
+  worktree. The review's proposed `fix` text is not an applied fix.
+- Never push without explicit confirmation, and never force-push or rebase a
+  PR branch. If the branch moved under you, stop and report - the commits stay
+  local.

package/packages/software-development/lekker-review/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-lekker-review",
+  "description": "FAANG-quality PR code review: isolated worktree checkout, context gathering from your issue tracker/chat/docs/CI/monitoring, 5 parallel specialist review agents, adversarial finding verification, proof-of-bug tests for Criticals, and an optional --fix mode that applies and commits its own findings.",
+  "skills": "./skills"
+}