SpecBridge v0.5: local MCP server, interactive task execution, and Claude Code plugin

[HelloThisWorld]

What

v0.5 delivers the three headline capabilities from the roadmap's Phase K and beyond, strictly as adapters over the existing core packages — no workflow, verification, Git, evidence, approval, or Markdown-writing logic is duplicated:

1. Local stdio MCP server (packages/mcp-server)

• Official @modelcontextprotocol/sdk 1.29.0 (pinned exact), stable protocol baseline 2025-11-25, stdio transport only.
• 21 typed tools (14 read-only + 7 state-changing), 7 resources (specbridge://…), 4 workflow prompts — every tool with versioned Zod input/output schemas, annotations, and the stable SBMCP001–SBMCP020 error envelope returned as tool results (never protocol errors, never stack traces).
• Bounded everything: 50/200 list pagination with tamper-checked cursors, 1 MB documents/candidates, 2 MB structured responses, 500-diagnostic cap.
• One pinned project root per process (--project-root → SPECBRIDGE_PROJECT_ROOT → CLAUDE_PROJECT_DIR → cwd); stderr-only structured logging; per-project write mutex; request cancellation propagates to verifier child processes.
• New CLI commands: specbridge mcp serve|doctor|manifest|tools.

2. Direct interactive task execution

• task_begin → the current session edits source → task_complete (plus task_abort), reusing the v0.3 snapshot/verification/evidence pipeline (finalizeTaskRun) unchanged: hash-exact change attribution, protected-path detection, trusted argv-only verification commands, append-only evidence, and the verified-only one-line checkbox update.
• Reported fields are recorded as claims, never proof; completion is idempotent; nothing is ever rolled back.
• Repository-local lock (.specbridge/locks/interactive-task.lock) with atomic acquisition, staleness diagnosis, and the explicit specbridge run recover-lock [--remove] recovery command — ambiguous or live locks are never removed.
• Run schemas gain interactive-execution/interactive-authoring kinds plus lifecycleStatus/host/abortReason — all optional; every v0.3 record keeps validating.

3. Self-contained Claude Code plugin (integrations/claude-code-plugin/specbridge)

• Bundled dist/cli.cjs + dist/mcp-server.cjs (no node_modules, no workspace resolution, no monorepo paths — committed like the GitHub Action bundle so marketplace installs work from a clone), POSIX + Windows wrappers, license report, SHA-256 checksum manifest.
• Eight skills: /specbridge:doctor·status·new·author·approve·implement·continue·verify. approve is disable-model-invocation: true and remains the human gate; implement uses the interactive lifecycle and never launches a nested Claude process (enforced by content scans + tests).
• Repository-local marketplace (.claude-plugin/marketplace.json, strict mode) and a reproducible release ZIP.
• pnpm build:plugin / validate:plugin / verify:plugin-bundle (mandatory isolated-copy verification: space-containing temp dir, outside fixture project, raw JSON-RPC handshake, no-monorepo-path proof).

Why

The primary UX becomes: install the plugin → /specbridge:status → /specbridge:author → explicit human approval → /specbridge:implement (the current session edits; MCP captures actual Git changes; trusted verification runs; the checkbox flips only when verified) → /specbridge:verify. The standalone CLI remains a first-class product and the authoritative runtime; approval is deliberately not exposed as a model-controlled MCP tool (see docs/cli-mcp-parity.md).

Verification

Gate	Result
Baseline (pre-change)	lint/typecheck/build ✓, 520/520 tests, 28/28 smoke
pnpm lint / pnpm typecheck	✓
pnpm test	631/631 (520 regression + 111 new: MCP unit, process-level stdio, concurrency/cancellation, interactive lifecycle, authoring, verification, resources/prompts, plugin structure/bundle)
pnpm build / build:plugin	✓
pnpm validate:plugin	✓
pnpm verify:plugin-bundle	✓ 8/8 isolated checks
pnpm smoke	✓ 32/32 (incl. new mcp + recover-lock checks)
Live E2E through the shipped bundle	handshake 0.5.0/2025-11-25 → task_begin → edit → task_complete = verified, exactly one checkbox flipped, evidence recorded, HEAD untouched

Reviewer notes

• Core packages changed minimally and behavior-compatibly: RUN_KINDS extension + runTypeForKind (core), run-record optional fields (execution), policyRelevantDirtyPaths extraction and FinalizeDeps loosening (execution), candidateAnalysis export (execution), persistArtifacts option on verifySpecs (drift, default unchanged).
• @modelcontextprotocol/sdk is also a root devDependency (pinned) for the root-level test suite's in-memory client.
• All versions move to 0.5.0 consistently (validator-enforced). Nothing is published to npm and the plugin is not submitted to any external marketplace.
• Not executed here: claude --plugin-dir inside a live Claude Code session (needs an interactive host); everything headlessly testable is covered by the isolated bundle verification, and the docs describe the manual check.
• CI gains plugin validation, isolated bundle verification, and an ubuntu reproducibility diff for the committed plugin bundle.

🤖 Generated with Claude Code