/project-init

name: project-init
description: Use when beads/Dolt database initialization fails, when bd commands return errors about missing databases, when setting up beads in a new project, or when recovering from diverged Dolt history. Handles fresh init, bootstrap from remote, and recovery workflows.

Project Init: Beads/Dolt Database Setup and Recovery

<!-- Based on gastownhall/beads docs/SYNC_SETUP.md (MIT). Attribution: README "Built on". -->

**Announce at start:** "I'm using the project-init skill to set up or recover the beads database."

Iron Law: NEVER Run `bd init --force`

NEVER run bd init --force (deprecated in v1.0.4). Use the named-intent alternatives: bd init --reinit-local (preserves remote) or bd init --discard-remote (explicit destruction).

**Why:** Issue #2363 documents an AI agent that destroyed 247 issues via `bd init --force` cascade. The root cause was misdiagnosing "server can't connect" as "database missing". `bd init --force` is a nuclear option that should ONLY be run by a human who explicitly types it.

This Iron Law is the Production-Grade Doctrine applied to your data ledger: never take the shortcut that accepts catastrophic, irreversible risk.

| Action | Safe? | Use When | |--------|-------|----------| | `bd init` | ✅ Safe | Fresh project, no existing .beads/ | | `bd bootstrap` | ✅ Safe | Cloned repo with remote beads data | | `bd doctor --fix --yes` | ✅ Safe | Database exists but seems broken | | `bd init --force` | ❌ **NEVER** | **Deprecated (v1.0.4) — do NOT use** | | `bd init --reinit-local` | ⚠️ Recovery only | Reinitialize local state, preserve remote data | | `bd init --discard-remote` | ⚠️ Recovery only | Discard remote data and reinitialize (explicit destruction) |

Diagnostic Phase (Always Run First)

Before taking ANY action, run diagnostics to understand the current state:

bash scripts/diagnose.sh

One Bash call gathers the full read-only battery as labeled RAW DATA (no verdicts, no fixes): `bd`/`dolt` versions, `.beads/` presence, `config.yaml`/`metadata.json`, whether `bd list`/`bd vc status` work, and any dolt refs on the git remote. Read the `== section ==` output, then author the diagnosis yourself against the Decision Matrix below:

**Diagnosis:** <one-line read of what the sections above show> **Path:** <A/B/C/D/E/F, from the Decision Matrix>

Done when: both lines above are written and a single path letter is chosen.

`bd doctor` is intentionally NOT part of the battery — `--fix --yes` can mutate. Run it only after the diagnosis→path block above is emitted and a path is chosen (bd v1.1.0+ `bd doctor` also flags migration-content skew vs remote; surface that before any sync work).

Decision Matrix

Based on diagnostic results, follow the appropriate path. "Remote" below always means the configured beads remote (`bd dolt remote list`) — independent of the code repo's git origin; see "Multi-Repo / Private Beads Remote" below.

| State | Action | Path | |-------|--------|------| | No .beads/, no remote data | Fresh init | → Path A | | No .beads/, remote has dolt refs | Bootstrap from remote | → Path B | | .beads/ exists, `bd list` works, beads remote matches | Already good ✅ | Done | | .beads/ exists, `bd list` fails | Run `bd doctor --fix --yes` | → Path D | | .beads/ exists, `bd list` works, no beads remote configured | Add remote | → Path E | | .beads/ exists, push fails "no common ancestor" | Fix diverged history | → Path C | | .beads/ exists but empty/corrupt, remote has data | Export + re-bootstrap | → Path F |

Path A: Fresh Initialization (New Project)

# 1. Initialize beads
bd init

# 2. Verify
bd list                    # Should work (empty is fine)
bd create "Test bead" -t task -p 4
bd list                    # Should show the test bead
bd close <test-id> --reason "Init verification"

# 3. Add remote (if syncing) — RECOMMENDED: a dedicated beads remote (private for public projects),
#    separate from the code repo (ADR-0057; bd releases after v1.1.0 refuse a code-repo URL without --allow-git-origin)
bd dolt remote add origin git+ssh://git@github.com/<owner>/<repo>-beads.git

# 4. First push
bd dolt push

Done when: `bd list` shows the test bead created and closed, and (if a remote was added) `bd dolt push` succeeds.

Path B: Bootstrap from Remote (Cloned Repo)

# 1. Bootstrap (auto-detects remote dolt data)
bd bootstrap

# 2. Verify
bd list                    # Should show existing issues
bd vc status               # Should show branch + commit hash

# After any pull: repair denormalized blocked flags (bd v1.1.0+)
bd recompute-blocked

**If `bd bootstrap` fails:** open `references/recovery.md` (open when bootstrap auto-detect fails) for the manual 8-step fallback.

Path C: Fix Diverged History

Open `references/recovery.md` (open when push is rejected) for the v1.1.0 remote-migrate gate, the diverged-history fix, and the GitHub push-protection recovery.

Path D: Database Exists but Broken

# 1. Run doctor (non-destructive diagnostics + auto-fix)
bd doctor --fix --yes

# 2. If doctor fixes it:
bd list                    # Verify

# 3. If still broken, restart the Dolt server
bd dolt stop
bd dolt start
bd list                    # Retry

# 4. If still broken, check circuit breaker
rm -f /tmp/beads-dolt-circuit-*.json
bd dolt stop
bd dolt start
bd list                    # Retry

Path E: Add Remote to Existing Database

# 1. Add the remote — RECOMMENDED: a dedicated beads remote (private for public projects),
#    separate from the code repo (ADR-0057; bd releases after v1.1.0 refuse a code-repo URL without --allow-git-origin)
bd dolt remote add origin git+ssh://git@github.com/<owner>/<repo>-beads.git

# 2. Push to establish remote
bd dolt push

# 3. Verify
git ls-remote git+ssh://git@github.com/<owner>/<repo>-beads.git | grep dolt    # Should show refs/dolt/data

Path F: Corrupt Local, Remote Has Data

# 1. Export what we can