feat(plugins): DSPy.ts Claude Code / Codex plugin marketplace

.claude-plugin/marketplace.json

@@ -0,0 +1,93 @@
+{
+  "name": "dspy.ts",
+  "metadata": {
+    "version": "0.1.0",
+    "description": "DSPy.ts Claude Code & Codex plugins — program AI systems on AgentDB. From practical (scaffold/compile/eval) to exotic (GEPA self-evolution) plus vertical appliances."
+  },
+  "owner": {
+    "name": "rUv",
+    "url": "https://github.com/ruvnet"
+  },
+  "plugins": [
+    {
+      "name": "dspy-core",
+      "source": "./plugins/dspy-core",
+      "description": "Scaffold, compile (BootstrapFewShot/MIPROv2/GEPA) and evaluate DSPy.ts programs; the `dspy-architect` agent designs signatures, modules and metrics.",
+      "version": "0.1.0",
+      "category": "official",
+      "status": "available"
+    },
+    {
+      "name": "dspy-optimize",
+      "source": "./plugins/dspy-optimize",
+      "description": "Deep optimizer workflows: MIPROv2 + experience replay, GEPA Pareto evolution, BootstrapFewShot dynamic demos; `optimizer-engineer` agent.",
+      "version": "0.1.0",
+      "category": "official",
+      "status": "available"
+    },
+    {
+      "name": "dspy-rag",
+      "source": "./plugins/dspy-rag",
+      "description": "RAG with `RetrieveModule` over AgentDB (HNSW, RaBitQ, MMR) wired into ChainOfThought; `rag-architect` agent; corpus-indexing commands.",
+      "version": "0.1.0",
+      "category": "official",
+      "status": "available"
+    },
+    {
+      "name": "dspy-react",
+      "source": "./plugins/dspy-react",
+      "description": "ReAct agents with tool registries + `ReActReflexion` (recall lessons, record episodes, promote skills); `react-engineer` agent.",
+      "version": "0.1.0",
+      "category": "official",
+      "status": "available"
+    },
+    {
+      "name": "dspy-observability",
+      "source": "./plugins/dspy-observability",
+      "description": "`CompilationTracer` causal-chain traces, AgentDB persistence, optional MLflow; `CachingLM` setup; `observability-engineer` agent.",
+      "version": "0.1.0",
+      "category": "official",
+      "status": "available"
+    },
+    {
+      "name": "dspy-evolution",
+      "source": "./plugins/dspy-evolution",
+      "description": "Exotic: GEPA-driven self-evolution loops that optimize a program's prompts (and the program itself) against a benchmark across runs; `evolution-coordinator` agent.",
+      "version": "0.1.0",
+      "category": "exotic",
+      "status": "available"
+    },
+    {
+      "name": "dspy-appliance-support-bot",
+      "source": "./plugins/dspy-appliance-support-bot",
+      "description": "Vertical appliance: a pre-wired DSPy.ts support assistant — RAG over a knowledge base + ChainOfThought answer + a quality metric + MIPROv2 tuning.",
+      "version": "0.1.0",
+      "category": "appliance",
+      "status": "available"
+    },
+    {
+      "name": "dspy-appliance-code-review",
+      "source": "./plugins/dspy-appliance-code-review",
+      "description": "Vertical appliance: a DSPy.ts code-review pipeline — Retrieve(repo context) → ChainOfThought(review) → metric on actionability; GEPA-tuned.",
+      "version": "0.1.0",
+      "category": "appliance",
+      "status": "available"
+    },
+    {
+      "name": "dspy-appliance-research-assistant",
+      "source": "./plugins/dspy-appliance-research-assistant",
+      "description": "Vertical appliance: a DSPy.ts research assistant — ReAct(search tools)+reflexion → synthesize → cite; optimized for grounded answers.",
+      "version": "0.1.0",
+      "category": "appliance",
+      "status": "available"
+    },
+    {
+      "name": "dspy-appliance-data-pipeline",
+      "source": "./plugins/dspy-appliance-data-pipeline",
+      "description": "Vertical appliance: a DSPy.ts ETL/classification pipeline — typed Predict modules in a Pipeline, BootstrapFewShot from a labeled CSV, evaluated batch.",
+      "version": "0.1.0",
+      "category": "appliance",
+      "status": "available"
+    }
+  ]
+}

README.md

@@ -180,6 +180,35 @@ await opt.compile(qa, trainset);
 
 ---
 
+## Plugins (Claude Code & Codex)
+
+DSPy.ts ships a **plugin marketplace** so you can program, compile, evaluate, and run DSPy.ts programs from inside Claude Code or OpenAI Codex — commands, sub-agents, design skills, and bundled MCP servers exposing the library as tools/resources. See [`docs/adr/ADR-0001-claude-code-plugin-marketplace.md`](./docs/adr/ADR-0001-claude-code-plugin-marketplace.md).
+
+```bash
+# add the marketplace, then install a plugin
+/plugin marketplace add ruvnet/dspy.ts
+/plugin install dspy-core@dspy.ts
+# or try one locally from a checkout
+claude --plugin-dir ./plugins/dspy-core
+```
+
+| Plugin | What it does |
+|--------|--------------|
+| `dspy-core` | Scaffold / compile (BootstrapFewShot · MIPROv2 · GEPA) / evaluate programs; `dspy-architect` agent; signature- & metric-design skills; MCP tools for the library |
+| `dspy-optimize` | Deep optimizer workflows — MIPROv2 + experience replay, GEPA Pareto evolution, BootstrapFewShot dynamic demos; `optimizer-engineer` agent |
+| `dspy-rag` | `RetrieveModule` (MMR) over an AgentDB corpus → `ChainOfThought`, grounded + cited; corpus indexing; `rag-architect` agent |
+| `dspy-react` | ReAct agents + tool registries + `ReActReflexion` (recall lessons, record episodes, promote skills); `react-engineer` agent |
+| `dspy-observability` | `CompilationTracer` causal-chain traces (AgentDB / optional MLflow) + `CachingLM`; `observability-engineer` agent |
+| `dspy-evolution` *(exotic)* | Multi-generation GEPA self-evolution against a held-out benchmark — persistent Pareto frontier, warm-start, optional structural exploration; `evolution-coordinator` agent |
+| `dspy-appliance-support-bot` | Vertical appliance: a pre-wired RAG support assistant (Retrieve → CoT + citations + quality metric + MIPROv2 tuning) |
+| `dspy-appliance-code-review` | Vertical appliance: a code-review pipeline (Retrieve repo context → CoT structured review + actionability metric + GEPA tuning) |
+| `dspy-appliance-research-assistant` | Vertical appliance: a ReAct(search/fetch/note)+reflexion → CoT synthesizer that writes grounded, cited answers |
+| `dspy-appliance-data-pipeline` | Vertical appliance: typed `PredictModule` stages in a `Pipeline` + CSV/JSONL batch I/O + BootstrapFewShot from a labeled CSV |
+
+Source: [`plugins/`](./plugins/) · marketplace manifest: [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json)
+
+---
+
 ## Documentation
 
 | Doc | Where |

docs/adr/ADR-0001-claude-code-plugin-marketplace.md

@@ -0,0 +1,89 @@
+# ADR-0001: DSPy.ts Claude Code & Codex Plugin Marketplace
+
+- **Status:** Accepted
+- **Date:** 2026-05-11
+- **Deciders:** rUv
+- **Tags:** plugins, marketplace, mcp, claude-code, codex, dx
+
+## Context
+
+DSPy.ts ships a real programming model — typed `Signature`s, modules (`PredictModule`,
+`ChainOfThought`, `ReAct`, `RetrieveModule`, `Pipeline`), optimizers
+(`BootstrapFewShot`, `MIPROv2`, `GEPA`), and an AgentDB memory layer (HNSW + RaBitQ +
+MMR, ReasoningBank, ReActReflexion, CompilationTracer). Today a user has to read the
+docs/examples and wire all of that by hand. We want the library to be *usable from
+inside an agent* — Claude Code and OpenAI Codex — so an agent can scaffold a program,
+compile it with an optimizer, evaluate it, and run RAG/ReAct without the human
+hand-assembling the pieces.
+
+Claude Code supports **plugins** (`.claude-plugin/plugin.json` + `commands/`,
+`agents/`, `skills/`, and bundled `mcpServers`), distributed through a
+**marketplace** (`.claude-plugin/marketplace.json`). Codex consumes the same MCP
+servers and reads `AGENTS.md`. So a single repo can publish: a marketplace manifest,
+several plugins, and MCP tools/resources that expose the library itself.
+
+## Decision
+
+Publish a **plugin marketplace from the `ruvnet/dspy.ts` repo**:
+
+1. **`.claude-plugin/marketplace.json`** at the repo root lists all plugins.
+2. **`plugins/<name>/`** — one directory per plugin, each a valid Claude Code plugin
+   (`.claude-plugin/plugin.json`, `commands/*.md`, `agents/*.md`,
+   `skills/<name>/SKILL.md`), and where useful a bundled **MCP server** (`mcp/server.js`,
+   referenced from `plugin.json`'s `mcpServers`) exposing DSPy.ts as tools
+   (`dspy_scaffold`, `dspy_compile`, `dspy_eval`, `dspy_retrieve`, …) and resources
+   (`dspy://docs/api`, `dspy://examples`, the design-skill guides). Codex picks up the
+   same MCP servers.
+3. **Tiers, practical → exotic, plus vertical appliances:**
+   - `dspy-core` — scaffold / compile / evaluate; `dspy-architect` agent; signature- &
+     metric-design skills; MCP tools for the library. *(shipped first)*
+   - `dspy-optimize` — deep optimizer workflows (MIPROv2 + experience replay, GEPA
+     Pareto evolution, BootstrapFewShot dynamic demos).
+   - `dspy-rag` — `RetrieveModule` over AgentDB (HNSW/RaBitQ/MMR) → ChainOfThought;
+     corpus indexing.
+   - `dspy-react` — ReAct + tool registries + `ReActReflexion` (recall lessons, record
+     episodes, promote skills).
+   - `dspy-observability` — `CompilationTracer` causal traces, AgentDB persistence,
+     optional MLflow; `CachingLM`.
+   - `dspy-evolution` — *(exotic)* GEPA-driven self-evolution loops that evolve a
+     program's prompts (and the program) against a benchmark across runs.
+   - **Vertical appliances** — pre-wired end-to-end programs:
+     `dspy-appliance-support-bot`, `dspy-appliance-code-review`,
+     `dspy-appliance-research-assistant`, `dspy-appliance-data-pipeline`.
+4. **Build cadence:** `dspy-core` + the marketplace manifest land now; the remaining
+   plugins are built one per iteration via a recurring loop, each scaffolded, validated
+   (plugin.json parses, frontmatter present, referenced files exist) and committed,
+   tracked in a GitHub issue, finishing with a single PR.
+
+## Consequences
+
+**Positive**
+- The library becomes operable from Claude Code / Codex with no hand-wiring; agents get
+  first-class commands, sub-agents, design skills, and MCP tools/resources.
+- One source of truth (this repo) for the marketplace; users add it with
+  `/plugin marketplace add ruvnet/dspy.ts`.
+- Vertical appliances give a working baseline you can `dspy-compile` further — they
+  double as examples.
+
+**Negative / risks**
+- More surface to keep in sync with the `dspy.ts` API — mitigated by pinning
+  `minClaudeFlowVersion`-style version hints in each `plugin.json` and keeping command
+  bodies thin (they orchestrate, the library does the work).
+- The bundled MCP servers start as scaffolds (tool schemas + handler stubs that shell
+  out to `npx ts-node`) — fleshing out the stdio transport + handlers is follow-up work
+  per plugin.
+
+## Alternatives considered
+
+- **Docs only / no plugins** — rejected: doesn't make the library agent-operable.
+- **One mega-plugin** — rejected: a 12-field-signature problem; tiers + appliances are
+  clearer and let users install only what they need.
+- **A separate `dspy-plugins` repo** — rejected: keeps the marketplace away from the
+  code it wraps; co-locating means a PR can change both together.
+
+## References
+
+- Tracking issue: roadmap + per-plugin checklist on `ruvnet/dspy.ts`.
+- `dspy.ts@2.2.0` API: `configureLM`, `ChainOfThought`, `BootstrapFewShot`, `MIPROv2`,
+  `GEPA`, `RetrieveModule`, `AgentDBClient`, `ReActReflexion`, `CachingLM`,
+  `CompilationTracer`.

plugins/dspy-appliance-code-review/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "dspy-appliance-code-review",
+  "description": "Vertical appliance: a pre-wired DSPy.ts code-review pipeline. Ships a ready-to-run program — RetrieveModule pulls relevant repo context (conventions, related code, prior reviews) from an AgentDB index → ChainOfThought produces a structured review (severity-tagged findings + suggested fixes) → an actionability metric scores it → GEPA tuning. Commands scaffold it into your repo, review a diff/file, and tune the reviewer.",
+  "version": "0.1.0",
+  "author": { "name": "rUv", "url": "https://github.com/ruvnet" },
+  "homepage": "https://github.com/ruvnet/dspy.ts",
+  "license": "MIT",
+  "keywords": ["dspy", "dspy.ts", "appliance", "code-review", "rag", "gepa", "agentdb", "pull-request"],
+  "mcpServers": { "dspy-appliance-code-review": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"] } }
+}

plugins/dspy-appliance-code-review/AGENTS.md

@@ -0,0 +1,13 @@
+# dspy-appliance-code-review — for Codex / MCP clients
+
+A vertical appliance: a pre-wired DSPy.ts code-review pipeline. Ships a ready-to-run program (`templates/code-reviewer.ts` — `RetrieveModule` pulls repo context → `ChainOfThought` produces a structured review + an `actionabilityMetric`) plus tooling to stand it up. MCP server: `mcp/server.js`, command `node ${CLAUDE_PLUGIN_ROOT}/mcp/server.js`.
+
+**Tools**
+- `code_review_init` — copy the appliance program into `src/dspy/code-reviewer.ts` (+ spec), build the AgentDB repo-context index (conventions, ADRs, representative modules, prior PR reviews).
+- `code_review_run` — review a diff/file: retrieves relevant repo context, returns `{summary, findings:[{severity,location,issue,suggestion}], questions, passages, context}`.
+- `code_review_tune` — GEPA-tune (or MIPROv2) the reviewer against a labelled set (`[{input:{diff,intent?}, output:{knownIssues:[{severity,near}], verdict}}]`) and the actionability metric (coverage − noise, specificity, calibration; false alarms on clean PRs penalised); saves `<program>.gepa.json`.
+- `code_review_status` — context-index stats + whether a tuned reviewer is loaded.
+
+**Resources**: `dspy://code-reviewer/template`, `dspy://review-context-indexing`, `dspy://review-actionability-metric`.
+
+Handlers shell out to `npx ts-node` against `src/dspy/*` (the copied appliance) and `dspy.ts`. Slash commands `/code-review-init`, `/code-review-run`, `/code-review-tune` wrap the same flows; the `code-review-builder` agent stands up and tunes a reviewer for a specific repo. Builds on `dspy-rag` (index/retrieve), `dspy-optimize` + `dspy-evolution` (GEPA/MIPROv2 tuning), `dspy-observability` (tracer, cache).

plugins/dspy-appliance-code-review/agents/code-review-builder.md

@@ -0,0 +1,14 @@
+---
+name: code-review-builder
+description: Stands up and tunes the DSPy.ts code-review appliance for a specific repo — scaffolds the program, builds the repo-context index (conventions, representative code, ADRs, prior reviews), assembles a labelled review set, GEPA-tunes the reviewer against the actionability metric, and validates review quality. Use to go from "review PRs against our conventions" to a tuned reviewer.
+---
+You build code-review appliances on DSPy.ts.
+
+STEPS:
+1. **Scaffold** — `/code-review-init --context <path> --include '<conventions, ADRs, representative modules>' --prior-reviews <past-reviews.json>`. The appliance code (`RetrieveModule → ChainOfThought` + `actionabilityMetric`) is the starting point; keep the prompt's hard constraints — *judge against the repo's actual conventions (cite them), every finding is located + has a concrete fix, severity-tag honestly, say "ship it" when it's good*.
+2. **Index the right context** — conventions docs, ADRs, a *representative sample* of modules (the patterns you want enforced), and especially **prior PR reviews** (they encode what this team actually flags). Metadata `{ source, kind }`. Don't bulk-index the whole repo — that dilutes retrieval; curate. (See the `review-context-indexing` skill.)
+3. **Labelled review set** — from past PRs: `{ input:{diff, intent}, output:{knownIssues:[{severity, near}], verdict} }`. **Include clean PRs** (`verdict: 'ship'`, no `knownIssues`) so tuning penalises false alarms — without them the reviewer learns to always find problems. Hold out a slice.
+4. **Tune** — `/code-review-tune <set>` with GEPA against `actionabilityMetric` (coverage of real issues − noise, specificity, severity calibration), `frontierStore` + a `CachingLM`. Read the reflections — which instruction change made it more specific / less noisy? For ongoing evolution, hand to `dspy-evolution`'s `/dspy-evolve`.
+5. **Validate** — `/code-review-run` on held-out diffs: does it catch the known issues? are findings located + actionable? does it stay quiet on clean PRs? does it cite real conventions (not invented ones)? (See the `review-actionability-metric` skill.)
+
+DELIVER: the program file, the context index, the labelled set, the tuned reviewer (`.gepa.json`), and a quality report (mean metric, examples of good findings, false-alarm rate on clean PRs, recall on known issues).

plugins/dspy-appliance-code-review/commands/code-review-init.md

@@ -0,0 +1,11 @@
+---
+description: Scaffold the DSPy.ts code-review appliance into your repo — copy the program template to src/dspy/code-reviewer.ts (+ spec), build the AgentDB repo-context index (conventions, representative modules, ADRs, prior reviews), and print next steps.
+argument-hint: "[--dest src/dspy/code-reviewer.ts] [--context .dspy/review-context] [--include 'src/**/*.ts,docs/adr/**,CONVENTIONS.md'] [--prior-reviews path/to/reviews.json]"
+---
+Set up the code-review appliance. Parse `$ARGUMENTS` for `--dest` (default `src/dspy/code-reviewer.ts`), `--context` (AgentDB index path, default `.dspy/review-context`), `--include` (globs of repo material to index: conventions docs, ADRs, a sample of representative modules), `--prior-reviews` (a JSON of past PR review comments to index — optional but high value).
+
+1. Confirm `dspy.ts` is a dependency.
+2. Copy `${CLAUDE_PLUGIN_ROOT}/templates/code-reviewer.ts` → `--dest` (+ `code-reviewer.spec.ts`); rewrite `CONTEXT_PATH` to `--context`.
+3. `const ctx = new AgentDBClient({ vectorDimension: 384, storage: { path: contextPath } }); await ctx.init();`
+4. Index the `--include` material: chunk each file (keep `{ source, kind: 'convention'|'adr'|'code'|'review' }` metadata), `ctx.storeText(chunk, meta, { tier: 'long' })`. Index `--prior-reviews` too (`kind: 'review'`) — past reviews teach the reviewer what this team flags. Don't index the whole repo — a representative sample of conventions + patterns + reviews is what helps; bulk source just dilutes retrieval.
+5. Print next steps: `git diff` then `/code-review-run` on it; build `tune/reviews.json` (`[{ input:{diff, intent?}, output:{knownIssues:[{severity, near}], verdict} }]` from labelled past PRs); then `/code-review-tune tune/reviews.json`.

plugins/dspy-appliance-code-review/commands/code-review-run.md

@@ -0,0 +1,11 @@
+---
+description: Run the code-review appliance on a diff or file — retrieves relevant repo context (conventions, related code, prior reviews), produces a structured review (severity-tagged, located findings + suggested fixes), and prints it.
+argument-hint: "<diff-or-file> [--intent \"PR title/description\"] [--program src/dspy/code-reviewer.ts] [--severity-min nit|minor|major|blocker] [--show-context]"
+---
+Review a change. Parse `$ARGUMENTS` for the target (a path to a `.diff`/`.patch`, a source file, or `-` to read a diff from stdin / `git diff`), `--intent` (what the change is meant to do), `--program`, `--severity-min` (filter findings), `--show-context`.
+
+1. Obtain the diff (read the file, or `git diff` if `-`).
+2. `const rev = await buildCodeReviewer();` (from the appliance module) — `RetrieveModule → ChainOfThought`.
+3. `const out = await rev.run({ diff, intent });`
+4. Print: the **summary** (ship / changes-needed / blocked + why); the **findings** grouped by severity — each `location · issue · suggestion` (filter by `--severity-min`); the **questions** for the author; and the **passages** that informed it (rank · score · source · kind). With `--show-context`, the assembled context.
+5. If findings are vague ("consider refactoring") or it flags things that aren't actually project conventions: that's what `/code-review-tune` fixes (the metric rewards specific, located, convention-cited findings and penalises noise). If it misses obvious issues: index more representative code / prior reviews into the context.