Skip to content

flurdy/agent-skills / skills/beads-check-dolt-migration

beads-check-dolt-migration

Verified

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

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

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:

# 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

Safety gate before store-opening probes: bd may auto-migrate on store open. On an old, unknown or potentially pending schema, stop at file-only evidence unless the installed probe path is proven nonmutating. Recommend the migration core's protected-backup path for separate authorization; do not perform its backup or migration from this read-only check. The bd commands below are conditional on that proof, not permission to open an unprotected store.

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

For a Dolt repository also run:

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

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:

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

StateIndicatorsRecommendation
Classicbeads.db exists, no Dolt directoryFull migration needed
JSONL-onlyissues.jsonl exists, no SQLite or Dolt directoryInitialize Dolt and import
Dolt, currentDolt directory exists, bd migrate --inspect reports no pending migrationsNo migration needed
Dolt, pending (local-only)Inspection reports pending migrations and no Dolt remoteBack up, then run the schema-upgrade path
Dolt, pending (remote-backed)Inspection returns remote_migrate_gateChoose exactly one designated clone to migrate and push; every other clone must adopt with bd bootstrap
Partial/broken DoltDolt directory exists but bd list or bd dolt status failsDiagnose and recover from backup or bootstrap; do not destroy data automatically
No beadsNo .beads/ directoryRun 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.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall