@iceinvein/agent-skills 0.1.35 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/index.json

@@ -219,9 +219,9 @@
   },
   {
     "name": "magpie",
-    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
+    "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
     "type": "prompt",
-    "version": "0.5.1"
+    "version": "0.6.0"
   },
   {
     "name": "module-secret-auditor",

package/skills/magpie/README.md

@@ -4,14 +4,14 @@ Interactive Claude Code skill that runs a multi-stage PR review pipeline inside
 
 ## What it does
 
-Given a GitHub PR number, dispatches five specialist subagents in parallel (security, bugs, performance, code-smells, architecture), dedupes their findings, applies a critic rubric, peer-reviews via `codex exec`, serves an interactive HTML report, and posts the findings the user selects via `gh`.
+Given a GitHub PR number, dispatches five specialist subagents in parallel (security, bugs, performance, code-smells, architecture), dedupes their findings, applies a critic rubric, peer-reviews via `codex exec` (falling back to a Claude second-opinion subagent when codex is unavailable), serves an interactive HTML report, and posts the findings the user selects via `gh`.
 
 ## Requirements
 
 - `bun` on PATH (https://bun.sh)
 - `gh` on PATH, authenticated (`gh auth status`)
-- `codex` on PATH, authenticated
 - `git` on PATH
+- `codex` on PATH, authenticated (optional; if absent the peer-review stage falls back to a Claude second-opinion subagent)
 
 ## Install
 

package/skills/magpie/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: magpie
-description: Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Use when the user asks to review a GitHub pull request.
+description: Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Use when the user asks to review a GitHub pull request.
 ---
 
 # Magpie
 
 ## Prerequisites
 
-The skill pre-flights `bun`, `gh`, `codex`, `git`. If any are missing the run aborts with a single install hint line.
+The skill pre-flights `bun`, `gh`, `git` (required) and `codex` (optional). If a required binary is missing the run aborts with a single install hint line. `codex` is the preferred peer reviewer, but it is optional: if it is missing the run continues and the peer-review stage falls back to a Claude second-opinion subagent (setup prints a one-line notice and logs `{stage: preflight, status: done, missingOptional: ["codex"]}`).
 
 ## Stage walkthrough
 
@@ -147,17 +147,23 @@ Read `$RUN_DIR/findings.deduped.json`. Apply the critic rubric from this SKILL.m
 
 ### 6. Peer review
 
-Build the peer-review prompt by taking the `magpie-peer-review` block from this SKILL.md and substituting the placeholders listed in its `## Substitute before use` preamble. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`. Then run codex with the prompt piped on stdin:
+This stage always runs. `codex` is the preferred reviewer because it is a different model from the Claude agents that produced the findings; when `codex` is unavailable, a Claude second-opinion subagent stands in.
+
+Build the peer-review prompt first: take the `magpie-peer-review` block from this SKILL.md and substitute the placeholders listed in its `## Substitute before use` preamble. Write the substituted prompt to `$RUN_DIR/peer-prompt.md`.
+
+**Codex path (preferred).** If `codex` is available (setup did not log `missingOptional: ["codex"]` and `command -v codex` succeeds), set `<<PEER_PROVIDER>>` to `codex` and run codex with the prompt piped on stdin:
 
 ```
 codex exec < "$RUN_DIR/peer-prompt.md" > "$RUN_DIR/peer.out"
 ```
 
-`peer.out` is codex's full transcript; extract the fenced JSON block tagged `review-peer-review` from it to get the verdicts array. Write that verdicts array to `$RUN_DIR/peer.json` for record-keeping.
+`peer.out` is codex's full transcript; extract the fenced JSON block tagged `review-peer-review` from it to get the verdicts array. Write that verdicts array to `$RUN_DIR/peer.json`, append `{stage: peer-review, status: done, provider: codex}`, then apply the verdicts as described below.
+
+If codex returns non-zero, do not abort: fall through to the Claude path and record `{stage: peer-review, provider: codex, status: error}` first.
 
-If codex returns non-zero, ask the user once: "Codex peer-review failed: <stderr>. Skip peer-review and proceed, or abort?". On "skip", copy `findings.kept.json` to `findings.final.json` and add `{stage: peer-review, status: skipped}`.
+**Claude path (fallback).** When `codex` is unavailable or failed, get the second opinion from a Claude subagent instead. Set `<<PEER_PROVIDER>>` to `claude`, then prepend the `magpie-peer-review-claude-preamble` block from this SKILL.md to the substituted peer-review prompt (the preamble forces genuine independence, since the reviewer shares a model family with the primary reviewers). Dispatch one subagent (Agent tool, `general-purpose`) whose entire task is that combined prompt, and instruct it to return only the fenced `review-peer-review` JSON block. Write its output to `$RUN_DIR/peer.out`, extract the `review-peer-review` block to `$RUN_DIR/peer.json`, and append `{stage: peer-review, status: done, provider: claude}`.
 
-Otherwise parse the verdicts JSON, apply them (drop / downgrade), and write `findings.final.json`. Append `{stage: peer-review, status: done}` and re-render progress.
+**Apply the verdicts (both paths).** Parse the verdicts JSON and apply the `update` / `add` entries (an empty array means no change), then write `findings.final.json`. Re-render progress.
 
 ### 7. Report
 
@@ -564,13 +570,9 @@ Output every candidate exactly once. Do not invent ids. Do not output anything o
 
 ## Peer-review prompt
 
-The agent substitutes the placeholders below, writes the result to `<run-dir>/peer-prompt.md`, then runs:
-
-```
-codex exec < <run-dir>/peer-prompt.md > <run-dir>/peer.out
-```
+The agent substitutes the placeholders below and writes the result to `<run-dir>/peer-prompt.md`. Step 6 then feeds that prompt to the peer reviewer: `codex exec < <run-dir>/peer-prompt.md > <run-dir>/peer.out` when codex is available, or a Claude `general-purpose` subagent (with the `magpie-peer-review-claude-preamble` prepended) writing to `<run-dir>/peer.out` when it is not.
 
-Then extract the fenced `review-peer-review` block from `peer.out` and save it to `<run-dir>/peer.json`.
+Either way, extract the fenced `review-peer-review` block from `peer.out` and save it to `<run-dir>/peer.json`.
 
 ## Substitute before use
 
@@ -638,6 +640,18 @@ Rules:
 ```
 ````
 
+## Claude peer-review preamble
+
+Used only by the Claude fallback path in step 6. Prepend this block verbatim (no substitutions) to the substituted `magpie-peer-review` prompt before dispatching the subagent. Its job is to buy back the independence you lose by using the same model family that produced the findings: the reviewer must re-derive each verdict from the diff rather than trusting the finding text, and must actively resist rubber-stamping.
+
+````magpie-peer-review-claude-preamble
+You are a fresh, independent second-opinion reviewer. You have no memory of, and no stake in, how the findings below were produced. They were generated by other agents that share your model family, so they may carry the same blind spots you would: do not defer to them, and do not assume they are correct because they sound confident.
+
+Ground every verdict in the diff hunks provided, not in the prose of the finding. For each finding, independently re-derive whether the described problem is actually present on the cited line before you accept it. If a finding's reasoning does not hold against the hunk, or the anchor is wrong, or the severity is off, say so with "update"; if you can see a clearly actionable adjacent issue in the same hunks that was missed, add it. When the existing finding survives your own check unchanged, leave it alone.
+
+Hold yourself to the exact same output contract and constraints described below. Return [] when the review is already sound.
+````
+
 ## Resuming a crashed run
 
 If the user re-invokes the skill and a `$RUN_DIR/state/server-info` exists:

package/skills/magpie/scripts/__tests__/preflight.test.ts

@@ -10,18 +10,30 @@ test('returns ok when all binaries resolve', async () => {
   })
   expect(result.ok).toBe(true)
   expect(result.missing).toEqual([])
+  expect(result.missingOptional).toEqual([])
 })
 
-test('returns missing list when binaries do not resolve', async () => {
+test('returns missing list when required binaries do not resolve', async () => {
   const result = await preflight({
     bun: 'bun',
     gh: 'definitely-not-a-binary-xyz123',
-    codex: 'also-not-real-abc456',
+    codex: 'echo',
     git: 'git',
   })
   expect(result.ok).toBe(false)
   expect(result.missing).toContain('gh')
-  expect(result.missing).toContain('codex')
+})
+
+test('missing codex is optional and does not abort the run', async () => {
+  const result = await preflight({
+    bun: 'bun',
+    gh: 'echo',
+    codex: 'also-not-real-abc456',
+    git: 'git',
+  })
+  expect(result.ok).toBe(true)
+  expect(result.missing).not.toContain('codex')
+  expect(result.missingOptional).toContain('codex')
 })
 
 test('renderInstallHint produces a single-line message per missing tool', () => {

package/skills/magpie/scripts/__tests__/render-progress.test.ts

@@ -92,7 +92,7 @@ test('each pipeline stage exposes a short sublabel so first-timers can learn wha
   })
   expect(html).toContain('class="hint"')
   expect(html).toContain('five reviewers in parallel')
-  expect(html).toContain('second opinion via codex')
+  expect(html).toContain('independent second opinion')
 })
 
 test('renderProgressHtml includes the archived banner element', () => {

package/skills/magpie/scripts/preflight.ts

@@ -7,10 +7,17 @@ export type Deps = {
 
 export type PreflightResult = {
   ok: boolean
+  /** Required binaries that did not resolve; any entry here aborts the run. */
   missing: string[]
+  /** Optional binaries that did not resolve; these only degrade features, they never abort. */
+  missingOptional: string[]
   resolved: Record<keyof Deps, string | null>
 }
 
+// codex only powers the optional peer-review stage; a missing codex degrades that
+// stage to skipped rather than blocking the whole run.
+const OPTIONAL_DEPS: ReadonlySet<keyof Deps> = new Set<keyof Deps>(['codex'])
+
 export async function preflight(deps: Deps): Promise<PreflightResult> {
   const resolved: Record<keyof Deps, string | null> = {
     bun: Bun.which(deps.bun),
@@ -18,8 +25,12 @@ export async function preflight(deps: Deps): Promise<PreflightResult> {
     codex: Bun.which(deps.codex),
     git: Bun.which(deps.git),
   }
-  const missing = (Object.keys(resolved) as Array<keyof Deps>).filter((k) => resolved[k] === null)
-  return { ok: missing.length === 0, missing, resolved }
+  const unresolved = (Object.keys(resolved) as Array<keyof Deps>).filter(
+    (k) => resolved[k] === null,
+  )
+  const missing = unresolved.filter((k) => !OPTIONAL_DEPS.has(k))
+  const missingOptional = unresolved.filter((k) => OPTIONAL_DEPS.has(k))
+  return { ok: missing.length === 0, missing, missingOptional, resolved }
 }
 
 const HINTS: Record<string, string> = {

package/skills/magpie/scripts/render-progress.ts

@@ -19,7 +19,7 @@ const STAGE_HINT: Record<StageId, string> = {
   specialists: 'five reviewers in parallel',
   dedupe: 'merge overlaps',
   critic: 'keep the high-signal ones',
-  'peer-review': 'second opinion via codex',
+  'peer-review': 'independent second opinion',
   report: 'render this page',
   post: 'comment on the PR',
 }
@@ -30,7 +30,7 @@ const STAGE_NOW_DOING: Record<StageId, string> = {
   specialists: 'Five reviewers reading the diff in parallel',
   dedupe: 'Merging overlapping findings',
   critic: 'Keeping only the high-signal ones',
-  'peer-review': 'Asking a second opinion via codex',
+  'peer-review': 'Getting an independent second opinion',
   report: 'Composing the report page',
   post: 'Ready to post; switch tabs to pick findings',
 }

package/skills/magpie/scripts/setup-cmd.ts

@@ -32,7 +32,18 @@ export async function runSetup(input: RunSetupInput): Promise<number> {
     await cleanup(input.runDir)
     return 3
   }
-  await logLine(input.runDir, { stage: 'preflight', status: 'done' })
+  if (preResult.missingOptional.length > 0) {
+    await logLine(input.runDir, {
+      stage: 'preflight',
+      status: 'done',
+      missingOptional: preResult.missingOptional,
+    })
+    process.stderr.write(
+      `magpie: optional dependency unavailable, some stages will be skipped:\n${renderInstallHint(preResult.missingOptional)}\n`,
+    )
+  } else {
+    await logLine(input.runDir, { stage: 'preflight', status: 'done' })
+  }
 
   const fetched = await fetchPr({
     ghBin: deps.gh,

package/skills/magpie/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "magpie",
-  "version": "0.5.1",
-  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec, and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
+  "version": "0.6.0",
+  "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
   "author": "iceinvein",
   "type": "prompt",
   "tools": [