@iceinvein/agent-skills 0.1.34 → 0.1.36

package/skills/index.json

@@ -1,9 +1,9 @@
 [
   {
     "name": "bounded-context-auditor",
-    "description": "Evans-inspired bounded context analysis — detect linguistic fractures, draw context maps, identify leaking language and shared model pollution",
+    "description": "Evans-inspired bounded context analysis: detect linguistic fractures, draw context maps, identify leaking language and shared model pollution",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "domain"
     ],
@@ -22,9 +22,9 @@
   },
   {
     "name": "cognitive-load-auditor",
-    "description": "Jeff Johnson-inspired cognitive load analysis — evaluate UI against Miller's Law, Hick's Law, Fitts's Law, and working memory limits",
+    "description": "Jeff Johnson-inspired cognitive load analysis: evaluate UI against Miller's Law, Hick's Law, Fitts's Law, and working memory limits",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "ui"
     ],
@@ -32,9 +32,9 @@
   },
   {
     "name": "cohesion-analyzer",
-    "description": "Constantine & Yourdon-inspired cohesion analysis — classify module focus on the 7-level spectrum, find split lines, reduce mixed responsibilities",
+    "description": "Constantine & Yourdon-inspired cohesion analysis: classify module focus on the 7-level spectrum, find split lines, reduce mixed responsibilities",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -42,9 +42,9 @@
   },
   {
     "name": "complexity-accountant",
-    "description": "Ousterhout-inspired complexity analysis — deep vs shallow modules, complexity budget, justified abstractions",
+    "description": "Ousterhout-inspired complexity analysis: deep vs shallow modules, complexity budget, justified abstractions",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -52,9 +52,9 @@
   },
   {
     "name": "composability-auditor",
-    "description": "Unix Philosophy-inspired composability analysis — identify reuse blockers, decompose self-sufficient units into composable pieces with standard interfaces",
+    "description": "Unix Philosophy-inspired composability analysis: identify reuse blockers, decompose self-sufficient units into composable pieces with standard interfaces",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -62,9 +62,9 @@
   },
   {
     "name": "contract-enforcer",
-    "description": "Meyer-inspired Design by Contract — preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
+    "description": "Meyer-inspired Design by Contract: preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -72,19 +72,49 @@
   },
   {
     "name": "coupling-auditor",
-    "description": "Constantine & Yourdon-inspired coupling analysis — classify, measure, and reduce interdependence between modules",
+    "description": "Constantine & Yourdon-inspired coupling analysis: classify, measure, and reduce interdependence between modules",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
     "quick": true
   },
+  {
+    "name": "cover-letter",
+    "description": "Cover letter suite router. Dispatches to write, audit, rewrite, or persona subcommands and shares file I/O (PDF, DOCX, MD/MDX, URL), output formats, and writing conventions across the suite",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "cover-letter-audit",
+    "description": "Scores a cover letter on 100 points across content/fit, structure, voice/humanness, and correctness; detects AI-generated-content signals and produces a prioritized fix list",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "cover-letter-persona",
+    "description": "Reusable writing personas built on the NNGroup 4-dimension tone framework, adapted for professional correspondence and used by cover-letter-write and cover-letter-rewrite",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "cover-letter-rewrite",
+    "description": "Audit-driven targeted rewrite of an existing cover letter. Focus modes: humanize, align, tighten, structure, tone; preserves voice where it already works",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "cover-letter-write",
+    "description": "Generates a cover letter from a resume and job description. Outputs markdown, DOCX, and PDF; enforces human prose, maps every claim to a resume bullet, and covers top JD requirements without keyword stuffing",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
   {
     "name": "cqs-auditor",
-    "description": "Meyer-inspired Command-Query Separation — classify functions as commands or queries, detect mixed violations, separate side effects from return values",
+    "description": "Meyer-inspired Command-Query Separation: classify functions as commands or queries, detect mixed violations, separate side effects from return values",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -92,9 +122,9 @@
   },
   {
     "name": "demeter-enforcer",
-    "description": "Lieberherr-inspired Law of Demeter analysis — detect chain violations, parameter drilling, and hidden traversal; fix with tell-don't-ask or parameter narrowing",
+    "description": "Lieberherr-inspired Law of Demeter analysis: detect chain violations, parameter drilling, and hidden traversal; fix with tell-don't-ask or parameter narrowing",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -102,9 +132,9 @@
   },
   {
     "name": "dependency-direction-auditor",
-    "description": "Martin-inspired dependency direction analysis — trace imports across layers, classify violations by severity, recommend inversion",
+    "description": "Martin-inspired dependency direction analysis: trace imports across layers, classify violations by severity, recommend inversion",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -112,9 +142,9 @@
   },
   {
     "name": "design-review",
-    "description": "Brooks-inspired design integrity review — tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
+    "description": "Brooks-inspired design integrity review: tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -122,9 +152,9 @@
   },
   {
     "name": "error-strategist",
-    "description": "Duffy & Abrahams-inspired error handling — classify errors (bug/recoverable/fatal), assign safety guarantees, design recovery boundaries",
+    "description": "Duffy & Abrahams-inspired error handling: classify errors (bug/recoverable/fatal), assign safety guarantees, design recovery boundaries",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "errors"
     ],
@@ -132,9 +162,9 @@
   },
   {
     "name": "event-design-reviewer",
-    "description": "Evans/Vernon/Dahan-inspired event design — domain-meaningful naming, fat payloads, schema evolution, and the domain expert test",
+    "description": "Evans/Vernon/Dahan-inspired event design: domain-meaningful naming, fat payloads, schema evolution, and the domain expert test",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "integration",
       "domain"
@@ -143,9 +173,9 @@
   },
   {
     "name": "evolution-analyzer",
-    "description": "Lehman-inspired software evolution analysis — trajectory assessment, debt visibility, and change impact on system health",
+    "description": "Lehman-inspired software evolution analysis: trajectory assessment, debt visibility, and change impact on system health",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -153,9 +183,9 @@
   },
   {
     "name": "gestalt-reviewer",
-    "description": "Gestalt-inspired visual perception audit — proximity, similarity, closure, continuity, and figure-ground analysis for UI layouts",
+    "description": "Gestalt-inspired visual perception audit: proximity, similarity, closure, continuity, and figure-ground analysis for UI layouts",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "ui"
     ],
@@ -163,9 +193,9 @@
   },
   {
     "name": "idempotency-guardian",
-    "description": "Helland-inspired idempotency analysis — classify mutation points, check protection mechanisms, evaluate side effect safety for retry-safe systems",
+    "description": "Helland-inspired idempotency analysis: classify mutation points, check protection mechanisms, evaluate side effect safety for retry-safe systems",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "integration"
     ],
@@ -179,9 +209,9 @@
   },
   {
     "name": "integration-pattern-auditor",
-    "description": "Hohpe & Woolf-inspired messaging analysis — name the integration pattern, verify delivery guarantees, identify missing infrastructure",
+    "description": "Hohpe & Woolf-inspired messaging analysis: name the integration pattern, verify delivery guarantees, identify missing infrastructure",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "integration"
     ],
@@ -189,15 +219,15 @@
   },
   {
     "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",
-    "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
+    "description": "Parnas-inspired information hiding analysis: module boundaries drawn by change-reason, not by noun or technical layer",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -205,9 +235,9 @@
   },
   {
     "name": "port-adapter-auditor",
-    "description": "Cockburn-inspired hexagonal architecture analysis — identify ports and adapters, classify boundary health, ensure core testability and swappability",
+    "description": "Cockburn-inspired hexagonal architecture analysis: identify ports and adapters, classify boundary health, ensure core testability and swappability",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "architecture"
     ],
@@ -215,9 +245,9 @@
   },
   {
     "name": "rams-design-audit",
-    "description": "Dieter Rams-inspired design audit — every visual element must earn its presence, less but better, clarity through restraint",
+    "description": "Dieter Rams-inspired design audit: every visual element must earn its presence, less but better, clarity through restraint",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "ui"
     ],
@@ -225,9 +255,9 @@
   },
   {
     "name": "seam-finder",
-    "description": "Feathers-inspired legacy code modification — find seams, make minimal incisions, preserve existing behavior",
+    "description": "Feathers-inspired legacy code modification: find seams, make minimal incisions, preserve existing behavior",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "legacy"
     ],
@@ -235,9 +265,9 @@
   },
   {
     "name": "simplicity-razor",
-    "description": "Hickey-inspired simplicity analysis — simple vs easy, complecting detection, strand decomposition",
+    "description": "Hickey-inspired simplicity analysis: simple vs easy, complecting detection, strand decomposition",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -245,9 +275,9 @@
   },
   {
     "name": "temporal-coupling-detector",
-    "description": "Hidden ordering dependency analysis — detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",
+    "description": "Hidden ordering dependency analysis: detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -261,9 +291,9 @@
   },
   {
     "name": "type-driven-designer",
-    "description": "Wlaschin & Minsky-inspired type design — make illegal states unrepresentable through branded types, discriminated unions, and domain-encoded constraints",
+    "description": "Wlaschin & Minsky-inspired type design: make illegal states unrepresentable through branded types, discriminated unions, and domain-encoded constraints",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "any"
     ],
@@ -271,9 +301,9 @@
   },
   {
     "name": "unidirectional-flow-enforcer",
-    "description": "Elm Architecture-inspired data flow analysis — enforce unidirectional state flow, detect bidirectional mutations, trace state lifecycle in UI applications",
+    "description": "Elm Architecture-inspired data flow analysis: enforce unidirectional state flow, detect bidirectional mutations, trace state lifecycle in UI applications",
     "type": "prompt",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "applies": [
       "ui"
     ],

package/skills/integration-pattern-auditor/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "integration-pattern-auditor",
-  "version": "1.0.0",
-  "description": "Hohpe & Woolf-inspired messaging analysis — name the integration pattern, verify delivery guarantees, identify missing infrastructure",
+  "version": "1.0.1",
+  "description": "Hohpe & Woolf-inspired messaging analysis: name the integration pattern, verify delivery guarantees, identify missing infrastructure",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

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": [

package/skills/module-secret-auditor/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "module-secret-auditor",
-  "version": "1.0.0",
-  "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
+  "version": "1.0.1",
+  "description": "Parnas-inspired information hiding analysis: module boundaries drawn by change-reason, not by noun or technical layer",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

package/skills/port-adapter-auditor/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "port-adapter-auditor",
-  "version": "1.0.0",
-  "description": "Cockburn-inspired hexagonal architecture analysis — identify ports and adapters, classify boundary health, ensure core testability and swappability",
+  "version": "1.0.1",
+  "description": "Cockburn-inspired hexagonal architecture analysis: identify ports and adapters, classify boundary health, ensure core testability and swappability",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

package/skills/rams-design-audit/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "rams-design-audit",
-  "version": "1.0.0",
-  "description": "Dieter Rams-inspired design audit — every visual element must earn its presence, less but better, clarity through restraint",
+  "version": "1.0.1",
+  "description": "Dieter Rams-inspired design audit: every visual element must earn its presence, less but better, clarity through restraint",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },