HelloThisWorld · HelloThisWorld · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/.claude-plugin/marketplace.json b/.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
+    }
+  ]
+}
diff --git a/.github/workflows/ci.yml b/.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
diff --git a/.gitignore b/.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/
 

diff --git a/CHANGELOG.md b/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:

diff --git a/README.md b/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)

diff --git a/docs/architecture.md b/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

diff --git a/docs/claude-code-plugin.md b/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).