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

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

Add packages/mcp-server: a local stdio MCP server (pinned
@modelcontextprotocol/sdk 1.29.0, protocol baseline 2025-11-25) exposing the
shared core packages as 21 typed tools, 7 read-only resources, and 4
workflow prompts, with the stable SBMCP001-020 error envelope, bounded
paginated outputs, a per-project write mutex, stderr-only structured
logging, and pinned project-root resolution. The CLI gains
`mcp serve|doctor|manifest|tools` and `run recover-lock`.

Add the direct interactive execution lifecycle in @specbridge/execution:
task_begin -> the current host session edits source -> task_complete
(plus task_abort), reusing the v0.3 Git snapshots, trusted verification
commands, evidence evaluation, append-only evidence, and the verified-only
surgical checkbox update. A repository-local lock file serializes runs
across processes; recovery is explicit and never automatic. Run schemas
gain interactive kinds and lifecycle fields, backward compatibly.

Add the self-contained Claude Code plugin
(integrations/claude-code-plugin/specbridge): bundled cli.cjs and
mcp-server.cjs (no node_modules, no monorepo paths), POSIX and Windows CLI
wrappers, eight namespaced skills (approve is human-only via
disable-model-invocation), a repository-local marketplace
(.claude-plugin/marketplace.json), a third-party license report, a SHA-256
checksum manifest, and a reproducible release ZIP. New scripts:
build:plugin, validate:plugin, verify:plugin-bundle (mandatory
isolated-copy verification), mcp:inspect.

Safety: no arbitrary filesystem/shell/Git MCP tool, no model-controlled
stage approval, no nested Claude invocation from plugin or MCP paths
(enforced by content scans and tests), candidate hash binding between
validate and apply, and no automatic Git mutations of any kind.

All versions move to 0.5.0. 631 tests pass (520 regression + 111 new),
plus 32 CLI smoke checks and 8 isolated bundle checks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Make plugin license-file discovery filesystem-case-independent

The license report generator probed a fixed list of file names with
existsSync, which behaves differently across filesystems: on Windows
(case-insensitive) "LICENSE.md" matched express-rate-limit's and ms's
"license.md", while on Linux it did not — so the ubuntu CI rebuild produced
a different THIRD_PARTY_LICENSES.txt (and checksum manifest) than the
committed artifact, failing the plugin-bundle reproducibility check.

Discovery now lists the package directory and matches names against a
case-insensitive licen[cs]e pattern with a deterministic sort, so every
platform selects the same file. The committed artifact was already the
complete report (generated on the case-insensitive side); only the script
needed the fix, and ubuntu now reproduces the committed bytes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: HelloThisWorld

.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "specbridge-plugins",
+  "owner": {
+    "name": "HelloThisWorld"
+  },
+  "description": "Claude Code integrations for SpecBridge, the open spec runtime for existing Kiro projects.",
+  "plugins": [
+    {
+      "name": "specbridge",
+      "source": "./integrations/claude-code-plugin/specbridge",
+      "description": "Kiro-compatible spec workflows, verified interactive task execution, and deterministic drift checks.",
+      "version": "0.5.0",
+      "license": "MIT",
+      "keywords": [
+        "spec-driven-development",
+        "mcp",
+        "kiro",
+        "verification"
+      ],
+      "category": "development",
+      "strict": true
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -48,3 +48,13 @@ jobs:
       - name: GitHub Action bundle is reproducible
         if: matrix.os == 'ubuntu-latest'
         run: git diff --exit-code integrations/github-action/dist
+
+      - name: Validate the Claude Code plugin (deterministic, no Claude Code required)
+        run: pnpm validate:plugin
+
+      - name: Verify the isolated plugin bundle (mandatory self-containment check)
+        run: pnpm verify:plugin-bundle
+
+      - name: Claude Code plugin bundle is reproducible
+        if: matrix.os == 'ubuntu-latest'
+        run: git diff --exit-code integrations/claude-code-plugin/specbridge/dist

.gitignore

@@ -8,6 +8,10 @@ dist/
 # The GitHub Action ships its reproducible bundle in-repo (checked in CI).
 !integrations/github-action/dist/
 
+# The Claude Code plugin ships its reproducible bundle in-repo too, so
+# installing the plugin straight from the GitHub marketplace source works.
+!integrations/claude-code-plugin/specbridge/dist/
+
 # Test output
 coverage/
 

CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.5.0
+
+Added:
+
+- Local stdio MCP server (`specbridge mcp serve`) built on the official
+  `@modelcontextprotocol/sdk` 1.29.0 (pinned; stable protocol baseline
+  2025-11-25): 21 typed tools with versioned Zod input/output schemas,
+  annotations, and the stable SBMCP001–SBMCP020 error envelope; 7 read-only
+  resources (`specbridge://…`); 4 workflow prompts for non-Claude clients;
+  bounded structured responses (pagination cursors, 1 MB documents, 2 MB
+  responses, 500-diagnostic cap); `specbridge mcp doctor|manifest|tools`.
+- Direct interactive task execution: `task_begin` → the CURRENT host session
+  edits source → `task_complete` (plus `task_abort`), reusing the v0.3 Git
+  snapshots, trusted verification commands, evidence evaluation, append-only
+  evidence, and the verified-only surgical checkbox update. Model-reported
+  fields are recorded as claims, never proof.
+- Interactive execution locking (`.specbridge/locks/interactive-task.lock`):
+  atomic acquisition, heartbeats, crash-tolerant staleness diagnosis, and
+  the explicit `specbridge run recover-lock [--remove] [--json]` recovery
+  command. Ambiguous or actively held locks are never removed.
+- Candidate stage authoring over MCP: `spec_stage_validate` (deterministic
+  analysis + diff + approval effects + candidate hash, read-only) and
+  `spec_stage_apply` (atomic, hash-bound to the reviewed bytes, dependent
+  approvals invalidated per workflow rules, append-only
+  `interactive-authoring` run record, no force option). Preview-first
+  `spec_create` (apply: false renders without writing).
+- Self-contained Claude Code plugin
+  (`integrations/claude-code-plugin/specbridge`): bundled `dist/cli.cjs` and
+  `dist/mcp-server.cjs` (no node_modules, no workspace resolution, no
+  monorepo paths), POSIX + Windows CLI wrappers, eight namespaced skills
+  (`/specbridge:doctor·status·new·author·approve·implement·continue·verify`),
+  third-party license report, and a SHA-256 checksum manifest.
+- Repository-local plugin marketplace (`.claude-plugin/marketplace.json`,
+  strict mode) so `/plugin marketplace add HelloThisWorld/specbridge` works
+  straight from a clone.
+- Isolated plugin bundle verification (`pnpm verify:plugin-bundle`): copies
+  the built plugin to an isolated space-containing directory, runs the
+  bundled CLI and wrappers against an outside fixture project, performs a
+  real MCP stdio handshake, and proves no monorepo path is required — plus
+  deterministic `pnpm validate:plugin` and the reproducible release ZIP
+  artifact `dist/specbridge-claude-plugin-0.5.0.zip`.
+
+Changed:
+
+- Claude Code plugin task execution now uses the current session
+  (task_begin/task_complete) instead of starting a nested Claude process;
+  the v0.3 runner workflow remains fully supported from the standalone CLI.
+- Shared core APIs are exposed consistently through CLI and MCP; the MCP
+  server is a thin typed adapter with no duplicated workflow, verification,
+  Git, evidence, approval, or Markdown-writing logic
+  (docs/cli-mcp-parity.md).
+- Run schemas now distinguish runner execution, interactive execution,
+  interactive authoring, and deterministic verification (new optional
+  `kind` values plus `lifecycleStatus`, `host`, and `abortReason`; every
+  v0.3 record keeps validating unchanged).
+
+Security:
+
+- No arbitrary filesystem, shell, or Git MCP tool; no user-supplied
+  executable or working directory; one pinned project root per server
+  process.
+- No model-controlled stage approval: approval is not an MCP tool or
+  prompt, and the plugin approve skill sets disable-model-invocation.
+- No nested Claude invocation from the plugin or MCP handlers — enforced by
+  automated content scans and tests.
+- No stdout logging under stdio (structured stderr only, verified
+  process-level); no secrets, prompts, or file contents in logs; run views
+  and resources never expose raw prompts or runner output;
+  `.specbridge/config.json` is only ever reported as a redacted status.
+- Candidate hash binding prevents validation/apply substitution; there is
+  no force option.
+- State-changing MCP operations serialize behind a per-project write mutex,
+  with the repository lock file guarding cross-process interactive runs.
+- No automatic Git commit, push, reset, stash, or rollback — including
+  after protected-path violations, which are reported instead.
+
+Deferred (documented on the roadmap, not claimed):
+
+- production multi-runner support (v0.6)
+- templates, plugin SDK, extension registry, community ecosystem (v0.7)
+- remote MCP transports (HTTP/SSE/WebSocket), MCP OAuth, cloud hosting
+- public marketplace submission; npm publication of the packages
+- `spec sync` / `spec export`, SARIF output, Action PR comments
+
 ## 0.4.0
 
 Added:

README.md

@@ -14,9 +14,42 @@ Codex, local models, or any supported coding agent.
 
 > Your `.kiro` specs remain the source of truth.
 
-Now with deterministic spec drift verification (v0.4) — Kiro helps you
-write specs; SpecBridge verifies whether the implementation still matches
-them:
+New in v0.5 — a self-contained **Claude Code plugin** with a local MCP
+server and verified interactive task execution:
+
+```text
+/plugin marketplace add HelloThisWorld/specbridge
+/plugin install specbridge@specbridge-plugins
+/reload-plugins
+```
+
+Then, inside any project that contains `.kiro/`:
+
+```text
+/specbridge:doctor
+/specbridge:status
+/specbridge:implement notification-preferences 2.3
+/specbridge:verify
+```
+
+```text
+/specbridge:implement
+        ↓
+task_begin
+        ↓
+current Claude session edits
+        ↓
+task_complete
+        ↓
+Git evidence + trusted verification
+        ↓
+verified task completion
+```
+
+The plugin bundles everything (CLI + MCP server + skills) — no global npm
+install, no nested Claude processes, and stage approval stays an explicit
+human action. Deterministic spec drift verification (v0.4) still guards the
+other end:
 
 ```text
 approved spec
@@ -179,6 +212,8 @@ Working today (fully offline, no model, no API key):
 | `specbridge spec affected` | **v0.4** — which specs does this change set touch (read-only) |
 | `specbridge spec policy init / show / validate` | **v0.4** — per-spec verification policies (impact areas, required commands, rule overrides) |
 | `specbridge verify rules / explain <id>` | **v0.4** — inspect the stable rule registry SBV001–SBV025 |
+| `specbridge mcp serve / doctor / manifest / tools` | **v0.5** — local stdio MCP server (21 tools, 7 resources, 4 prompts) |
+| `specbridge run recover-lock` | **v0.5** — diagnose and explicitly recover the interactive execution lock |
 
 Planned commands (`spec sync/export`) are registered, marked "(planned)" in
 `--help`, and exit with an honest error — see the [roadmap](docs/roadmap.md).
@@ -444,7 +479,19 @@ SpecBridge stores no credentials of any kind.
   secrets or environment variables.
 - Full model: [docs/security.md](docs/security.md).
 
-## Limitations (v0.4)
+## Limitations (v0.5)
+
+- The MCP server is stdio-only and local-only: no HTTP/SSE/WebSocket
+  transport, no OAuth, no cloud hosting. One server process serves one
+  project root.
+- The plugin requires Node.js 20+ on PATH (the same requirement as Claude
+  Code) and a Git repository for interactive task execution.
+- Interactive execution is strictly one task per run per repository,
+  guarded by a lock file; recovery after a crash is explicit
+  (`specbridge run recover-lock`), never automatic.
+- Claude Code plugin-scoped MCP tool prefixes are host-generated; skills
+  reference tools by short name, and the effective prefixes are only
+  verifiable inside a real Claude Code session (`/mcp`).
 
 - Verification is deterministic, not semantic: it proves traceability,
   approval, evidence, scope, and command facts — it cannot judge whether
@@ -485,12 +532,14 @@ v0.2: offline spec authoring, deterministic analysis, hash-based approvals,
 stale-approval detection. v0.3: agent runner contract, the Claude Code local
 runner, model-assisted generation/refinement, approved task execution with
 git snapshots, trusted verification, append-only evidence, verified-only
-checkbox completion, manual acceptance, resumable sessions. v0.4 (this
-release): deterministic drift verification (rule engine SBV001–SBV025,
-policies, affected-spec resolution, evidence freshness, normalized task-plan
-approval hash, four report formats) and the production GitHub Action. Next:
-MCP server (K), more runners, `spec sync`/`spec export`, SARIF.
-Full detail: [docs/roadmap.md](docs/roadmap.md).
+checkbox completion, manual acceptance, resumable sessions. v0.4:
+deterministic drift verification (rule engine SBV001–SBV025, policies,
+affected-spec resolution, evidence freshness, four report formats) and the
+production GitHub Action. v0.5 (this release): the local stdio MCP server,
+direct interactive task execution, and the self-contained Claude Code
+plugin with its repository-local marketplace. Next — v0.6: production
+multi-runner support. v0.7: templates, plugin SDK, extension registry,
+community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
 
 ## Documentation
 
@@ -517,6 +566,18 @@ Full detail: [docs/roadmap.md](docs/roadmap.md).
 [GitHub Action](docs/github-action.md) ·
 [CI quality gates](docs/ci-quality-gates.md) ·
 [Claude Code integration](docs/claude-code-integration.md) ·
+[MCP server](docs/mcp-server.md) ·
+[MCP tools](docs/mcp-tools.md) ·
+[MCP resources](docs/mcp-resources.md) ·
+[MCP prompts](docs/mcp-prompts.md) ·
+[Interactive task execution](docs/interactive-task-execution.md) ·
+[Claude Code plugin](docs/claude-code-plugin.md) ·
+[Plugin installation](docs/plugin-installation.md) ·
+[Plugin development](docs/plugin-development.md) ·
+[Plugin marketplace](docs/plugin-marketplace.md) ·
+[Plugin security](docs/plugin-security.md) ·
+[Plugin release](docs/plugin-release.md) ·
+[CLI/MCP parity](docs/cli-mcp-parity.md) ·
 [Migration from Kiro](docs/migration-from-kiro.md) (spoiler: there is none) ·
 [Roadmap](docs/roadmap.md) ·
 [Changelog](CHANGELOG.md)

docs/architecture.md

@@ -15,16 +15,19 @@ instead of duplicating logic.
 | `@specbridge/drift` | Deterministic drift verification (v0.4): git comparison resolution, spec policies, the SBV001–SBV025 rule engine, affected-spec resolution, trusted-command orchestration, schema-validated report assembly — plus the v0.1 primitives |
 | `@specbridge/runners` | Model/agent adapters behind one `AgentRunner` interface (mock implemented; CLI runners detection-only) |
 | `@specbridge/reporting` | Terminal formatting, JSON report envelope, self-contained HTML rendering |
-| `specbridge` (packages/cli) | Commander-based CLI wiring the above together |
+| `@specbridge/mcp-server` | v0.5 local stdio MCP server: typed tool/resource/prompt adapters over the packages above, SBMCP error model, bounded outputs, per-project write mutex — no duplicated logic |
+| `specbridge` (packages/cli) | Commander-based CLI wiring the above together (including `mcp serve/doctor/manifest/tools`) |
 
 Dependency direction (arrows = "may import"):
 
 ```
 cli ──▶ workflow ──▶ compat-kiro ──▶ core
 cli ──▶ reporting   ──▶ core
 cli ──▶ drift ─▶ compat-kiro, core, workflow, evidence, runners
+cli ──▶ mcp-server ─▶ compat-kiro, core, workflow, execution, evidence, drift
 runners ─▶ core
 integrations/github-action ─▶ drift, reporting, core (bundled; no CLI dependency)
+integrations/claude-code-plugin ─▶ cli + mcp-server (bundled; self-contained at runtime)
 ```
 
 ## Design principles

docs/claude-code-plugin.md

@@ -0,0 +1,108 @@
+# Claude Code plugin
+
+A self-contained Claude Code plugin that turns the SpecBridge workflow into
+namespaced `/specbridge:*` commands backed by the bundled MCP server and
+CLI. After installation the plugin needs nothing outside its own directory:
+no global npm install, no workspace resolution, no network for normal
+operation — only Node.js 20+ on `PATH`.
+
+## Directory structure
+
+```text
+integrations/claude-code-plugin/specbridge/
+├── .claude-plugin/
+│   └── plugin.json            plugin metadata (ONLY metadata lives here)
+├── .mcp.json                  bundled stdio MCP server configuration
+├── README.md · LICENSE · NOTICE.md
+├── skills/
+│   ├── doctor/SKILL.md        /specbridge:doctor
+│   ├── status/SKILL.md        /specbridge:status [spec]
+│   ├── new/SKILL.md           /specbridge:new <spec> [description]
+│   ├── author/SKILL.md        /specbridge:author <spec> <stage> [note]
+│   ├── approve/SKILL.md       /specbridge:approve <spec> <stage>   (human-only)
+│   ├── implement/SKILL.md     /specbridge:implement <spec> [task]
+│   ├── continue/SKILL.md      /specbridge:continue <run-id>
+│   └── verify/SKILL.md        /specbridge:verify [spec]
+├── bin/
+│   ├── specbridge             POSIX wrapper → dist/cli.cjs
+│   └── specbridge.cmd         Windows wrapper → dist/cli.cjs
+└── dist/
+    ├── cli.cjs                self-contained SpecBridge CLI (CJS bundle)
+    ├── mcp-server.cjs         self-contained MCP server (CJS bundle)
+    ├── THIRD_PARTY_LICENSES.txt
+    └── checksums.json         SHA-256 manifest of the bundle
+```
+
+`.mcp.json` launches the bundled server for the current project:
+
+```json
+{
+  "mcpServers": {
+    "specbridge": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.cjs",
+        "--stdio",
+        "--project-root",
+        "${CLAUDE_PROJECT_DIR}"
+      ]
+    }
+  }
+}
+```
+
+`${CLAUDE_PLUGIN_ROOT}` keeps the configuration cache-safe: the plugin works
+from wherever Claude Code copies it, with no absolute build-machine path
+anywhere in the artifact.
+
+## Skill design
+
+Skills are **thin orchestration** — they call the MCP tools for inspection
+and controlled lifecycle operations and never duplicate core logic:
+
+- `doctor`/`status` are read-only (`workspace_detect`, `spec_list`,
+  `spec_status`).
+- `new` previews with `spec_create(apply: false)` and creates only after
+  explicit confirmation.
+- `author` drafts in the current session, validates with
+  `spec_stage_validate`, shows the diff, and applies via `spec_stage_apply`
+  only after explicit confirmation — the stage remains unapproved.
+- `approve` is the human gate: `disable-model-invocation: true` (Claude can
+  never trigger it), a narrowly scoped Bash allowance for exactly
+  `"${CLAUDE_PLUGIN_ROOT}/bin/specbridge" spec approve …`, and a final
+  explicit confirmation before the CLI runs.
+- `implement` uses the interactive lifecycle
+  (`task_begin` → this session edits → `task_complete`) and reports the
+  ACTUAL evidence outcome. It never invokes `specbridge spec run`, `claude
+  -p`, or any nested agent — that invariant is enforced by automated scans
+  in `pnpm validate:plugin` and the test suite.
+- `continue` finishes an interrupted interactive run honestly (never
+  presenting a fresh run as a resumption).
+- `verify` runs `spec_check_drift` and asks before `spec_run_verification`.
+
+No skill uses `bypassPermissions`, `dangerously-skip-permissions`,
+unrestricted `Bash(*)`, or unrestricted `Write`, and no skill instructs
+direct edits to `.kiro` or `.specbridge`.
+
+## Tool scoping
+
+Claude Code prefixes tools from plugin-bundled MCP servers with a
+host-generated scope (visible via `/mcp`), which may differ from manually
+configured servers. Skills therefore reference tools by their short names
+(`task_begin`, `spec_status`, …). Nothing in the server hardcodes a prefix.
+
+## Why no nested Claude invocation
+
+The plugin's implementation workflow must never start a second agent: the
+current session already IS the agent, a nested run would double cost and
+confuse permissions, and evidence attribution assumes exactly one actor
+between the Git snapshots. The v0.3 runner (`specbridge spec run`) remains
+fully supported **from the standalone CLI** for users who want detached
+execution — it is only the plugin path that forbids it. Automated tests scan
+the skills and the interactive execution code for `claude -p`,
+`spec run`, runner-registry usage, and process spawning.
+
+See [plugin-installation.md](plugin-installation.md),
+[plugin-development.md](plugin-development.md),
+[plugin-security.md](plugin-security.md), and
+[plugin-release.md](plugin-release.md).