# Beads Check Dolt Migration

> Detect whether a beads repository needs classic-to-Dolt migration or an in-place Dolt schema upgrade.

- Skill: `flurdy/beads-check-dolt-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flurdy/beads-check-dolt-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flurdy/beads-check-dolt-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: flurdy (https://skillmd.com/u/flurdy)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/flurdy/beads-check-dolt-migration

---


# Beads Migration and Schema Check

Read-only detection of whether a repository needs classic-to-Dolt migration, a Dolt schema upgrade, or no action. Reports the current state without changing files, databases, remotes, or Git state.

## When to Use

- Before running `/beads-migrate-to-dolt`
- After upgrading `bd`, especially across a minor or major version
- When `bd` reports pending schema migrations or a remote migration gate
- When `bd` commands fail and the storage format or schema may be stale
- When onboarding to a repo with beads

## Instructions

### 1. Check for Beads Installation

```bash
ls -la .beads/ 2>/dev/null
```

If no `.beads/` directory exists, report "No beads installation found" and stop.

### 2. Detect Storage Format

On-disk inspection is authoritative:

```bash
# Classic format indicators
test -f .beads/beads.db && echo "FOUND: SQLite database"
test -f .beads/issues.jsonl && echo "FOUND: JSONL issues file"

# Dolt format indicators
test -d .beads/dolt && echo "FOUND: server-mode Dolt directory"
test -d .beads/embeddeddolt && echo "FOUND: legacy embedded-Dolt directory"
test -f .beads/metadata.json && cat .beads/metadata.json
```

`issues.jsonl` is not proof of classic storage: modern bd can export JSONL for interchange while Dolt remains authoritative.

### 3. Check Configuration, Remotes, and Worktrees

```bash
cat .beads/config.yaml 2>/dev/null
git worktree list 2>/dev/null
```

For a Dolt repository also run:

```bash
bd dolt status 2>&1 || true
bd dolt remote list 2>&1 || true
bd config get no-push 2>&1 || true
```

Look for:
- `sync.remote` or `sync.branch` in config
- A configured Dolt remote
- Worktrees at `.git/beads-worktrees/` from the classic sync mechanism

### 4. Check bd and Schema Compatibility

```bash
bd --version 2>/dev/null
bd migrate --inspect --json 2>&1 || true
```

Treat the inspection output as diagnostic even when it exits non-zero. On bd 1.1+, a remote-backed database with pending migrations intentionally refuses automatic migration and returns a `remote_migrate_gate`. Do not bypass that gate during this read-only check.

For classic data, optionally collect the legacy diagnostic too:

```bash
bd doctor --migration=pre 2>&1 || true
```

Do not trust `bd doctor` to classify storage: newer versions may inspect configured defaults rather than the files on disk, and embedded mode may not support it.

### 5. Classify and Report

| State | Indicators | Recommendation |
|-------|------------|----------------|
| **Classic** | `beads.db` exists, no Dolt directory | Full migration needed |
| **JSONL-only** | `issues.jsonl` exists, no SQLite or Dolt directory | Initialize Dolt and import |
| **Dolt, current** | Dolt directory exists, `bd migrate --inspect` reports no pending migrations | No migration needed |
| **Dolt, pending (local-only)** | Inspection reports pending migrations and no Dolt remote | Back up, then run the schema-upgrade path |
| **Dolt, pending (remote-backed)** | Inspection returns `remote_migrate_gate` | Choose exactly one designated clone to migrate and push; every other clone must adopt with `bd bootstrap` |
| **Partial/broken Dolt** | Dolt directory exists but `bd list` or `bd dolt status` fails | Diagnose and recover from backup or bootstrap; do not destroy data automatically |
| **No beads** | No `.beads/` directory | Run `bd init` only if the repo should use beads |

Include in the report:
- Current storage format and mode
- bd CLI version
- Current and target schema versions, when available
- Issue count, when readable
- Configured Dolt remote or sync branch
- Whether `no-push` is enabled and will require a one-command approved override
- Whether classic worktrees exist
- Any `remote_migrate_gate` and its two choices
- Clear recommendation: migrate classic data, upgrade schema here, adopt another clone, repair, or do nothing

## Remote-Backed Upgrade Safety

When bd 1.1+ reports pending schema migrations on a database with a remote:

- Never set `BD_ALLOW_REMOTE_MIGRATE=1` during this check.
- Ask the operator which single clone is the designated migrator.
- The designated clone backs up, runs `BD_ALLOW_REMOTE_MIGRATE=1 bd migrate`, verifies, then pushes.
- Ask for explicit permission immediately before `bd dolt push`.
- Other clones preserve any unpushed issues, then use `bd bootstrap` to adopt the published schema. They must not migrate independently because that forks schema history.

## Rules

- This skill is strictly read-only. Never modify files, databases, remotes, or Git state.
- Always preserve output from commands that may fail on old formats or a migration gate.
- Prefer on-disk evidence over backend defaults reported by old `bd doctor` versions.
- Never recommend independent schema migration on multiple clones of one Dolt remote.