yf-beads-init

Verify, initialize, and repair a functioning beads (`bd`) configuration in a repository, and the shared dependency-verification home that other beads skills' preflights route to.

At a glance

• Category: beads
• Invocation: /yf-beads-init (user-invocable)
• Requires tools: bd, uv, git
• Depends on skills: yf-beads-extra
• Depended on by: yf-beads-hygiene
• Source: SKILL.md · README.md

When it fires

/yf-beads-init invoked; a repository is being set up for beads and `bd` is present but the repo's beads configuration is **non-existent, incorrect, or appears corrupted** (e.g. `bd status` errors, `bd doctor` reports errors, a wedged schema migration, or `bd ready`/`bd list` work while `bd status` does not); or another beads skill's preflight reports `system_deps_missing` / `bd_not_initialized` / a corrupted DB. SKIP when: bd is healthy (`yf preflight yf-beads-init --json` returns `ok`) and you only need routine issue operations (use the `beads` skill); for direct-CLI gotchas use `yf-beads-extra`.

Prerequisites

Mirrors SKILL.md frontmatter depends-on-tool: [bd, uv, git]. Depends on the beads-extra skill for direct-CLI semantics.

Usage

/beads-init

Or invoke the engine directly:

uv run scripts/beads_init.py verify --json-output   # read-only health check
uv run scripts/beads_init.py repair                 # dry-run: print the fix plan
uv run scripts/beads_init.py repair --apply         # apply standard repairs
uv run scripts/beads_init.py repair --apply --local-only   # also assert no Dolt remote

verify returns status ∈ {ok, deps_missing, not_initialized, corrupted} with diagnostics and remediations. repair fixes a wedged schema migration with a mode-aware flush before bd migrate schema → bd migrate — bd dolt stop in server mode, or a data-preserving raw-dolt working-set commit for embedded storage (no server to stop) — plus permissions, outdated hooks, gitignore drift, stale metadata, and the portable issues.jsonl export.

Companion rule

Ships protocols/BEADS_INIT.md (installed to the rules surface). It carries the always-loaded trigger contract — verify-before-use, the false-negative invariant, and repair-safety invariants — so the preflight check fires regardless of which beads skill is active. It also carries two general bd-usage mandates (use-bd-for-all-tracking; non-interactive shell-flag safety) folded in from the retired orphan rule.

Retirement of ~/.claude/rules/BEADS.md

protocols/BEADS_INIT.md consolidates the keep-worthy content of the legacy, unowned user-scoped rule ~/.claude/rules/BEADS.md (which no skill installed, upgraded, or carried across machines). CLI/issue-type detail routed to yf-beads-extra; the land-the-plane push is owned by yf-beads-upstream's UPSTREAM_TRACKING.md. After installing this skill (yf skills install), delete the orphan rule manually: rm -f ~/.claude/rules/BEADS.md. It is not a repo-tracked file, so retirement is a documented manual step, not a repo change.

Layout

skills/beads-init/
├── SKILL.md                  # verify/repair procedure, the corrections, preflight-home role
├── README.md                 # this file
├── scripts/
│   └── beads_init.py         # PEP 723 engine: verify / repair / status
└── protocols/
    ├── BEADS_INIT.md         # always-loaded trigger contract (installed to rules/)
    └── manifest.json         # rule hash/version manifest