@olegkoval/agent-skills 1.14.1 → 1.16.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -9,6 +9,7 @@
   "repository": "https://github.com/oleg-koval/agent-skills",
   "license": "MIT",
   "skills": [
+    "./packages/software-development/self-critique",
     "./packages/software-development/docs-index-keeper",
     "./packages/software-development/semantic-release-beta",
     "./packages/software-development/gh-cli",

package/.cursor-plugin/index.json

@@ -1,6 +1,11 @@
 {
   "name": "agent-skills",
   "plugins": [
+    {
+      "name": "olko:self-critique",
+      "source": "./packages/software-development/self-critique/adapters/cursor",
+      "description": "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score."
+    },
     {
       "name": "olko:docs-index-keeper",
       "source": "./packages/software-development/docs-index-keeper/adapters/cursor",

package/catalog/skills.json

@@ -1,6 +1,27 @@
 {
   "name": "agent-skills",
   "packages": [
+    {
+      "name": "self-critique",
+      "lookupName": "olko:self-critique",
+      "category": "software-development",
+      "path": "packages/software-development/self-critique",
+      "description": "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score.",
+      "tags": [
+        "critical-thinking",
+        "self-review",
+        "verification",
+        "adversarial",
+        "agents",
+        "quality"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
     {
       "name": "docs-index-keeper",
       "lookupName": "olko:docs-index-keeper",

package/collections/software-development.json

@@ -2,6 +2,7 @@
   "name": "software-development",
   "description": "Skills for software development, release automation, git workflows, documentation, prompt tooling, and product building.",
   "packages": [
+    "self-critique",
     "docs-index-keeper",
     "semantic-release-beta",
     "gh-cli",

package/package.json

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

package/packages/software-development/relay/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: relay
+description: >
+  Use claude-relay to run a long or rate-limit-prone task autonomously across subscription accounts.
+  Invoke this skill whenever the user says "use relay", "run this with relay", "do this overnight",
+  "run this autonomously", "use relay for X", or has a multi-hour / multi-step task they want to
+  hand off completely. Also use proactively when a task looks like it will take many turns and the
+  user hasn't thought about rate limits yet. Guides goal writing, picks the right flags, and starts
+  the run.
+license: MIT
+allowed-tools: Bash, Read, Write
+metadata:
+  author: Oleg Koval
+  tags:
+    - relay
+    - autonomous
+    - rate-limits
+    - claude-relay
+---
+
+# relay
+
+Runs a task **unattended** using `claude-relay`: drives `claude -p` in a headless loop, writes a
+handoff summary when one account's limit approaches, and switches to the next account automatically.
+You watch logs; relay handles the rest.
+
+Binary: `claude-relay` (alias `relay` if added to shell). Config: `~/.claude-relay/relay.config.json`.
+
+---
+
+## Step 1 — Decide: relay or inline?
+
+**Use relay when:**
+- Task will take many turns or hours (big refactor, migration, research + implementation)
+- The user wants to hand it off and walk away
+- Rate limits are a real concern (long-running or token-heavy)
+
+**Stay inline when:**
+- Task is quick (< ~10 turns)
+- User wants to review each step
+- Task needs interactive input that relay can't provide
+
+---
+
+## Step 2 — Write the goal
+
+A relay goal is a self-contained spec a fresh Claude agent can execute cold. Write it to
+`/tmp/relay-goal-<short-name>.md`. It must include:
+
+- **What to do** — concrete deliverables, not vague intent
+- **How to verify** — the exact command proving success (`npm test`, `curl /api/health`, etc.)
+- **Scope** — explicit list of what NOT to do (no commits, no PRs, no migrations — unless stated)
+- **Key files** — paths the agent should read first if the context isn't obvious
+
+**Template:**
+```markdown
+## Goal
+<1-3 sentences: the deliverable>
+
+## Success criteria
+Run `<command>` and confirm it exits 0 / returns the expected result.
+
+## Scope
+- DO: <explicit list>
+- DO NOT: open PRs / push commits / run migrations / touch unrelated files
+
+## Key files
+- <path> — <why it matters>
+```
+
+Good goals are specific. "Add input validation to all POST routes in `app/api/`" beats "improve the API".
+
+---
+
+## Step 3 — Pick flags
+
+| Situation | Flag |
+|-----------|------|
+| Task needs uncommitted changes, local `.env`, or a local database | `--in-place` |
+| Everything is committed; task is self-contained | *(default — isolated git worktree)* |
+
+When in doubt: if the repo has a `.env` or `node_modules` the task depends on, use `--in-place`.
+
+---
+
+## Step 4 — Run
+
+```bash
+claude-relay run /tmp/relay-goal-<name>.md <absolute-path-to-repo> [--in-place]
+```
+
+Relay logs stream to stderr. The run ends when the agent outputs `RELAY_TASK_COMPLETE` on its own
+line, or hits a hard cap (400 turns / 48h wall clock).
+
+---
+
+## Step 5 — Tell the user
+
+After starting, report:
+- The exact command you ran
+- What to watch for: `RELAY_TASK_COMPLETE` in logs, or `claude-relay status --config ~/.claude-relay/relay.config.json`
+- The flag you picked and why (especially if you chose `--in-place`)
+
+---
+
+## Health check
+
+If anything seems misconfigured:
+```bash
+claude-relay doctor --config ~/.claude-relay/relay.config.json
+```
+
+Should show ✓ for both account slots. If a slot shows ✗, tell the user to run:
+```bash
+claude-relay login <email>  # must have claude.ai open in browser as that account first
+```

package/packages/software-development/self-critique/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: self-critique
+description: Adversarially critique your own last substantial answer before the user has to. Spawn a critic agent that verifies every claim against live sources, checks similar and related issues, finds patterns, and addresses comments directly to you. Loop (revise, re-score) until satisfied, then report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score. Use when the user asks you to criticize, challenge, stress-test, or red-team your own answer, or accepts a "critical-thinking review" offer.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - critical-thinking
+    - self-review
+    - verification
+    - adversarial
+    - agents
+    - quality
+---
+
+# Self-critique
+
+Run an adversarial review of **your own previous answer** and report the result in numbers.
+
+## Overview
+
+A confident answer is not a verified one. This skill turns your last substantial reply into the
+subject of a hostile review: a separate critic agent tries to refute it against live sources, hunts
+for the related issue or pattern you missed, and scores it. You then revise and re-score until the
+score stops moving, and report the outcome honestly, including where you were wrong.
+
+The point is to surface error before the user does, and to make "is this actually right?" a measured
+quantity instead of a vibe.
+
+## When to Use
+
+- The user asks you to criticize, challenge, stress-test, red-team, or "poke holes in" your own answer.
+- The user accepts a "critical-thinking review" offer.
+- You have just produced a substantial analysis, recommendation, or investigation and want a
+  confidence number before the user acts on it.
+
+Do not use for trivial one-shot replies or simple chat. The overhead only pays off on load-bearing
+answers.
+
+## Procedure
+
+1. **Snapshot the target.** Capture your last substantial answer verbatim, plus the concrete claims
+   it makes and the source each claim rests on. This is `v1`.
+
+2. **Spawn the critic.** Launch one independent agent with live-source access (issue tracker, code
+   host, error monitor, the repo). Use the prompt template below. The critic must return: `score`
+   (0-100), `verdict` (AGREE / AGREE-WITH-CAVEATS / DISAGREE), `where_wrong` (list), `missed`
+   (related issues or patterns you failed to surface), `unverifiable` (claims it could not confirm),
+   and `fixes` (ranked, actionable).
+
+3. **Decide and loop.** Stop if `score >= 90` OR no actionable `fixes` remain. Otherwise revise the
+   answer using the fixes to produce `v2`, then re-spawn the critic to score `v2`. Repeat.
+   **Hard cap: 3 critic rounds.** (A known ceiling: raise it only if a round is still finding real,
+   fixable defects.)
+
+4. **Report, always, even after a single round:**
+   - **Where you were wrong** - consolidated, each item with the receipt the critic cited.
+   - **Iterations to satisfy** - how many critic rounds it took to reach the stop condition (1 means
+     it was solid on the first pass).
+   - **Improvement in numbers** - the score trajectory, for example `72 -> 88 -> 94 (+22 pts, +31%)`.
+     If only one round ran, state `no revision needed`.
+   - **Final score** - the critic's last score and verdict.
+   - **Unverifiable** - anything you should not present as fact.
+
+## Critic prompt template
+
+Pass this to the critic agent, filling in the two placeholders. It is deliberately adversarial:
+the default stance is that the answer is wrong until a live source proves otherwise.
+
+> You are an adversarial reviewer. Your job is to verify and, where possible, **refute** the answer
+> below. Default to skepticism: assume a claim is wrong until a live source proves it. Address every
+> comment **directly to the author** ("You claimed X; the source says Y").
+>
+> **The answer under review (verbatim):**
+> {{ANSWER}}
+>
+> **Its claims and the source each rests on:**
+> {{CLAIMS_AND_SOURCES}}
+>
+> **Do this:**
+> 1. Re-verify every claim against the **live** source (issue tracker / code host / error monitor /
+>    the repo) - never trust the answer's own summary. Quote the field, line, PR body, or issue you
+>    checked.
+> 2. **Check similar and related issues, and find patterns.** Is this part of a cluster? Is there a
+>    closer sibling, parent epic, or duplicate the answer should have surfaced but did not? Name it
+>    with its ID and the shared signal (same error, same code path, same root cause).
+> 3. Stress-test the **strongest** load-bearing claim and the answer's biggest blind spot
+>    specifically. Where is it over-confident? Where is symptom-level reasoning passing itself off as
+>    a proven root cause?
+> 4. List exactly **where the author was wrong or imprecise**, and what they **missed**.
+> 5. Flag any claim you **could not verify** so it is not presented as fact.
+>
+> **Output, terse, with a receipt for every line:**
+> - `verdict`: AGREE | AGREE-WITH-CAVEATS | DISAGREE
+> - `score`: 0-100 (rubric: 100 = every claim verified, nothing missed, confidence correctly
+>   calibrated; subtract for each unverified claim, each missed sibling or pattern, and each
+>   over- or under-statement)
+> - `where_wrong`: bullet list, each with its source receipt
+> - `missed`: related issues or patterns the author failed to surface, with IDs
+> - `unverifiable`: claims that need a source you do not have
+> - `fixes`: ranked, actionable - what to change to raise the score
+
+## Optional: auto-offer via a Claude Code Stop hook
+
+A hook is a shell command, so it cannot run this loop itself. What it can do is **nudge**: after a
+substantial answer, it offers the review and you run the skill only if the user says yes.
+
+The hook ships with this skill at `scripts/critique-nudge.mjs`. Register it as a `Stop` hook in your
+Claude Code settings (`.claude/settings.json` for a team, `.claude/settings.local.json` for
+yourself):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/critique-nudge.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy `scripts/critique-nudge.mjs` to `.claude/hooks/critique-nudge.mjs` (or point the command at
+wherever you keep it). After an answer whose final prose is at least 1500 characters, the hook blocks
+the turn once and instructs the agent to append a one-line "critical-thinking review" offer, then
+stop. Two loop guards keep it from firing forever: it does nothing when `stop_hook_active` is set, and
+nothing when the answer already contains the offer phrase. On any malformed input it exits silently
+and never blocks the user.
+
+The 1500-character threshold is a heuristic with a known ceiling: it misses short but dense
+tool-heavy turns. If that matters, extend the script to also count tool calls since the last user
+message.
+
+## Notes
+
+- One critic round is fine and common. If the answer was already solid, report
+  `iterations: 1, no revision needed` and the single score rather than forcing a revision.
+- Diversity beats redundancy: if a claim can fail in more than one way, give the critic distinct
+  lenses (correctness, completeness, does-it-reproduce) instead of repeating the same check.
+- The critic verifies against live sources; it does not rewrite the answer. You revise; it re-scores.

package/packages/software-development/self-critique/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-self-critique",
+  "description": "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score.",
+  "skills": "./skills"
+}

package/packages/software-development/self-critique/adapters/claude/skills/self-critique/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: self-critique
+description: Adversarially critique your own last substantial answer before the user has to. Spawn a critic agent that verifies every claim against live sources, checks similar and related issues, finds patterns, and addresses comments directly to you. Loop (revise, re-score) until satisfied, then report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score. Use when the user asks you to criticize, challenge, stress-test, or red-team your own answer, or accepts a "critical-thinking review" offer.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - critical-thinking
+    - self-review
+    - verification
+    - adversarial
+    - agents
+    - quality
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Self-critique
+
+Run an adversarial review of **your own previous answer** and report the result in numbers.
+
+## Overview
+
+A confident answer is not a verified one. This skill turns your last substantial reply into the
+subject of a hostile review: a separate critic agent tries to refute it against live sources, hunts
+for the related issue or pattern you missed, and scores it. You then revise and re-score until the
+score stops moving, and report the outcome honestly, including where you were wrong.
+
+The point is to surface error before the user does, and to make "is this actually right?" a measured
+quantity instead of a vibe.
+
+## When to Use
+
+- The user asks you to criticize, challenge, stress-test, red-team, or "poke holes in" your own answer.
+- The user accepts a "critical-thinking review" offer.
+- You have just produced a substantial analysis, recommendation, or investigation and want a
+  confidence number before the user acts on it.
+
+Do not use for trivial one-shot replies or simple chat. The overhead only pays off on load-bearing
+answers.
+
+## Procedure
+
+1. **Snapshot the target.** Capture your last substantial answer verbatim, plus the concrete claims
+   it makes and the source each claim rests on. This is `v1`.
+
+2. **Spawn the critic.** Launch one independent agent with live-source access (issue tracker, code
+   host, error monitor, the repo). Use the prompt template below. The critic must return: `score`
+   (0-100), `verdict` (AGREE / AGREE-WITH-CAVEATS / DISAGREE), `where_wrong` (list), `missed`
+   (related issues or patterns you failed to surface), `unverifiable` (claims it could not confirm),
+   and `fixes` (ranked, actionable).
+
+3. **Decide and loop.** Stop if `score >= 90` OR no actionable `fixes` remain. Otherwise revise the
+   answer using the fixes to produce `v2`, then re-spawn the critic to score `v2`. Repeat.
+   **Hard cap: 3 critic rounds.** (A known ceiling: raise it only if a round is still finding real,
+   fixable defects.)
+
+4. **Report, always, even after a single round:**
+   - **Where you were wrong** - consolidated, each item with the receipt the critic cited.
+   - **Iterations to satisfy** - how many critic rounds it took to reach the stop condition (1 means
+     it was solid on the first pass).
+   - **Improvement in numbers** - the score trajectory, for example `72 -> 88 -> 94 (+22 pts, +31%)`.
+     If only one round ran, state `no revision needed`.
+   - **Final score** - the critic's last score and verdict.
+   - **Unverifiable** - anything you should not present as fact.
+
+## Critic prompt template
+
+Pass this to the critic agent, filling in the two placeholders. It is deliberately adversarial:
+the default stance is that the answer is wrong until a live source proves otherwise.
+
+> You are an adversarial reviewer. Your job is to verify and, where possible, **refute** the answer
+> below. Default to skepticism: assume a claim is wrong until a live source proves it. Address every
+> comment **directly to the author** ("You claimed X; the source says Y").
+>
+> **The answer under review (verbatim):**
+> {{ANSWER}}
+>
+> **Its claims and the source each rests on:**
+> {{CLAIMS_AND_SOURCES}}
+>
+> **Do this:**
+> 1. Re-verify every claim against the **live** source (issue tracker / code host / error monitor /
+>    the repo) - never trust the answer's own summary. Quote the field, line, PR body, or issue you
+>    checked.
+> 2. **Check similar and related issues, and find patterns.** Is this part of a cluster? Is there a
+>    closer sibling, parent epic, or duplicate the answer should have surfaced but did not? Name it
+>    with its ID and the shared signal (same error, same code path, same root cause).
+> 3. Stress-test the **strongest** load-bearing claim and the answer's biggest blind spot
+>    specifically. Where is it over-confident? Where is symptom-level reasoning passing itself off as
+>    a proven root cause?
+> 4. List exactly **where the author was wrong or imprecise**, and what they **missed**.
+> 5. Flag any claim you **could not verify** so it is not presented as fact.
+>
+> **Output, terse, with a receipt for every line:**
+> - `verdict`: AGREE | AGREE-WITH-CAVEATS | DISAGREE
+> - `score`: 0-100 (rubric: 100 = every claim verified, nothing missed, confidence correctly
+>   calibrated; subtract for each unverified claim, each missed sibling or pattern, and each
+>   over- or under-statement)
+> - `where_wrong`: bullet list, each with its source receipt
+> - `missed`: related issues or patterns the author failed to surface, with IDs
+> - `unverifiable`: claims that need a source you do not have
+> - `fixes`: ranked, actionable - what to change to raise the score
+
+## Optional: auto-offer via a Claude Code Stop hook
+
+A hook is a shell command, so it cannot run this loop itself. What it can do is **nudge**: after a
+substantial answer, it offers the review and you run the skill only if the user says yes.
+
+The hook ships with this skill at `scripts/critique-nudge.mjs`. Register it as a `Stop` hook in your
+Claude Code settings (`.claude/settings.json` for a team, `.claude/settings.local.json` for
+yourself):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/critique-nudge.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy `scripts/critique-nudge.mjs` to `.claude/hooks/critique-nudge.mjs` (or point the command at
+wherever you keep it). After an answer whose final prose is at least 1500 characters, the hook blocks
+the turn once and instructs the agent to append a one-line "critical-thinking review" offer, then
+stop. Two loop guards keep it from firing forever: it does nothing when `stop_hook_active` is set, and
+nothing when the answer already contains the offer phrase. On any malformed input it exits silently
+and never blocks the user.
+
+The 1500-character threshold is a heuristic with a known ceiling: it misses short but dense
+tool-heavy turns. If that matters, extend the script to also count tool calls since the last user
+message.
+
+## Notes
+
+- One critic round is fine and common. If the answer was already solid, report
+  `iterations: 1, no revision needed` and the single score rather than forcing a revision.
+- Diversity beats redundancy: if a claim can fail in more than one way, give the critic distinct
+  lenses (correctness, completeness, does-it-reproduce) instead of repeating the same check.
+- The critic verifies against live sources; it does not rewrite the answer. You revise; it re-scores.

package/packages/software-development/self-critique/adapters/claude/skills/self-critique/scripts/critique-nudge.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Stop hook: after a substantial answer, make the model offer the user a
+// critical-thinking review (adversarial critic agent, per the /self-critique skill).
+// The hook only NUDGES. It cannot spawn agents or run the loop itself.
+//
+// ponytail: "substantial" = final assistant prose >= THRESHOLD chars. Known ceiling:
+// misses short-but-dense tool-heavy turns. Upgrade path: also count tool_use blocks
+// since the last user message if length alone misfires.
+import { readFileSync } from 'node:fs';
+
+const THRESHOLD = 1500;
+const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
+
+function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
+
+let raw = '';
+try { raw = readFileSync(0, 'utf8'); } catch { bail(); }
+
+let input;
+try { input = JSON.parse(raw); } catch { bail(); }
+
+// Loop guard #1: if this hook already forced a continuation, let the turn end.
+if (input.stop_hook_active) bail();
+
+const path = input.transcript_path;
+if (!path) bail();
+
+let lines;
+try { lines = readFileSync(path, 'utf8').trim().split('\n'); } catch { bail(); }
+
+// Walk from the end; grab the final assistant message that has text content.
+let text = '';
+for (let i = lines.length - 1; i >= 0; i--) {
+  let obj;
+  try { obj = JSON.parse(lines[i]); } catch { continue; }
+  const msg = obj.message;
+  if (obj.type === 'assistant' && msg && Array.isArray(msg.content)) {
+    text = msg.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+    if (text.trim()) break;
+  }
+}
+
+if (text.length < THRESHOLD) bail();
+
+// Loop guard #2: the answer already carries the offer (e.g. I added it last turn).
+if (OFFER_MARKER.test(text)) bail();
+
+const reason =
+  'That was a substantial answer. Before ending the turn, append exactly ONE short line ' +
+  'offering the user a "critical-thinking review": ask whether they want you to run /self-critique ' +
+  '(spawn an adversarial critic agent that challenges this answer, checks similar issues, finds ' +
+  'patterns, and reports where you were wrong, iterations-to-satisfy, the numeric improvement, and a ' +
+  'final score). The offer line MUST contain the phrase "critical-thinking review". Do NOT run the ' +
+  'critique now and do not re-explain the answer. Just offer it, then stop.';
+
+process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+bail();

package/packages/software-development/self-critique/adapters/codex/README.md

@@ -0,0 +1,21 @@
+# Codex Adapter for self-critique
+
+This is a Codex-specific adapter for the `olko:self-critique` skill.
+The canonical skill definition is in `../../../SKILL.md`.
+
+## Usage
+
+Invoke in a Codex session:
+
+```
+Use the olko:self-critique skill to adversarially review your last answer and report a confidence score.
+```
+
+## Workflow
+
+See `../../../SKILL.md` for the full workflow: spawn a critic agent, verify every claim against live
+sources, find the related issue or pattern you missed, then loop (revise, re-score) until satisfied
+and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score.
+
+The optional Claude Code `Stop` hook (`scripts/critique-nudge.mjs`) is Claude-specific and does not
+apply to Codex; the skill procedure itself is agent-agnostic.

package/packages/software-development/self-critique/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:self-critique",
+  "version": "0.1.0",
+  "description": "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score.",
+  "skills": "skills/"
+}

package/packages/software-development/self-critique/adapters/cursor/skills/self-critique/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: self-critique
+description: Adversarially critique your own last substantial answer before the user has to. Spawn a critic agent that verifies every claim against live sources, checks similar and related issues, finds patterns, and addresses comments directly to you. Loop (revise, re-score) until satisfied, then report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score. Use when the user asks you to criticize, challenge, stress-test, or red-team your own answer, or accepts a "critical-thinking review" offer.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools.
+metadata:
+  targets: ["cursor"]
+  author: Oleg Koval
+  tags:
+    - critical-thinking
+    - self-review
+    - verification
+    - adversarial
+    - agents
+    - quality
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Self-critique
+
+Run an adversarial review of **your own previous answer** and report the result in numbers.
+
+## Overview
+
+A confident answer is not a verified one. This skill turns your last substantial reply into the
+subject of a hostile review: a separate critic agent tries to refute it against live sources, hunts
+for the related issue or pattern you missed, and scores it. You then revise and re-score until the
+score stops moving, and report the outcome honestly, including where you were wrong.
+
+The point is to surface error before the user does, and to make "is this actually right?" a measured
+quantity instead of a vibe.
+
+## When to Use
+
+- The user asks you to criticize, challenge, stress-test, red-team, or "poke holes in" your own answer.
+- The user accepts a "critical-thinking review" offer.
+- You have just produced a substantial analysis, recommendation, or investigation and want a
+  confidence number before the user acts on it.
+
+Do not use for trivial one-shot replies or simple chat. The overhead only pays off on load-bearing
+answers.
+
+## Procedure
+
+1. **Snapshot the target.** Capture your last substantial answer verbatim, plus the concrete claims
+   it makes and the source each claim rests on. This is `v1`.
+
+2. **Spawn the critic.** Launch one independent agent with live-source access (issue tracker, code
+   host, error monitor, the repo). Use the prompt template below. The critic must return: `score`
+   (0-100), `verdict` (AGREE / AGREE-WITH-CAVEATS / DISAGREE), `where_wrong` (list), `missed`
+   (related issues or patterns you failed to surface), `unverifiable` (claims it could not confirm),
+   and `fixes` (ranked, actionable).
+
+3. **Decide and loop.** Stop if `score >= 90` OR no actionable `fixes` remain. Otherwise revise the
+   answer using the fixes to produce `v2`, then re-spawn the critic to score `v2`. Repeat.
+   **Hard cap: 3 critic rounds.** (A known ceiling: raise it only if a round is still finding real,
+   fixable defects.)
+
+4. **Report, always, even after a single round:**
+   - **Where you were wrong** - consolidated, each item with the receipt the critic cited.
+   - **Iterations to satisfy** - how many critic rounds it took to reach the stop condition (1 means
+     it was solid on the first pass).
+   - **Improvement in numbers** - the score trajectory, for example `72 -> 88 -> 94 (+22 pts, +31%)`.
+     If only one round ran, state `no revision needed`.
+   - **Final score** - the critic's last score and verdict.
+   - **Unverifiable** - anything you should not present as fact.
+
+## Critic prompt template
+
+Pass this to the critic agent, filling in the two placeholders. It is deliberately adversarial:
+the default stance is that the answer is wrong until a live source proves otherwise.
+
+> You are an adversarial reviewer. Your job is to verify and, where possible, **refute** the answer
+> below. Default to skepticism: assume a claim is wrong until a live source proves it. Address every
+> comment **directly to the author** ("You claimed X; the source says Y").
+>
+> **The answer under review (verbatim):**
+> {{ANSWER}}
+>
+> **Its claims and the source each rests on:**
+> {{CLAIMS_AND_SOURCES}}
+>
+> **Do this:**
+> 1. Re-verify every claim against the **live** source (issue tracker / code host / error monitor /
+>    the repo) - never trust the answer's own summary. Quote the field, line, PR body, or issue you
+>    checked.
+> 2. **Check similar and related issues, and find patterns.** Is this part of a cluster? Is there a
+>    closer sibling, parent epic, or duplicate the answer should have surfaced but did not? Name it
+>    with its ID and the shared signal (same error, same code path, same root cause).
+> 3. Stress-test the **strongest** load-bearing claim and the answer's biggest blind spot
+>    specifically. Where is it over-confident? Where is symptom-level reasoning passing itself off as
+>    a proven root cause?
+> 4. List exactly **where the author was wrong or imprecise**, and what they **missed**.
+> 5. Flag any claim you **could not verify** so it is not presented as fact.
+>
+> **Output, terse, with a receipt for every line:**
+> - `verdict`: AGREE | AGREE-WITH-CAVEATS | DISAGREE
+> - `score`: 0-100 (rubric: 100 = every claim verified, nothing missed, confidence correctly
+>   calibrated; subtract for each unverified claim, each missed sibling or pattern, and each
+>   over- or under-statement)
+> - `where_wrong`: bullet list, each with its source receipt
+> - `missed`: related issues or patterns the author failed to surface, with IDs
+> - `unverifiable`: claims that need a source you do not have
+> - `fixes`: ranked, actionable - what to change to raise the score
+
+## Optional: auto-offer via a Claude Code Stop hook
+
+A hook is a shell command, so it cannot run this loop itself. What it can do is **nudge**: after a
+substantial answer, it offers the review and you run the skill only if the user says yes.
+
+The hook ships with this skill at `scripts/critique-nudge.mjs`. Register it as a `Stop` hook in your
+Claude Code settings (`.claude/settings.json` for a team, `.claude/settings.local.json` for
+yourself):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/critique-nudge.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy `scripts/critique-nudge.mjs` to `.claude/hooks/critique-nudge.mjs` (or point the command at
+wherever you keep it). After an answer whose final prose is at least 1500 characters, the hook blocks
+the turn once and instructs the agent to append a one-line "critical-thinking review" offer, then
+stop. Two loop guards keep it from firing forever: it does nothing when `stop_hook_active` is set, and
+nothing when the answer already contains the offer phrase. On any malformed input it exits silently
+and never blocks the user.
+
+The 1500-character threshold is a heuristic with a known ceiling: it misses short but dense
+tool-heavy turns. If that matters, extend the script to also count tool calls since the last user
+message.
+
+## Notes
+
+- One critic round is fine and common. If the answer was already solid, report
+  `iterations: 1, no revision needed` and the single score rather than forcing a revision.
+- Diversity beats redundancy: if a claim can fail in more than one way, give the critic distinct
+  lenses (correctness, completeness, does-it-reproduce) instead of repeating the same check.
+- The critic verifies against live sources; it does not rewrite the answer. You revise; it re-scores.

package/packages/software-development/self-critique/adapters/cursor/skills/self-critique/scripts/critique-nudge.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Stop hook: after a substantial answer, make the model offer the user a
+// critical-thinking review (adversarial critic agent, per the /self-critique skill).
+// The hook only NUDGES. It cannot spawn agents or run the loop itself.
+//
+// ponytail: "substantial" = final assistant prose >= THRESHOLD chars. Known ceiling:
+// misses short-but-dense tool-heavy turns. Upgrade path: also count tool_use blocks
+// since the last user message if length alone misfires.
+import { readFileSync } from 'node:fs';
+
+const THRESHOLD = 1500;
+const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
+
+function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
+
+let raw = '';
+try { raw = readFileSync(0, 'utf8'); } catch { bail(); }
+
+let input;
+try { input = JSON.parse(raw); } catch { bail(); }
+
+// Loop guard #1: if this hook already forced a continuation, let the turn end.
+if (input.stop_hook_active) bail();
+
+const path = input.transcript_path;
+if (!path) bail();
+
+let lines;
+try { lines = readFileSync(path, 'utf8').trim().split('\n'); } catch { bail(); }
+
+// Walk from the end; grab the final assistant message that has text content.
+let text = '';
+for (let i = lines.length - 1; i >= 0; i--) {
+  let obj;
+  try { obj = JSON.parse(lines[i]); } catch { continue; }
+  const msg = obj.message;
+  if (obj.type === 'assistant' && msg && Array.isArray(msg.content)) {
+    text = msg.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+    if (text.trim()) break;
+  }
+}
+
+if (text.length < THRESHOLD) bail();
+
+// Loop guard #2: the answer already carries the offer (e.g. I added it last turn).
+if (OFFER_MARKER.test(text)) bail();
+
+const reason =
+  'That was a substantial answer. Before ending the turn, append exactly ONE short line ' +
+  'offering the user a "critical-thinking review": ask whether they want you to run /self-critique ' +
+  '(spawn an adversarial critic agent that challenges this answer, checks similar issues, finds ' +
+  'patterns, and reports where you were wrong, iterations-to-satisfy, the numeric improvement, and a ' +
+  'final score). The offer line MUST contain the phrase "critical-thinking review". Do NOT run the ' +
+  'critique now and do not re-explain the answer. Just offer it, then stop.';
+
+process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+bail();

package/packages/software-development/self-critique/scripts/critique-nudge.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Stop hook: after a substantial answer, make the model offer the user a
+// critical-thinking review (adversarial critic agent, per the /self-critique skill).
+// The hook only NUDGES. It cannot spawn agents or run the loop itself.
+//
+// ponytail: "substantial" = final assistant prose >= THRESHOLD chars. Known ceiling:
+// misses short-but-dense tool-heavy turns. Upgrade path: also count tool_use blocks
+// since the last user message if length alone misfires.
+import { readFileSync } from 'node:fs';
+
+const THRESHOLD = 1500;
+const OFFER_MARKER = /critical-thinking review/i; // the offer line must contain this; doubles as a loop guard
+
+function bail() { process.exit(0); } // any uncertainty => do nothing, never block the user
+
+let raw = '';
+try { raw = readFileSync(0, 'utf8'); } catch { bail(); }
+
+let input;
+try { input = JSON.parse(raw); } catch { bail(); }
+
+// Loop guard #1: if this hook already forced a continuation, let the turn end.
+if (input.stop_hook_active) bail();
+
+const path = input.transcript_path;
+if (!path) bail();
+
+let lines;
+try { lines = readFileSync(path, 'utf8').trim().split('\n'); } catch { bail(); }
+
+// Walk from the end; grab the final assistant message that has text content.
+let text = '';
+for (let i = lines.length - 1; i >= 0; i--) {
+  let obj;
+  try { obj = JSON.parse(lines[i]); } catch { continue; }
+  const msg = obj.message;
+  if (obj.type === 'assistant' && msg && Array.isArray(msg.content)) {
+    text = msg.content.filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+    if (text.trim()) break;
+  }
+}
+
+if (text.length < THRESHOLD) bail();
+
+// Loop guard #2: the answer already carries the offer (e.g. I added it last turn).
+if (OFFER_MARKER.test(text)) bail();
+
+const reason =
+  'That was a substantial answer. Before ending the turn, append exactly ONE short line ' +
+  'offering the user a "critical-thinking review": ask whether they want you to run /self-critique ' +
+  '(spawn an adversarial critic agent that challenges this answer, checks similar issues, finds ' +
+  'patterns, and reports where you were wrong, iterations-to-satisfy, the numeric improvement, and a ' +
+  'final score). The offer line MUST contain the phrase "critical-thinking review". Do NOT run the ' +
+  'critique now and do not re-explain the answer. Just offer it, then stop.';
+
+process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+bail();