Add swarm plugin scaffold with backend adapter layer (P1)

.claude-plugin/marketplace.json

@@ -25,6 +25,12 @@
       "source": "./plugins/pr-flow",
       "description": "PR review feedback loop for Claude Code. Create PRs with readiness checks, commit + push + trigger @claude review, inspect status, and work through review issues interactively.",
       "version": "1.2.2"
+    },
+    {
+      "name": "swarm",
+      "source": "./plugins/swarm",
+      "description": "Local mixture-of-agents code review for Claude Code. Will fan out to Claude subagents plus codex and grok CLIs, merge and verify findings into one ranked report. Phase 1 ships the backend adapter and /swarm:agents status.",
+      "version": "0.1.0"
     }
   ]
 }

.claude/knowledge/_index.md

@@ -13,6 +13,7 @@
 - `features/herdr-kickoff-automation.md` — herdr `herdr-launch.sh`: `launch` (`/kickoff`) + `resume` (`/continue <task>` reopens an `/exit`-closed tab)
 - `features/herdr-close-automation.md` — `/close` in herdr: cwd-tab teardown, plugin SessionEnd hook, the one TUI-exit primitive, detached self-exit onto idle
 - `features/task-archiving-on-close.md` — `/close` archives (not deletes) the task file; adaptive commit + ff-push to main
+- `features/swarm-backend-adapter.md` — Verified codex/grok CLI facts (schema-enforced JSON, effort mapping, stdin hang) behind `swarm`'s adapter script
 
 ## Deployment
 - `deployment/ci-structure-checks.md` — `check-structure.py` as the single automated guard for a build-less repo

.claude/knowledge/features/swarm-backend-adapter.md

@@ -0,0 +1,63 @@
+---
+title: "Swarm Backend Adapter Layer"
+createdAt: 2026-07-02
+updatedAt: 2026-07-02
+createdFrom: "branch: task/add-swarm-plugin"
+updatedFrom: "branch: task/add-swarm-plugin"
+pluginVersion: 1.8.2
+prime: false
+---
+
+# Swarm Backend Adapter Layer
+
+The `swarm` plugin reviews locally with a mixture-of-agents ensemble: Claude
+subagents plus the external `codex` and `grok` CLIs. All deterministic backend
+logic lives in one script — `plugins/swarm/scripts/agents.sh` (verbs: `list`,
+`available`, `ready`, `run`) — so skills never call an external CLI directly.
+The script header documents the per-backend mechanics; this entry captures the
+*verified* CLI behavior the adapter is built on and the gotchas that cost a
+debugging round.
+
+## Verified CLI facts (codex 0.128 / grok 0.2.77, 2026-07)
+
+- **Uniform findings JSON** is achievable from both CLIs: `codex exec
+  --output-schema <file>` and `grok --json-schema '<inline>'` both enforce a
+  JSON Schema on the final answer. One bundled schema
+  (`scripts/schema/finding.schema.json`) feeds both — the ensemble merge never
+  parses free-form review prose. In strict structured-output modes all
+  properties must be `required`, so the schema requires every field and uses
+  honest defaults (`line: 0`, self-reported `confidence`) instead of optionals.
+- **Where the JSON lands differs per CLI**: codex writes the pure JSON via
+  `--output-last-message <file>` (stdout carries the agent transcript,
+  stderr the progress log); grok prints a response **envelope** on stdout —
+  the validated object is its `.structuredOutput` field.
+- **grok's default model rejects `--effort`** (`grok-composer-2.5-fast` errors
+  with "does not support parameter reasoningEffort"). The adapter must pin
+  `-m grok-build`. grok's effort ladder (low…max) matches code-review's;
+  codex has no `max` tier → map `max`→`xhigh` (`-c model_reasoning_effort=…`).
+- **`grok-composer-2.5-fast` also does not enforce `--json-schema`**: it
+  returns plain text with `structuredOutput: null` +
+  `structuredOutputError: "model output was not valid JSON"`. So it cannot
+  serve as a second grok ensemble voice (besides being same-family-correlated,
+  which would dilute the ≥2-backend consensus signal). `grok-build` is the
+  only schema-capable grok model; for "more grok" at high effort, prefer its
+  native `--best-of-n N` over a second model voice.
+- **Headless tool execution**: both CLIs run read-only commands (e.g.
+  `git diff`) without extra approval flags — codex inside `-s read-only`
+  sandbox, grok headless `-p` auto-approves read-only tools. So lens prompts
+  may either inline the diff or instruct the agent to read it itself.
+
+## Gotchas (found in E2E testing, fixed in the adapter)
+
+- **codex hangs on inherited stdin.** With an open non-TTY stdin, `codex exec`
+  waits for "additional input from stdin" *in addition to* the positional
+  prompt — in a background shell this hangs forever. Always call it with
+  `</dev/null` (the adapter does).
+- **`set -u` + EXIT trap + `local`**: a trap like `trap 'rm -f "$out"' EXIT`
+  referencing a function-`local` variable fires after the function returned —
+  under `set -u` the script then dies with "unbound variable" and **exit 1
+  despite a fully successful run** (a pipeline would misread the backend as
+  failed). Keep trap-referenced temp paths global.
+- **Exit-code discipline matters** because the ensemble treats non-zero `run`
+  as "backend dropped": stdout must stay pure findings-JSON (all CLI noise to
+  stderr or /dev/null), and success must exit 0.

CLAUDE.md

@@ -21,6 +21,7 @@ This is a **Claude Code plugin marketplace** (monorepo) containing plugins that
 - **knowledge-system** (v1.5.x) — Knowledge management with three layers: Rules, Knowledge, Memory. Skills: `/init`, `/query`, `/curate`, `/reindex`, `/backfill-knowledge`, `/migrate`, `/statusline`
 - **work-system** (v1.2.x) — Task and worktree workflow. Skills: `/define`, `/kickoff`, `/adopt`, `/continue`, `/status`, `/close`, `/list`
 - **pr-flow** (v1.1.x) — PR review feedback loop. Skills: `/open`, `/cycle`, `/check`, `/fix`, `/rebase`, `/merge`
+- **swarm** (v0.1.x) — Local mixture-of-agents code review (external `codex`/`grok` CLIs + Claude subagents). P1: backend adapter + status. Skills: `/swarm:agents`
 
 ## Plugin Anatomy
 

README.md

@@ -28,6 +28,14 @@ PR review feedback loop. Create PRs with readiness checks, commit + push + trigg
 
 [Documentation →](plugins/pr-flow/)
 
+### Swarm
+
+Local mixture-of-agents code review. Fans out one review across Claude subagents plus the `codex` and `grok` CLIs, merges and verifies their findings, and presents a single ranked report — before anything is pushed. Complementary to PR Flow's GitHub-side loop. *(Phase 1: scaffold + backend adapter.)*
+
+**Commands:** `/swarm:agents` *(more to come: `/swarm:review`, `/swarm:adversarial`, `/swarm:style`, `/swarm:security`)*
+
+[Documentation →](plugins/swarm/)
+
 ## Installation
 
 ### 1. Add the marketplace
@@ -42,6 +50,7 @@ PR review feedback loop. Create PRs with readiness checks, commit + push + trigg
 /plugin install knowledge-system
 /plugin install work-system
 /plugin install pr-flow
+/plugin install swarm
 ```
 
 ### 3. Reload plugins

plugins/swarm/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "swarm",
+  "description": "Local mixture-of-agents code review for Claude Code. Will fan out to Claude subagents plus codex and grok CLIs, merge and verify findings into one ranked report. Phase 1 ships the backend adapter and /swarm:agents status.",
+  "version": "0.1.0",
+  "author": {
+    "name": "gering"
+  },
+  "repository": "https://github.com/gering/claude-plugins",
+  "license": "MIT",
+  "keywords": ["review", "code-review", "multi-agent", "ensemble", "codex", "grok"]
+}

plugins/swarm/README.md

@@ -0,0 +1,82 @@
+# Swarm
+
+Local mixture-of-agents code review for Claude Code. Fans out one review
+across multiple independent agents — Claude subagents plus the `codex` and
+`grok` CLIs — merges and deduplicates their findings, and presents a single
+ranked report. Cross-agent agreement is a strong confidence signal when it
+occurs; single-agent findings (the common case) pass an adversarial 3-state
+verifier so real catches survive and noise is dropped.
+
+Complementary to [pr-flow](../pr-flow/): pr-flow drives the GitHub-PR
+`@claude`-bot loop; swarm reviews **locally**, before anything is pushed.
+
+## Status
+
+**Phase 1 of 6** — plugin scaffold + backend adapter layer. The review
+pipeline (`/swarm:review`) lands in later phases.
+
+## Commands
+
+- `/swarm:agents` — show which review backends are installed, authenticated,
+  and ready.
+
+Planned: `/swarm:review` (main command), `/swarm:adversarial`, `/swarm:style`,
+`/swarm:security` (thin lens presets).
+
+## Architecture
+
+### Backend adapter (`scripts/agents.sh`)
+
+All deterministic backend logic lives in one script; skills never call the
+external CLIs directly:
+
+```
+agents.sh list [--json]       # probe all backends → status table / JSON
+agents.sh available <backend> # installed? prints version
+agents.sh ready <backend>     # authenticated? hint on stderr if not
+agents.sh run <backend> [--prompt-file f] [--effort E] [--model M] [--schema f]
+                              # lens prompt in → findings JSON out
+```
+
+Backends:
+
+| Backend | Role | Mechanics |
+|---------|------|-----------|
+| `claude` | probe-only | reviews run in-session via the Agent tool |
+| `codex` | external reviewer | `codex exec --output-schema` in a read-only sandbox; auth via `codex login status` |
+| `grok` | external reviewer | headless `-p` with inline `--json-schema`; findings extracted from the response envelope |
+
+Unavailable backends drop silently from the ensemble — `claude` alone still
+works.
+
+### Shared findings schema (`scripts/schema/finding.schema.json`)
+
+Both external CLIs enforce the same JSON schema on their output, so the
+ensemble merge receives uniform findings:
+
+```json
+{
+  "findings": [
+    {
+      "file": "scripts/foo.sh",
+      "line": 42,
+      "severity": "warning",
+      "summary": "One-sentence statement of the defect",
+      "failure_scenario": "Concrete, falsifiable inputs → wrong behavior",
+      "confidence": "high",
+      "recommendation": "Suggested fix"
+    }
+  ]
+}
+```
+Severity is one of `critical | warning | minor`; confidence one of
+`high | medium | low`.
+
+`failure_scenario` is required and must be falsifiable — it is what the
+verifier tests in the confidence phase.
+
+## Requirements
+
+- `python3` on PATH (JSON handling in the adapter).
+- `codex` and/or `grok` CLIs are optional — install and authenticate them to
+  widen the ensemble.