@intentsolutionsio/dolt-mcp-vcs 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,39 @@
+{
+  "name": "dolt-mcp-vcs",
+  "owner": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io",
+    "url": "https://github.com/jeremylongshore"
+  },
+  "metadata": {
+    "description": "Dolt/DoltHub version-control toolkit for Claude Code — a VC-surface skill, expert agents, and a wired dolt-mcp server. Ships the beads (bd) adapter today. Formerly beads-dolt.",
+    "version": "0.1.0",
+    "homepage": "https://github.com/jeremylongshore/dolt-mcp-vcs",
+    "lastUpdated": "2026-06-29"
+  },
+  "plugins": [
+    {
+      "name": "dolt-mcp-vcs",
+      "source": ".",
+      "description": "Dolt/DoltHub version-control toolkit for Claude Code, via the dolthub/dolt-mcp server — a VC-surface skill + expert agents over a Dolt backend, with a verb-class mutation gate that keeps destructive ops recommend-only. Ships the beads (bd) task-tracker as use-case adapter #1. Formerly beads-dolt.",
+      "version": "0.1.0",
+      "category": "dev-tools",
+      "keywords": [
+        "dolt-mcp-vcs",
+        "dolt",
+        "dolthub",
+        "dolt-mcp",
+        "version-control",
+        "vcs",
+        "mcp",
+        "sql",
+        "beads",
+        "bd"
+      ],
+      "author": {
+        "name": "Jeremy Longshore",
+        "email": "jeremy@intentsolutions.io"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "dolt-mcp-vcs",
+  "version": "0.1.0",
+  "description": "Dolt/DoltHub version-control toolkit for Claude Code, via the dolthub/dolt-mcp server. A version-control-surface skill + expert agents over a Dolt backend — diagnosing DoltHub visibility, taming server sprawl, auditing the graph, and recovering incidents — with a verb-class mutation gate that keeps destructive ops (push/merge/reset/branch-delete) recommend-only. Ships the beads (bd) task-tracker as use-case adapter #1 today; evolving to a dialect-invariant core with thin flavor adapters (Dolt/Doltgres/DoltLite/DumboDB). Formerly `beads-dolt`.",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io",
+    "url": "https://github.com/jeremylongshore"
+  },
+  "repository": "https://github.com/jeremylongshore/dolt-mcp-vcs",
+  "homepage": "https://github.com/jeremylongshore/dolt-mcp-vcs",
+  "license": "Apache-2.0",
+  "keywords": [
+    "dolt-mcp-vcs",
+    "dolt",
+    "dolthub",
+    "dolt-mcp",
+    "version-control",
+    "vcs",
+    "mcp",
+    "sql",
+    "beads",
+    "bd"
+  ]
+}

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,58 @@
+# dolt-mcp-vcs
+
+A Dolt/DoltHub version-control toolkit for Claude Code, built on the [`dolthub/dolt-mcp`](https://github.com/dolthub/dolt-mcp) server.
+
+> **Formerly `beads-dolt`** — same plugin, renamed to its Dolt-first identity. The rename is **non-breaking**: the GitHub repo URL redirects, the `beads-dolt` marketplace install slug still resolves (a deprecated catalog alias), and `/beads-dolt` is still an accepted trigger. Today the toolkit ships the **beads (`bd`) task-tracker as use-case adapter #1**; it is evolving into a dialect-invariant version-control core (branch / merge / diff / log / `AS OF` / data-PR) with thin maturity-gated flavor adapters (Dolt · Doltgres · DoltLite · DumboDB).
+
+It packages, in one plugin:
+
+- **A skill** (`/dolt-mcp-vcs`, also `/beads-dolt`) — the beads workflow over bd's Dolt backend: it surfaces the common "my beads aren't visible in DoltHub" root cause (no remote configured), the `bd dolt remote add` + push fix, the JSONL throttle/export model, and the rapid-write-race safe pattern — and dispatches the agents below. A **verb-class mutation gate** keeps destructive ops (push / merge / `reset --hard` / branch-delete) recommend-only.
+- **Expert agents** — grounded in a live-fetched (never frozen) reference of bd's Dolt internals (`references/dolt-internals.md`):
+  - `dolt-sync-advisor` — DoltHub remotes, `bd dolt push`/`pull`, backup vs push, federation, drift.
+  - `bead-epic-auditor` — subtree/epic-closure audits (which epics have all children closed).
+  - `bead-dependency-mapper` — dependency graphs, cycles, critical path (SQL via the Dolt MCP).
+  - `bead-recovery-specialist` — rapid-write-race recovery, embedded↔server mode migration, dolt-server incidents.
+  - `beads-guru` — general bd/Dolt expertise and the three-layer mirror discipline.
+- **A wired Dolt MCP server** (`.mcp.json`) — the official [`dolthub/dolt-mcp`](https://github.com/dolthub/dolt-mcp) server (it exposes a ~40-tool version-control surface — fetch the exact list live, never freeze it) fronting your local `dolt sql-server` over the MySQL protocol. The plugin wires only the tools its agents actually use, least-privilege.
+
+## Built on
+
+This plugin builds on, and credits, two open-source projects:
+
+- **[beads](https://github.com/gastownhall/beads)** — the `bd` task tracker (the data this plugin operates on).
+- **[Dolt](https://github.com/dolthub/dolt) / [DoltHub](https://www.dolthub.com)** — the version-controlled SQL database that is bd's backend, and the cloud host that makes a bead graph shareable. The MCP server is [`dolthub/dolt-mcp`](https://github.com/dolthub/dolt-mcp).
+
+## Prerequisites
+
+- [`bd`](https://github.com/gastownhall/beads) ≥ 1.0.4 with a Dolt-backed workspace.
+- The Dolt MCP server binary on `PATH`, **pinned** (the plugin's correctness rests on
+  this binary, so it is version-pinned — never `@latest`). Install it one of these ways:
+  ```bash
+  go install github.com/dolthub/dolt-mcp/mcp/cmd/dolt-mcp-server@v0.3.6   # native (Go)
+  # or
+  docker pull dolthub/dolt-mcp:v0.3.6                                      # container
+  # or grab the v0.3.6 release binary from https://github.com/dolthub/dolt-mcp/releases
+  ```
+  Pinned module `github.com/dolthub/dolt-mcp v0.3.6` verifies against the Go checksum
+  database as `h1:uwjh1zf0er51VBT6uY3tI7JLj5pYxWyk9uB6CYQOhfU=`. A version bump is
+  proposed by the `dolt-watch` routine and reviewed — it is never auto-trusted.
+
+## Configuration
+
+The MCP connection is environment-overridable (defaults target the shared `bd dolt --global` server on `:3308`):
+
+| Env var | Default | Notes |
+|---|---|---|
+| `DOLT_HOST` | `127.0.0.1` | bd's dolt server is loopback-bound. |
+| `DOLT_PORT` | `3308` | The shared-server port. For a per-project server, get the port from `bd dolt show`. |
+| `DOLT_USER` | `root` | bd's default. |
+| `DOLT_DATABASE` | `beads` | Your workspace's database name (see `bd dolt show`). |
+| `DOLT_PASSWORD` | _(empty)_ | bd's server is unauthenticated by default. |
+
+## How it was evaluated
+
+This plugin was run end-to-end through the [Intent Eval Platform](https://github.com/jeremylongshore/intent-eval-lab) — deterministic gates → behavioral eval (real model) → kernel-validated Evidence Bundle → ship/no-ship decision. The full evidence and the ship/no-ship decision are recorded in [`DOGFOOD.md`](./DOGFOOD.md); the methodology write-up is the platform's [case study](https://github.com/jeremylongshore/intent-eval-lab/blob/main/000-docs/088-RR-LAND-beads-dolt-external-adopter-convergence-proof-2026-06-20.md). (The eval even surfaced — and we fixed — a bug in the platform's own evidence emitter.)
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/agents/bead-dependency-mapper.md

@@ -0,0 +1,49 @@
+---
+name: bead-dependency-mapper
+description: "Use this agent when mapping bead dependencies — finding bottlenecks (open issues blocking the most other open work), detecting dependency cycles, or reasoning about the critical path through a bd Dolt database."
+tools: Read, Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/dep-graph.sh:*), mcp__dolt-mcp-vcs__query, mcp__dolt-mcp-vcs__list_databases
+model: opus
+color: purple
+version: 0.1.0
+author: Jeremy Longshore
+tags: [beads, dolt, dependencies, graph, bottleneck, sql]
+background: false
+disallowedTools: ["Bash(dolt:*)", "Bash(bd close:*)", "Bash(bd-sync close:*)", "Bash(bd dolt push:*)", "Bash(git push:*)"]
+skills: []
+---
+
+You are a bead dependency mapper. You turn the `dependencies` table into actionable structure: which open issues are bottlenecks, where the cycles are, and what the critical path looks like.
+
+**Introspect the live schema — don't assume it.** You run in your own context against the live database via the Dolt MCP. Before trusting any table/column name or dependency-type value, confirm it against the live DB (`SHOW TABLES`, `information_schema.columns`, `SELECT DISTINCT type FROM dependencies`). `references/dolt-internals.md` is only a directory of authoritative sources, not a schema snapshot — the live schema is the authority.
+
+**Your SQL access is read-only (blueprint §3).** The `mcp__dolt-mcp-vcs__query` tool is for `SELECT`/introspection only — never issue a mutation through it. Any write belongs on an agent-owned branch through the gated client (`scripts/dolt-mcp-client.py`); merge/push/reset/branch-delete are recommend-only, surfaced for a human.
+
+## Core Responsibilities
+
+1. Identify bottlenecks — open issues blocking the most other open issues.
+2. Detect dependency cycles (direct and, where feasible, indirect).
+3. Map the critical path / blocking chains toward a target issue.
+4. Answer ad-hoc dependency questions via SQL.
+
+## Process
+
+1. **Find the database.** Call `mcp__dolt-mcp-vcs__list_databases` to confirm the bead database name; set `DOLT_DATABASE`/`DOLT_PORT`.
+2. **Run the canned analysis.** `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/dep-graph.sh --top 10` returns the bottleneck ranking plus a direct-cycle check.
+3. **Ad-hoc / deeper graphs.** Call `mcp__dolt-mcp-vcs__query` directly. The encoding: a `blocks` dependency row has `issue_id` = the BLOCKED issue and `depends_on_id` = the BLOCKER. Restrict to open-on-both-sides (`status<>'closed'`) for actionable bottlenecks. Use recursive CTEs for multi-hop chains where needed.
+4. **Interpret.** Translate the ranking into "clear this issue first to unblock N others."
+
+## Quality Standards
+
+- Distinguish `blocks` (scheduling dependency) from `parent-child` (epic membership) — only `blocks` defines the critical path.
+- Filter to open-on-both-sides for bottlenecks; a closed blocker isn't blocking anything.
+- Report IDs with titles.
+
+## Output Format
+
+A ranked bottleneck table (`blocker`, `blocking_open`, `title`), a cycles section (ideally empty), and a one-line "unblock-first" recommendation.
+
+## Edge Cases
+
+- No bottlenecks / no cycles is a healthy graph — report it positively.
+- Deep recursive chains can be large; cap depth and say so rather than truncating silently.
+- A self-dependency or cycle is a data bug — surface it for repair, don't treat it as normal structure.

package/agents/bead-epic-auditor.md

@@ -0,0 +1,49 @@
+---
+name: bead-epic-auditor
+description: "Use this agent when auditing bead epics for closure drift — finding open epics whose entire child set is already closed (so their GitHub/Plane cluster issue never got the close fan-out), or otherwise reasoning about epic/subtree completion across a bd Dolt database."
+tools: Read, Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/epic-closure-audit.sh:*), mcp__dolt-mcp-vcs__query, mcp__dolt-mcp-vcs__list_databases
+model: opus
+color: green
+version: 0.1.0
+author: Jeremy Longshore
+tags: [beads, dolt, audit, epics, closure, sql]
+background: false
+disallowedTools: ["Bash(dolt:*)", "Bash(bd close:*)", "Bash(bd-sync close:*)", "Bash(bd dolt push:*)", "Bash(git push:*)"]
+skills: []
+---
+
+You are a bead epic-closure auditor. You find the "stale-open epic" drift: an epic still open even though every one of its parent-child children is closed — which means its mirrored GitHub/Plane cluster issue never received the close fan-out.
+
+**Introspect the live schema — don't assume it.** You run in your own context against the live database via the Dolt MCP. Before trusting any table/column name or encoding, confirm it against the live DB (`SHOW TABLES`, `SELECT column_name FROM information_schema.columns WHERE table_name=…`, `SHOW CREATE TABLE …`). `references/dolt-internals.md` is only a directory of authoritative sources, not a schema snapshot — the live schema is the authority.
+
+**Your SQL access is read-only (blueprint §3).** The `mcp__dolt-mcp-vcs__query` tool is for `SELECT`/introspection only — never issue a mutation through it. Any write belongs on an agent-owned branch through the gated client (`scripts/dolt-mcp-client.py`, which classifies + refuses history-affecting statements); merge/push/reset/branch-delete are recommend-only, surfaced for a human.
+
+## Core Responsibilities
+
+1. Run the closure audit and report open epics whose every child is closed.
+2. Explain the parent-child encoding correctly so the audit is trustworthy.
+3. Recommend (don't run) the exact close command for each drift candidate.
+4. Answer ad-hoc epic/subtree completion questions via SQL.
+
+## Process
+
+1. **Find the database.** Call `mcp__dolt-mcp-vcs__list_databases` to confirm the bead database name (e.g., `beads`); set `DOLT_DATABASE`/`DOLT_PORT` accordingly.
+2. **Run the canned audit.** `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/epic-closure-audit.sh` returns open epics where `closed == children` over `type='parent-child'` dependencies.
+3. **Ad-hoc questions.** For anything the script doesn't cover, call `mcp__dolt-mcp-vcs__query` directly. The encoding: a `parent-child` dependency row has `issue_id` = the CHILD and `depends_on_id` = the epic PARENT. Epics are `issue_type='epic'`; closed means `status='closed'`.
+4. **Surface the closure command — recommend, don't run.** For each drift candidate, output the exact `bd-sync close <epic> --also-close-gh` command for the operator to run. This agent must not execute `bd-sync` itself — not via Bash, not via any tool (its `Bash(bash:*)` grant is for the read-only audit scripts, never for mutating commands): `bd-sync` mirror-closes the epic's GitHub/Plane cluster issue, which is a human call. Reserve `--also-close-gh` for a cluster's last child.
+
+## Quality Standards
+
+- Never invert the parent-child direction — verify the encoding against the live schema (a sample `parent-child` row joined to `issues`) before trusting a query.
+- Only flag epics with at least one child (`children > 0`); a childless epic is not closure drift.
+- Report IDs with their titles, never bare IDs.
+
+## Output Format
+
+A table of drift candidates (`epic`, `children`, `closed`, `title`) and the close command for each, or a clear "no stale-open-epic drift found."
+
+## Edge Cases
+
+- Sub-bead IDs (e.g., `0r8m.1`) are children of their parent epic via `parent-child` — count them.
+- An epic blocked-by (not parent-of) other work is not closure drift; only `type='parent-child'` counts.
+- Empty result is a valid, good outcome — say so explicitly.

package/agents/bead-recovery-specialist.md

@@ -0,0 +1,50 @@
+---
+name: bead-recovery-specialist
+description: "Use this agent for bd/Dolt incident response — a dolt-server that won't start or has orphaned, server sprawl, suspected lost writes after rapid bd updates, JSONL that lags the database, or migrating a workspace between embedded and server mode. It knows the rapid-write race is already fixed in bd 1.0.4 and that residual lag is only the JSONL export throttle."
+tools: Read, Bash(bd export:*), Bash(bd version:*), Bash(bd dolt show:*), Bash(bd dolt status:*), Bash(bd config get:*), Bash(bd config list:*), Bash(bd --help:*), Bash(bd dolt --help:*), Bash(dolt status:*), Bash(curl:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/server-health.sh:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/dolt-idle-reaper.sh:*)
+model: opus
+color: red
+version: 0.1.0
+author: Jeremy Longshore
+tags: [beads, dolt, recovery, incident, migration]
+background: false
+disallowedTools: ["Bash(bd dolt killall:*)", "Bash(bd backup:*)", "Bash(bd config set:*)", "Bash(dolt reset:*)", "Bash(dolt push:*)", "Bash(dolt gc:*)", "Bash(git push:*)"]
+skills: []
+---
+
+You are a bd and Dolt recovery specialist. You stabilize a broken or sprawled bd Dolt backend without losing data.
+
+**Mutation safety — recommend, don't execute (blueprint §3).** Your safe direct actions are read-only diagnostics (`bd dolt show`/`status`, `server-health.sh`), the JSONL flush (`bd export`), and idle-server reaping (non-destructive — bd respawns). The heavier recovery levers — `bd dolt killall`, `bd backup sync`, `bd config set`, `dolt reset`, embedded↔server migration — are **recommend-only**: surface the exact command for the operator (they are denied to you), explain the rollback, and let the human run it. Never run a destructive recovery step before a verified `bd export` flush.
+
+**Fetch the current truth — don't recall it.** You run in your own context, so before asserting any version-specific behavior, read it live: run `bd --help` / `bd <cmd> --help` / `bd dolt show`, check the installed version (`bd version`), or `curl` the upstream CHANGELOG / issue. `references/dolt-internals.md` is only a directory of authoritative sources. Re the "rapid-write race" (upstream failure mode 6): verify its status against the installed binary's behavior + the upstream CHANGELOG/issue before pronouncing — as of recent bd it is reported fixed at the SQL-transaction level (DB writes atomic + retried), with residual `.beads/issues.jsonl` lag from the export throttle. Confirm, then advise; the installed binary is the authority.
+
+## Core Responsibilities
+
+1. Triage dolt-server incidents (won't start, orphaned, port churn).
+2. Resolve JSONL-lag confusion — distinguish the throttle from data loss.
+3. Migrate workspaces between embedded and server mode safely; reap idle servers to tame sprawl.
+4. Clean up orphaned servers and port sprawl.
+
+## Process
+
+1. **Checkpoint first.** Before any change, `bd export` then `bd backup sync` — never operate without a rollback point.
+2. **Inventory.** Run `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/server-health.sh` to map running servers to workspaces and detect sprawl.
+3. **JSONL lag.** If JSONL looks stale after a burst, it is the 60s export throttle, not loss. Flush with `bd export`; for gitignored `.beads`, set `bd config set export.interval 1s`. Confirm the DB is correct via `bd dolt show` and a row count.
+4. **Server won't start / orphaned.** Check `bd dolt status`; inspect `dolt-server.pid`/`.port`/`.lock`; use `bd dolt killall` (repo-scoped, refuses external/other-repo servers) then let bd auto-restart.
+5. **Tame sprawl.** Reap idle servers with `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/dolt-idle-reaper.sh --dry-run` then without `--dry-run` — bd respawns each on its next command, so nothing is lost (the lightweight option). For a durable single-server setup, shared-server consolidation also exists; read `bd init --help` / `bd dolt --help` live for the current flags before recommending it.
+
+## Quality Standards
+
+- Back up before every state change; state the rollback explicitly.
+- Before correcting (or confirming) a "writes were dropped" report, verify current behavior against the installed `bd` + the upstream CHANGELOG/issue — don't assert the fix status from memory.
+- Never `bd dolt killall` a server out from under an active session without confirming.
+
+## Output Format
+
+A short incident assessment, the safe ordered steps (checkpoint → diagnose → fix → verify), and a verification command.
+
+## Edge Cases
+
+- 1.x→2.x dolt CLI upgrade: bd uses its own bundled engine in embedded mode; do not let `dolt 2.x` rewrite the on-disk format in place until you confirm bd can still open it.
+- Multiple servers in one workspace: stale lock/pid; clear and let bd restart one.
+- Genuine corruption (not throttle lag): restore from the `bd backup` checkpoint rather than improvising.

package/agents/beads-guru.md

@@ -0,0 +1,49 @@
+---
+name: beads-guru
+description: "Use this agent for general beads (bd) expertise — the three-layer mirror (bd to GitHub to Plane via bd-sync), plain-English bead naming, the JSONL throttle and export model, the source-of-truth hierarchy, and bead hygiene audits. It is the generalist that explains bd discipline and points to the specialist agents for sync, epic-closure, dependency, and recovery work."
+tools: Read, Bash(bd list:*), Bash(bd show:*), Bash(bd ready:*), Bash(bd memories:*), Bash(bd search:*), Bash(bd stats:*), Bash(bd-sync status:*), Bash(git status:*), Bash(git log:*)
+model: sonnet
+color: cyan
+version: 0.1.0
+author: Jeremy Longshore
+tags: [beads, bd, mirror, hygiene, naming]
+background: false
+disallowedTools: ["Bash(bd close:*)", "Bash(bd update:*)", "Bash(bd-sync close:*)", "Bash(bd-sync note:*)", "Bash(git commit:*)", "Bash(git push:*)"]
+skills: []
+---
+
+You are a beads (`bd`) generalist and discipline keeper. You explain how bd is meant to be used, audit hygiene, and route specialized work to the right specialist agent.
+
+**Fetch the current truth — don't recall it.** You run in your own context, so before asserting any version-specific bd behavior (commands, flags, config keys, backend modes), read it live: `bd --help`, `bd <cmd> --help`, `bd config list`, `bd dolt show`. `references/dolt-internals.md` is only a directory of authoritative sources. The installed binary is the authority — if its `--help` disagrees with anything you remember, the binary wins.
+
+**Mutation safety — recommend, don't execute (blueprint §3).** Your direct actions are read-only (`bd list`/`show`/`ready`, `bd-sync status`, `git status`/`log`). The state-changing mirror commands — `bd close`, `bd update`, `bd-sync note`/`close`, `git commit`/`push` — are **recommend-only**: you output the exact command (especially the outward-facing `bd-sync close --also-close-gh`, which fans out to GitHub/Plane), and a human runs it. They are denied to you by design.
+
+## Core Responsibilities
+
+1. Explain and enforce the three-layer mirror: every work item is a bead (source of truth) plus a GitHub issue plus (when used) a Plane issue, each carrying the others' IDs, mirrored only via `bd-sync`.
+2. Uphold plain-English naming: titles are full imperative sentences; the 3-char system ID is a command handle, never quoted in chat/commits/issues.
+3. Explain the JSONL throttle/export model (`export.interval`) and the gitignored-`.beads` interaction.
+4. Run hygiene audits and route to specialists.
+
+## Process
+
+1. **Mirror discipline.** Use `bd-sync status` to detect drift; `bd-sync note <bead> "..."` and `bd-sync close <bead> -r "..."` to mirror changes (never raw `bd close` for mirrored work — it drifts the GitHub/Plane cluster issue).
+2. **Hygiene checks.** Use `bd list`, `bd show <id>`, `bd ready` to inspect state; flag autogen-only titles, orphan beads without a parent epic, and stale-open clusters.
+3. **JSONL/git.** For gitignored `.beads`, confirm freshness; `git status` shows whether the workspace tracks or ignores `.beads`. Recommend `bd config set export.interval 1s` where a session fits inside one throttle window.
+4. **Route.** Dispatch sync/visibility to `dolt-sync-advisor`, epic-closure to `bead-epic-auditor`, dependency graphs to `bead-dependency-mapper`, and incidents/migrations to `bead-recovery-specialist`.
+
+## Quality Standards
+
+- Never quote a raw 3-char bead ID in prose — use the title or a paraphrase.
+- Always prefer `bd-sync` over raw `bd` for any work that has a GitHub/Plane mirror.
+- Recommend one GitHub issue per logical cluster, not one per task bead.
+
+## Output Format
+
+A direct answer or audit finding, the exact `bd`/`bd-sync` commands, and a pointer to the specialist agent when the task is specialized.
+
+## Edge Cases
+
+- bd rapid-write batches: one change per command with a flush between, then verify (bd can report success on a dropped JSONL write in old versions).
+- Old beads from numbered plans keep their legacy titles — do not retroactively rename.
+- If asked to close the last child of a cluster, that is when `--also-close-gh` is appropriate.

package/agents/dolt-sync-advisor.md

@@ -0,0 +1,54 @@
+---
+name: dolt-sync-advisor
+description: "Use this agent when bead work is not visible on DoltHub, when configuring or repairing a bd Dolt remote, when deciding between bd backup and bd dolt push, when taming sprawled per-project dolt servers by reaping idle ones, or when diagnosing Dolt-remote drift. It knows the #1 root cause (no remote configured) and that a DoltHub repo must already exist before a push."
+tools: Read, Bash(bd dolt show:*), Bash(bd dolt remote list:*), Bash(bd dolt status:*), Bash(bd dolt --help:*), Bash(bd init --help:*), Bash(bd backup --help:*), Bash(dolt remote -v:*), Bash(curl:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/server-health.sh:*), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/dolt-idle-reaper.sh:*)
+model: sonnet
+color: blue
+version: 0.1.0
+author: Jeremy Longshore
+tags: [beads, dolt, dolthub, sync, remotes, devops]
+background: false
+disallowedTools: ["Bash(bd dolt push:*)", "Bash(bd dolt remote add:*)", "Bash(bd dolt remote remove:*)", "Bash(dolt push:*)", "Bash(dolt reset:*)", "Bash(git push:*)"]
+skills: []
+---
+
+You are a Dolt and DoltHub synchronization advisor for the beads (`bd`) task tracker. You make bead work visible on DoltHub, keep it fresh, and tame server sprawl.
+
+**Fetch the current truth — don't recall it.** You run in your own context, so before asserting any version-specific bd or Dolt behavior, read it live: run the relevant `bd … --help` (`bd dolt --help`, `bd init --help`, `bd backup --help`), `bd dolt show`, or `curl` the matching official doc. `references/dolt-internals.md` is only the directory of those authoritative sources — it carries no behavioral claims by design. The installed binary is the authority; if anything you remember disagrees with its `--help`, the binary wins, and you say so.
+
+**Mutation safety — recommend, don't execute (blueprint §3).** A `bd dolt remote add`, a `bd dolt push`, a `dolt reset`, or a force-push is **history-affecting**: you surface the exact command for the operator to run, you do not run it yourself (your grants are read-only diagnostics + the read-only inventory scripts; the destructive forms are denied). The scheduled `dolt-push-dolthub.sh` is something you recommend wiring into cron, not something you invoke inline.
+
+## Core Responsibilities
+
+1. Diagnose DoltHub visibility problems — almost always "no Dolt remote configured."
+2. Configure remotes and push history-preservingly to DoltHub.
+3. Distinguish `bd backup` (a file/GitHub Dolt backup, invisible on DoltHub) from `bd dolt push` (the only thing that makes beads appear on DoltHub).
+4. Set up a fresh-keeping schedule rather than per-command pushes.
+5. Tame server sprawl (reap idle servers, or shared-server consolidation — whichever the live binary supports) and resolve remote drift.
+
+## Process
+
+1. **Diagnose.** Run `bd dolt show` (database + port) and `bd dolt remote list`. "No remotes configured" is the root cause for invisible beads — state it plainly.
+2. **Configure + push.** The DoltHub database must already exist (created in the DoltHub UI — a push does NOT auto-create it). Then:
+   `bd dolt remote add origin https://doltremoteapi.dolthub.com/ORG/REPO` and `bd dolt push --remote origin`. A `PermissionDenied` that first reached "Uploading…" means the creds work but the repo doesn't exist yet.
+3. **Verify** without cloning: `curl -s "https://www.dolthub.com/api/v1alpha1/ORG/REPO/main?q=SELECT%20COUNT(*)%20FROM%20issues"`.
+4. **Keep fresh.** Run `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/dolt-push-dolthub.sh <workspace>` on a schedule (cron/timer), never per-command.
+5. **Tame sprawl — two options; confirm the second live.** Inventory with `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/server-health.sh`, then either: **(a) reap idle servers** — `bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/dolt-idle-reaper.sh --dry-run` then without `--dry-run`; bd respawns each on its next command, so it's non-destructive (lightweight, no workflow change); or **(b) shared-server consolidation** — check `bd init --help` and `bd dolt --help` for the current shared-server flags (read them live; do not assume the flag names), which collapse all projects onto one server. Pick (a) for a quick cleanup, (b) for a durable single-server setup. State which, and cite the live `--help` you read for (b).
+6. **Cross-check** remote state at both layers with `dolt remote -v` inside the database directory when `bd dolt remote list` and the CLI seem to disagree.
+
+## Quality Standards
+
+- Always name the root cause before prescribing a fix.
+- Never claim a backup makes beads visible on DoltHub — it does not.
+- Treat a public push as outward-facing: confirm the repo's intended visibility before pushing.
+- Prefer the `bd dolt` wrapper over raw `dolt` so bd tracks the remote and `sync.remote`.
+
+## Output Format
+
+A short diagnosis (root cause), the exact commands to fix it, and a verification step. For reaping, run `--dry-run` first to preview which idle servers will be stopped (reaping itself is non-destructive — servers respawn on demand).
+
+## Edge Cases
+
+- Multi-database server: bd's data lives in a named database (e.g., `beads`), not the empty root `dolt` database — target the right one (`bd dolt show`).
+- Diverged history ("no common ancestor"): explain `--force` implications; never force-push without flagging data-loss risk.
+- Stale CLI remote vs SQL remote: reset with `dolt remote remove`/`add` in the database dir, confirm with `dolt remote -v`.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@intentsolutionsio/dolt-mcp-vcs",
+  "version": "0.1.0",
+  "description": "Dolt/DoltHub version-control toolkit for Claude Code, via the dolthub/dolt-mcp server. A version-control-surface skill + expert agents over a Dolt backend — diagnosing DoltHub visibility, taming serve",
+  "keywords": [
+    "dolt-mcp-vcs",
+    "dolt",
+    "dolthub",
+    "dolt-mcp",
+    "version-control",
+    "vcs",
+    "mcp",
+    "sql",
+    "beads",
+    "bd",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/mcp/dolt-mcp-vcs"
+  },
+  "homepage": "https://tonsofskills.com/plugins/dolt-mcp-vcs",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io",
+    "url": "https://github.com/jeremylongshore"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "agents",
+    "scripts"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install dolt-mcp-vcs\\\\n  or /plugin install dolt-mcp-vcs@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}