@ideate/plugin

The public, composable surface of ideate — a Claude Code plugin for AI-augmented software delivery.

ideate decomposes into three functions: a process record (the durable, auditable trail of what was decided and done — append-only, project-local, never curated or ranked by ideate itself), a knowledge graph (memory and retrieval over that trail — developed as a separate project, not part of this plugin), and a delegation board (how work is handed to and coordinated across agents — a future sibling capability, not part of this plugin today). ideate is deliberately non-prescriptive about workflow: it supplies primitives that fire mechanically, not a process you are told to follow, and it never blocks, redirects, or opines on what you do.

What this plugin provides today

This package ships the Layer-0 floor: the append-only process record and the mechanical capture/priming wiring around it. Nothing here is optional workflow — every piece below fires without requiring an agent to remember to call it.

• An append-only process record. Every entry — a decision, a finding, a session outcome, a subagent outcome, a commit boundary, a task completion — is appended, never updated or deleted; a correction is a new record that references the superseded one. Every write passes a capture-time secret-scanning gate before anything touches disk.
• Capture hooks. SessionEnd, PreCompact, SubagentStop, TaskCompleted, and PostToolUse (on git commit) are wired in hooks/hooks.json so records are captured mechanically as you work, with zero required tool calls. Every ideate hook is non-blocking: it exits 0, writes side effects and additionalContext only, and never blocks, denies, or halts anything the host is doing.
• Session priming. At session start, and on subagent start, a bounded, unranked digest of the most recent process records is surfaced as additional context — recency- and scope-selected only, never scored or curated, and explicitly framed as quoted historical data rather than instructions.
• Telemetry. Native counters for capture, priming, and failure events, inspectable with the ideate-telemetry CLI.

Install

There are two ways to wire this plugin into a Claude Code project. Both land on the same dist/server.js MCP server and hooks/hooks.json — the manifests below are just two different ways of pointing Claude Code at them. This section documents the contracts (what each mechanism provides); it does not prescribe which one to use or what workflow to run once installed.

(a) Marketplace install

This repo ships .claude-plugin/marketplace.json, a Claude Code plugin-marketplace manifest listing this plugin (name: ideate, source: "./" — the repo root). From within Claude Code:

/plugin marketplace add ideate-ai/ideate
/plugin install ideate

This is the manifest-driven path — Claude Code resolves the plugin and wires .mcp.json / hooks/hooks.json for you. Known limitation (honest status): this repo deliberately does not commit built output (dist/ is git-ignored), and a plugin install performs no build step — so the MCP server and CLIs are NOT functional straight from a marketplace install today. Until a distribution mechanism for built output exists (tracked as an open question in the project record), use the manual path below, which is the tested, supported route.

(b) Manual wiring

For a project that wants to point at this plugin directly rather than through the marketplace resolver:

1. Build the package: pnpm install && pnpm run build (compiles src/ to dist/; required before the MCP server or CLIs will run — dist/ is not checked in).

2. Add an MCP server entry to the consuming project's .mcp.json pointing at the built server, e.g.:

   {
     "mcpServers": {
       "ideate": {
         "command": "node",
         "args": ["<path-to-this-plugin>/dist/server.js"]
       }
     }
   }
   

   This registers the three MCP verbs (record_append, record_read, record_decision) described below.

3. Wire the mechanical capture hooks by pointing the consuming project's host at this plugin's hooks/hooks.json. That file declares the actual hook shape this plugin provides — SessionStart (priming via bin/ideate-record prime), SubagentStart/SubagentStop, SessionEnd (bin/ideate-record session-end), PreCompact, and PostToolUse on git commit — each entry a command hook invoking either ${CLAUDE_PLUGIN_ROOT}/bin/ideate-record or one of the hooks/*.mjs scripts. How a consuming project performs that wiring (copying the file, referencing it, or another host-specific mechanism) is outside this plugin's contract — only the shape of hooks/hooks.json itself is.

Build / test (contributor path)

Prerequisites: Node >= 22 and a pnpm-compatible install.

pnpm install
pnpm run build   # compiles src/ to dist/ — required before the MCP server
                 # or the CLIs will run; dist/ is not checked in
pnpm test        # vitest, fork pool capped at 4 (see vitest.config.ts)

pnpm run test:fresh-copy runs scripts/fresh-copy-check.mjs, which copies this directory to a scratch location with no surrounding project context and re-runs install/build/test there — the mechanical proof that this package stands alone.

The process-record surface

The record core has exactly two transports over one implementation: three MCP tools, and a CLI. Both write through the same gated append-only store, so a record captured via one transport is indistinguishable from one captured via the other.

MCP verbs (registered by the ideate MCP server, dist/server.js):

• record_append(kind, claim, verification_anchor?, scope?, content, task_id?) — append one process record. Open-vocabulary kind (e.g. finding, session-outcome, commit-boundary, …).
• record_read(scope?, limit?) — read records newest-first, optionally filtered by a plain substring match against scope/kind/source. Unranked: selection only, no scoring.
• record_decision(claim, rationale?, verification_anchor?, scope?, task_id?) — sugar for record_append(kind="decision", ...); the ADR entry point. The decision write is its capture — there is no separate decision store.

ideate-record CLI (bin/ideate-record, the same gated core as a standalone executable — this is what the capture hooks invoke):

• ideate-record append --kind <k> --claim <c> [--anchor <a>] [--scope <s>] [--content <text>|-] [--task <id>] — append one record directly; exits 1 on failure.
• ideate-record read [--scope <substring>] [--limit <n>] [--json] — print records newest-first; exits 1 on failure.
• ideate-record session-end — reads a SessionEnd hook payload from stdin and appends a recall-shaped session-outcome record. Hook path: always exits 0 (a capture failure must never look like a hook failure to the host).
• ideate-record prime [--scope <substring>] [--budget <n>] — print a compact, unranked digest of the most recent records for hook additionalContext. Hook path: always exits 0.

Honest status

• Available now: the append-only process record, the five mechanical capture points (SessionEnd, PreCompact, SubagentStop, TaskCompleted, PostToolUse on git commit), session/subagent priming, the capture-time secret-scanning gate, and native telemetry counters.
• Not yet built: the delegation board (work-state coordination across agents). This is a future sibling capability; nothing in this plugin depends on it.
• Eval-gated, not yet built: any feature whose value is an intelligence-adjacent claim is withheld until the evaluation harness (@ideate/harness, private, not part of this package) demonstrates it, per gates G1–G7 of the project's eval design. This includes: planning-time gap identification (/ideate:gap-check and its advisory hook — designed, not built, gated on G4), and per-prompt priming (technically wireable, but deferred — its token-cost tradeoff is exactly the kind of default the harness must license first, gated on G1/G2). None of this plugin's shipped behavior depends on either.
• This package is "private": true in package.json and stays that way until publishing this plugin to npm is separately ratified.

License

AGPL-3.0-only — see LICENSE.