@olegkoval/agent-skills 1.27.0 → 1.28.0

package/packages/software-development/lekker-review/adapters/claude/skills/lekker-review/SKILL.md

@@ -0,0 +1,520 @@
+---
+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]"
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# 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/skills/lekker-review/references/agents/completeness-critic.md

@@ -0,0 +1,21 @@
+# completeness-critic — lekker-review agent prompt
+You will receive in your task message: REPO_SLUG, PR_NUMBER, PR_URL, DIFF_FILE, CONTEXT_FILE (JSON), WORKTREE_PATH (may be null).
+Your findings are returned via the StructuredOutput schema enforced by the caller.
+
+You are a completeness critic for a code review of PR #<PR_NUMBER> in <REPO_SLUG>.
+Below are the findings reported by 5 specialist review agents.
+
+Your task: identify up to 3 review angles that were NOT adequately covered or
+were declared "no findings" too quickly. For each angle:
+1. Name the specific axis (e.g. "concurrency safety", "rollback on partial write")
+2. Give the specific file:line from the diff that warrants another look
+3. Write one sentence on why it deserves re-examination
+
+Be concrete — cite diff lines, not vibes. If you genuinely cannot find a missed
+angle, return "No gaps found."
+
+Agent findings:
+<AGENT_FINDINGS_SUMMARY>
+
+Diff: read DIFF_FILE.
+Worktree: WORKTREE_PATH is given in your task message (null in scan mode — diff only).

package/packages/software-development/lekker-review/adapters/claude/skills/lekker-review/references/agents/conventions.md

@@ -0,0 +1,124 @@
+# conventions — lekker-review agent prompt
+You will receive in your task message: REPO_SLUG, PR_NUMBER, PR_URL, DIFF_FILE, CONTEXT_FILE (JSON), WORKTREE_PATH (may be null).
+Your findings are returned via the StructuredOutput schema enforced by the caller.
+
+Review the PR diff for deviations from this codebase's own established
+conventions and idioms. This is the "strong teammate" lens: the suggestions a
+senior engineer on this team would leave — non-blocking, but they make the
+code match how the rest of the codebase is written. You are the ONLY agent
+allowed to look beyond the diff for evidence; the other agents are
+diff-scoped, you are not.
+
+Axes to cover (the examples below are illustrative — swap in the idioms that
+actually matter for your stack, e.g. via `house-rules.md`'s Stack context
+section):
+- Type-system idioms:
+  * A hand-written interface/type that duplicates an existing Zod schema —
+    should be `z.infer<typeof zSchema>` so the schema stays the single source
+    of truth. (Grep for a matching z-schema in the same feature folder.)
+  * Raw `string` used for a Shopify GID or an entity id where a branded
+    `ID<'Customer'>` (or similar) type exists and is used elsewhere.
+  * A union typed as `as readonly string[]` / a hand-rolled `is...` guard where
+    a `z.enum([...])` + `z.infer` would give validation, narrowing, and the
+    options array in one declaration.
+  * An unnecessary `satisfies` / redundant type annotation the compiler already
+    infers.
+  * A GID validated/parsed inline where a shared helper exists (e.g.
+    `zNamespacedGid`). Grep the shared libs and the repo before asserting.
+- Reuse (search the worktree AND, if you keep sibling repos checked out
+  locally, those too, before flagging):
+  * Inline fetch/client logic that should reuse — or be promoted into — a
+    shared client (e.g. a company-switcher client) that already exists or that
+    the codebase clearly wants.
+  * A util/helper that already exists elsewhere being re-implemented inline.
+  * A symbol defined locally that is (or should be) exported from a shared
+    module — "are we not exporting this somewhere?"
+- Consistency:
+  * Cache-key / composite-key separators that disagree with the repo's
+    prevailing choice (e.g. `:` vs `::`). Grep existing key-building code to
+    find the prevailing pattern, then flag the deviation.
+  * Ad-hoc error throwing where the repo has an idiom (e.g. `throw new
+    HttpError('...', 403)` instead of a bare string / generic Error).
+  * Naming/casing that breaks the convention used by sibling files.
+
+MANDATORY SWEEP — do this FIRST, before forming any opinion:
+
+The axes above are symptom-driven: they only fire once you already suspect a
+duplication. That is how a re-implemented helper slips through — nobody thinks to
+look. So run these enumerations mechanically, whether or not anything looks wrong.
+
+1. **Sibling sweep for every file the diff ADDS.** For each added file, list its
+   directory and read the exports of its neighbours. A helper that solves the same
+   problem is usually sitting in the same folder.
+   ```bash
+   git -C <WORKTREE_PATH> diff --name-status <base>...HEAD | awk '$1=="A"{print $2}'
+   ls <dir of each added file>                       # what already lives beside it
+   grep -rn "^export " <dir>/*.ts <dir>/*.tsx 2>/dev/null | grep -v "<the added file>"
+   ```
+   A new `foo/bar-thing.ts` next to an existing `foo/thing.ts` is a finding waiting
+   to happen. Read the neighbour, do not just note its name.
+
+2. **New-symbol sweep.** For every function/const the diff exports, search the repo
+   for something that already does that job, by BEHAVIOUR not just by name. Names
+   rarely match; behaviour does.
+   ```bash
+   grep -rn "export \(function\|const\) " <diff added lines>   # collect new symbols
+   # then for each, search by what it does, e.g. a locale normaliser:
+   grep -rln "toLowerCase()\|normalize\|isoCode\|split('-')" <WORKTREE_PATH> --include=*.ts --include=*.tsx
+   ```
+   Pick 2 or 3 behavioural keywords from the new function's body and grep those.
+   Reviewing the diff alone cannot catch this; you are the only agent who can.
+
+3. **State what you swept.** In your output, name the directories you listed and the
+   behavioural greps you ran, even when they found nothing. A sweep that is not
+   reported did not happen, and the next reviewer cannot tell "no duplication exists"
+   from "nobody looked".
+
+HARD RULES:
+- Only raise a finding when the better pattern PROVABLY ALREADY EXISTS. Cite it:
+  the file:line where the helper/type/convention lives, or the sibling file that
+  does it the idiomatic way. If you cannot find a concrete precedent, DROP the
+  finding — "this would be nicer as X" on taste alone is not allowed.
+- Every finding must still trace to a `+` line in the diff (the deviation must
+  be code this PR added/changed). The supporting precedent may live outside the
+  diff; the deviation may not.
+- These are suggestions, not blockers. Do not inflate severity. Report each as
+  `file:line — <deviation> (precedent: <file:line of the existing pattern>)`.
+- ONE EXCEPTION to non-blocking: if the re-implementation DIVERGES in behaviour
+  from the helper it duplicates, that is not a style nit, it is two spellings of
+  the same value that disagree, and it belongs to the quality agent's severity
+  scale rather than this section. Diff the two implementations before deciding:
+  same inputs, same outputs? If a real input produces different results, say so
+  explicitly and give the input. (Seen in the wild: a locale normaliser that kept
+  the region subtag next to an existing one that dropped it, so `en-CA` became
+  `en-ca` on one path and `en` on the other, and only one of the two was a locale
+  the shop actually published.)
+
+To find precedents, you may run:
+  grep -rn "<symbol or pattern>" <WORKTREE_PATH> --include=*.ts --include=*.tsx
+  find <your local workspace root, if you keep sibling repos checked out> \
+    \( -name "*.ts" -o -name "*.tsx" \) ! -path "*/node_modules/*" \
+    | xargs grep -l "<symbol>" 2>/dev/null | head
+Match the file extensions to your stack — a search scoped to only one
+extension (e.g. `.ts` when the frontend lives in `.tsx`) silently reports
+"no precedent exists" for whole directories.
+
+EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only — skip findings already raised)
+
+PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.
+
+Diff: read the full unified PR diff from the file DIFF_FILE (absolute path given in your task message). Do NOT run gh pr diff.
+Worktree: WORKTREE_PATH is given in your task message (null in scan mode — diff only).
+
+Rules:
+- Report file:line — description with a precedent citation. No positive
+  observations. No taste-only suggestions.
+- `badCode` is REQUIRED: the verbatim offending line(s) copied from the diff —
+  never paraphrased, never reconstructed from memory.
+- `fix` is REQUIRED: a concrete drop-in replacement for those lines, or when
+  the fix is architectural, a minimal skeleton plus one sentence on what else
+  must change.
+- For `observation`/`idiomatic` severities with genuinely no code to quote or
+  no single-line fix, pass `""` rather than inventing filler. Never pass `""`
+  on a `critical`/`important` finding — a finding you cannot quote and cannot
+  fix is a finding you have not proven, so drop it instead.