bobs-big-brain-plugin: Instructions file for Claude Code

AGENTS.md

Agent + developer guidance for the Bob's Big Brain plugin repo. Tool-agnostic; CLAUDE.md points here.

What this is

The unified, public Bob's Big Brain plugin — a Claude Code plugin that runs as a single stdio MCP server in two modes:

• local (default): an in-process governed brain over your own files (~/.teamkb). First-start native provisioning can use npm/network; optional dense retrieval uses a separate loopback embedder. Lexical retrieval needs no generative-model API key.
• team (when TEAMKB_API_URL is set): a remote proxy to a shared governed-brain HTTP API over your network.

This is the installable code; the landing/thesis lives in the company umbrella repo.

	Repo	Role
This repo	jeremylongshore/bobs-big-brain-plugin (personal, public)	the plugin: MCP runtime (local + team) + skills
Umbrella	intent-solutions-io/bobs-big-brain-umbrella (company)	landing page, thesis, competitive teardown — points here
Engines	jeremylongshore/{bobs-big-brain-compiler, bobs-big-brain-registrar}	Bob's Big Brain Compiler (compile) + Bob's Big Brain Registrar (govern) — separate repos
Retired marketplace	intent-solutions-io/team-intent-claude-plugins	historical distribution; current public marketplace is this repository

The old standalone intent-brain plugin is RETIRED. It used to live in qmd-team-intent-kb/.claude-plugin/ as a separate team-only plugin; it has been folded into this plugin's team mode and removed from the team marketplace (bead compile-then-govern-650.4). There is now ONE plugin for both local and team — do not resurrect a second one.

Architecture — the dual-mode dispatch (the part that matters)

src/index.ts is the dispatcher: it reads TEAMKB_API_URL and await import()s exactly one server (an unexpanded ${...} placeholder counts as unset → local):

• src/local-server.ts — LOCAL mode. Drives qmd + the deterministic govern kernel + ~/.teamkb directly, in-process (imports @qmd-team-intent-kb/* + better-sqlite3). Full tool surface (6): brain_search / brain_status / brain_audit_verify (read) + brain_capture / brain_govern / brain_transition (write).
• src/remote-server.ts — TEAM mode. Proxies to the Registrar HTTP API (apps/api) over the network with a per-user bearer token. Tool surface (9): brain_search and auth-free brain_status reads; brain_capture proposals; brain_inbox, brain_approve, and brain_reject admin review; brain_holds and brain_hold_recommend for the human-escalation hold queue (list and recommend only — see below); and brain_transition admin lifecycle changes. No brain_govern (govern runs server-side), and brain_audit_verify remains local-only.