* feat(schema): never migrate an existing database without explicit consent (bd-qhn8y) Beads 1.2 release remediation. 1.2.0/1.2.1 auto-applied migrations 54-65 at store open on ANY command, including reads; older binaries then refuse the migrated database. MigrateUp now refuses pending main-sequence migrations on an existing database before any write (dolt_ignore seeding included) unless the operator consented: bd migrate / bd migrate schema (preview flags withhold), bd migrate --force, or BD_ALLOW_MIGRATE=1 (BD_ALLOW_REMOTE_MIGRATE honored as an alias). Fresh init and at-latest databases are unaffected; the #4259 remote gate keeps all its protections. Also: freeze shipped migrations (hash-pin test, main 0001-0065 + ignored 0001-0024), retract v1.2.0/v1.2.1 in go.mod, agent-executable un-migrate runbook (docs/recovery/unmigrate-schema-v65.md), and the upgrade smoke + historical migration harnesses now model the consent contract and assert the refusal carries guidance. No version bump here by design: cutting the release stays with the release owner. Rebased onto main800d43eb8d: the go.mod retract hunk is dropped - main already retracts v1.2.0/v1.2.1 (and v1.1.1) since #5782. The uow consent grant moves into the TestMain main added in #6441 (a second TestMain no longer compiles), and the new files are listed in the BUILD.bazel targets main now carries (gazelle). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(schema): cloned-workspace bootstrap carries creation-consent (bd-qhn8y) The consent gate treated a workspace `bd init --remote` / `bd bootstrap` just cloned into existence like a pre-existing database, refusing the smart gate's provably-safe first-mover migration and stranding init in the generic open-error path (bypassing the bd-4mpy7 finalize+guidance ergonomics). Cloning IS creating: those paths now record consent explicitly, and the #4259 remote-migrate gate still applies to them unchanged (consent is not its designated-migrator override). Fixes CI TestEmbeddedInit/remote_behind_schema_gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(migration): consent first in main's wisp lanes too (bd-qhn8y) The rebase onto800d43eb8dbrought in #6049's wisp-plane lanes, which postdate this PR's harness changes. Each one makes an ordinary candidate command the first touch on an old-schema database, and the consent gate refuses it: - historical-dolt-upgrade-test.sh run_wisp_plane_upgrade opens with `bd list` before any migrate: "candidate could not open the seeded wisp workspace" for v1.0.1, v1.1.0, v1.1.2 and v1.2.2 (the Migration Test Harness dolt-runtime shard). - run_dirty_tracked_wisp_scenario (v1.1.2): the consent refusal stops the open before MigrateUp reaches the #5816 dirty tables, so the lane fails "without naming them". - upgrade-smoke-test.sh "Wisp plane survives upgrade" upgrades with a bare cand_init, so list/ready/blocked/update all hit the refusal (4 failures each for v1.3.0 and v1.3.1, both in the PR smoke set). Use the PR's own pattern: the explicit `bd migrate schema` is the first candidate touch (cand_upgrade in the smoke script). Base800d43eb8dpasses these lanes unchanged; with this fixup the full 14-version historical corpus and all five PR smoke versions pass. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(schema): close consent-gate review findings (bd-qhn8y) Review fixes for the migration-consent gate (adopt-pr review, attempts 1 and 2). Majors: - #4566 deadlock rebuilt one check earlier: on a database that is both behind and dirty, the consent refusal fired before the dirty-table guard, whose remedy (`bd dolt commit`) opens without consent. The working-set-reconcile opens now tolerate MigrateConsentError: embedded (toleratesConsentRefusal, WSR intent only) and server mode (LenientOpen's warnLenientOpenRefusal) print WorkingSetWarning and commit at the current schema; strict, read-only and RemoteSync opens still refuse. Covered by an embedded test (a refused open writes nothing: dolt_status, dolt_ignore and schema_migrations unchanged) and a server-mode integration subtest. - Bare `bd migrate` consented: isMigrateConsentCommand now matches only the schema verb, so `bd migrate` (metadata reconcile, including --update-repo-id, --inspect and --dry-run) no longer consents to a one-way migration; `bd migrate schema` and --force do. TestLocalMigrateConsentScope pins the scope through the root pre-run. The dirty-table warnings name `bd migrate schema` accordingly. - Runnable JSON hint: the JSON refusal follows the #4259 AgentDirective convention, a non-runnable hint plus a migrate_consent object (versions, pending, severity, human_decision_required, options) whose commands are retargeted with --global for the shared global database. The text refusal prints the same --global hint under `bd --global`. - Freeze floor: the hash-pinned freeze now covers what v1.3.x shipped, main 0001-0066 and ignored 0001-0026; the CHANGELOG puts new migrations in 0070+ / 0028+. - Fresh-bootstrap heal: MigrateUpWithLock with heal authority takes the consent-free migrate path, so a retried bd init whose first pass left a non-zero cursor converges; other lock callers keep the gate. Minors: the uow team-server guards are repinned on `bd migrate schema`; the un-migrate runbook is linked from the recovery index and cross-linked with the 1.2.1 repair-forward doc; the CHANGELOG BREAKING entry matches the shipped contract; harness comment grammar. Docs: the user docs and README named bare `bd migrate` as the step that applies schema migrations; they now say `bd migrate schema`, which also exists in the pinned docs release (v1.2.2) and in v1.3.x. The `bd migrate schema` help no longer claims migrations run automatically on store open. The Go remedy that sends a remote-gate stop to bare `bd migrate` for its migrate-or-adopt options is unchanged (pinned by TestNoticeSharedMigrateRefusalPerDecision). Upgrade smoke (attempt 2): the consent-gate assertion is graded only when the old binary left a database. Releases before v1.0 have no `init --non-interactive`, so prev_init creates nothing there and the candidate's `bd list` fails with "no beads database found", which has no consent guidance. Main's Bazel smoke lane (#7331) runs the newest 30 releases, 20 of them pre-1.0, under the required ci-gate; all 20 went red on the merge. The 10 v1.x releases still take the refusal branch. Shard manifest (pre-approval CI): the new embedded test TestEmbeddedMigrateConsent_BehindAndDirtyWorkingSetReconcileRecovers is listed in the Bazel 15-shard block of embedded-storage-test-shards.txt (incremental --write; shard 15). Main's ci lane runs TestStorageEmbeddedShardManifestGeneratorNotStale in //scripts:scripts_test, which fails on any unlisted top-level embeddeddolt test. Not addressed (optional): env-only consent docs for embedders, the unparseable BD_ALLOW_REMOTE_MIGRATE alias hint, and the harness `|| true` on `cand migrate schema`. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com> Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
373 lines
10 KiB
Markdown
373 lines
10 KiB
Markdown
---
|
|
title: Quick Start
|
|
description: Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes
|
|
---
|
|
|
|
Get up and running with Beads in a few minutes.
|
|
|
|
## Why Beads?
|
|
|
|
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
|
|
|
|
Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:
|
|
|
|
**Flat tracker (GitHub Issues):**
|
|
```
|
|
Open issues: Set up database, Create API, Add authentication
|
|
→ An agent picks "Add authentication" and gets stuck immediately
|
|
```
|
|
|
|
**Beads:**
|
|
```bash
|
|
$ bd ready
|
|
1. [P1] [task] bd-1: Set up database
|
|
|
|
$ bd ready --explain --json | jq '.blocked[0]'
|
|
{
|
|
"id": "bd-3",
|
|
"title": "Add authentication",
|
|
"blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
|
|
}
|
|
```
|
|
|
|
The agent picks the right task every time. No wasted cycles.
|
|
|
|
## Installation
|
|
|
|
Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).
|
|
|
|
**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.
|
|
|
|
```bash
|
|
bd --help
|
|
```
|
|
|
|
## Initialize
|
|
|
|
First time in a repository:
|
|
|
|
```bash
|
|
# Basic setup (prompts for contributor mode)
|
|
bd init
|
|
|
|
# For AI agents (non-interactive)
|
|
bd init --quiet
|
|
|
|
# OSS contributor (fork workflow with separate planning repo)
|
|
bd init --contributor
|
|
|
|
# Team member (branch workflow for collaboration)
|
|
bd init --team
|
|
|
|
# Protected main branch (GitHub/GitLab)
|
|
# Note: Dolt stores data under refs/dolt/data, separate from
|
|
# Git refs, so no --branch flag is needed.
|
|
```
|
|
|
|
The wizard will:
|
|
- Create `.beads/` directory and embedded Dolt database
|
|
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
|
|
- Import existing issues from git (if any)
|
|
- Install git hooks (skip with `--skip-hooks`)
|
|
|
|
Notes:
|
|
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
|
|
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
|
|
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
|
|
- To import issues from an older installation, run `bd init --from-jsonl`.
|
|
|
|
### Role configuration
|
|
|
|
During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"
|
|
|
|
- Answer **Y** if you're contributing to a fork (runs contributor wizard)
|
|
- Answer **N** if you're the maintainer or have push access
|
|
|
|
This sets `git config beads.role` which determines how beads routes issues:
|
|
|
|
| Role | Use case | Issue storage |
|
|
|------|----------|---------------|
|
|
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
|
|
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
|
|
|
|
You can also configure manually:
|
|
|
|
```bash
|
|
# Set as contributor
|
|
git config beads.role contributor
|
|
|
|
# Set as maintainer
|
|
git config beads.role maintainer
|
|
|
|
# Check current role
|
|
git config --get beads.role
|
|
```
|
|
|
|
**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.
|
|
|
|
## Your first issues
|
|
|
|
```bash
|
|
# Create a few issues
|
|
bd create "Set up database" -p 1 -t task
|
|
bd create "Create API" -p 2 -t feature
|
|
bd create "Add authentication" -p 2 -t feature
|
|
|
|
# List them
|
|
bd list
|
|
```
|
|
|
|
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
|
|
|
|
## Hierarchical issues (epics)
|
|
|
|
For large features, use hierarchical IDs to organize work:
|
|
|
|
```bash
|
|
# Create epic (generates parent hash ID)
|
|
bd create "Auth System" -t epic -p 1
|
|
# Returns: bd-a3f8e9
|
|
|
|
# Create child tasks (use --parent to attach to the epic)
|
|
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
|
|
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
|
|
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
|
|
|
|
# View hierarchy
|
|
bd dep tree bd-a3f8e9
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Dependency tree for bd-a3f8e9:
|
|
|
|
> bd-a3f8e9: Auth System [epic] [P1] (open)
|
|
> bd-a3f8e9.1: Design login UI [P1] (open)
|
|
> bd-a3f8e9.2: Backend validation [P1] (open)
|
|
> bd-a3f8e9.3: Integration tests [P1] (open)
|
|
```
|
|
|
|
Children inherit the epic's labels by default — if the epic carries a size/effort label, see [Labels](/core-concepts/labels) for how to keep it off the children.
|
|
|
|
## Add dependencies
|
|
|
|
```bash
|
|
# API depends on database
|
|
bd dep add bd-2 bd-1
|
|
|
|
# Auth depends on API
|
|
bd dep add bd-3 bd-2
|
|
|
|
# View the tree
|
|
bd dep tree bd-3
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Dependency tree for bd-3:
|
|
|
|
> bd-3: Add authentication [P2] (open)
|
|
> bd-2: Create API [P2] (open)
|
|
> bd-1: Set up database [P1] (open)
|
|
```
|
|
|
|
**Dependency visibility:** `bd list` shows blocking dependencies inline:
|
|
```
|
|
○ bd-a1b2 [P1] [task] - Set up database
|
|
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
|
|
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
|
|
```
|
|
|
|
## Find ready work
|
|
|
|
```bash
|
|
bd ready
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Ready work (1 issues with no active blockers):
|
|
|
|
1. [P1] bd-1: Set up database
|
|
```
|
|
|
|
Only bd-1 is ready because bd-2 and bd-3 are blocked.
|
|
|
|
**Understanding why:** Use `--explain` to see the full graph reasoning:
|
|
|
|
```bash
|
|
bd ready --explain
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Ready Work Explanation
|
|
|
|
● Ready (1 issues):
|
|
|
|
bd-1 [P1] Set up database
|
|
Reason: no blocking dependencies
|
|
Unblocks: 1 issue(s)
|
|
|
|
● Blocked (2 issues):
|
|
|
|
bd-2 [P2] Create API
|
|
← blocked by bd-1: Set up database [open]
|
|
|
|
bd-3 [P2] Add authentication
|
|
← blocked by bd-2: Create API [open]
|
|
|
|
─ Summary: 1 ready, 2 blocked
|
|
```
|
|
|
|
**Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work.
|
|
|
|
## Work the queue
|
|
|
|
```bash
|
|
# Start working on bd-1
|
|
bd update bd-1 --claim
|
|
|
|
# Complete it
|
|
bd close bd-1 --reason "Database setup complete"
|
|
|
|
# Check ready work again
|
|
bd ready
|
|
```
|
|
|
|
Now bd-2 is ready.
|
|
|
|
## Track progress
|
|
|
|
```bash
|
|
# See blocked issues
|
|
bd blocked
|
|
|
|
# View statistics
|
|
bd stats
|
|
```
|
|
|
|
## Team sync
|
|
|
|
Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs. In repos with `origin`, `bd init` configures that Dolt remote automatically.
|
|
|
|
```bash
|
|
# Verify the remote, or add one if the repo had no origin during init
|
|
bd dolt remote list
|
|
bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed
|
|
|
|
# Push your issues
|
|
bd dolt push
|
|
|
|
# Pull teammates' changes
|
|
bd dolt pull
|
|
```
|
|
|
|
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`.
|
|
|
|
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration, see [Dolt architecture](/architecture/dolt); for federation, see [federation](/multi-agent/federation).
|
|
|
|
## Optional: Notion sync
|
|
|
|
If you keep project issues in Notion, supply an integration token first:
|
|
|
|
```bash
|
|
export NOTION_TOKEN=<your-token>
|
|
# or, if .beads/config.yaml is not tracked by git:
|
|
bd config set notion.token <your-token>
|
|
```
|
|
|
|
`bd config set` never writes the token to the Dolt database, so `bd dolt push` does not send it to a remote. It writes the token to `.beads/config.yaml` instead, and refuses when that file is tracked by git, as it is after `bd init` in a git repository.
|
|
|
|
Then either create a new Beads database under a parent page or connect to an existing target:
|
|
|
|
```bash
|
|
bd notion init --parent <page-id>
|
|
# or
|
|
bd notion connect --url <notion-database-or-data-source-url>
|
|
```
|
|
|
|
Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
|
|
|
|
Check which auth source is active and whether the target schema is ready:
|
|
|
|
```bash
|
|
bd notion status
|
|
bd notion status --json
|
|
```
|
|
|
|
Preview or run sync:
|
|
|
|
```bash
|
|
bd notion sync --dry-run
|
|
bd notion sync
|
|
bd notion sync --pull
|
|
bd notion sync --push
|
|
```
|
|
|
|
## Database location
|
|
|
|
By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
|
|
In server mode, data is managed by the external `dolt sql-server`.
|
|
|
|
## Migrating databases
|
|
|
|
After upgrading bd, check for pending database migrations and apply them:
|
|
|
|
```bash
|
|
# Inspect migration plan (AI agents)
|
|
bd migrate --inspect --json
|
|
|
|
# Check schema and config
|
|
bd info --schema --json
|
|
|
|
# Preview migration changes
|
|
bd migrate --dry-run
|
|
|
|
# Apply pending schema migrations
|
|
bd migrate schema
|
|
|
|
# Migrate and clean up old files
|
|
bd migrate --yes
|
|
```
|
|
|
|
**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
|
|
|
|
## Database maintenance
|
|
|
|
As your project accumulates closed issues, the database grows. Manage size with these commands:
|
|
|
|
```bash
|
|
# View compaction statistics
|
|
bd admin compact --stats
|
|
|
|
# Preview compaction candidates (30+ days closed)
|
|
bd admin compact --analyze --json
|
|
|
|
# Apply agent-generated summary
|
|
bd admin compact --apply --id bd-42 --summary summary.txt
|
|
|
|
# Immediately delete closed issues (CAUTION: permanent!)
|
|
bd admin cleanup --force
|
|
```
|
|
|
|
**When to compact:**
|
|
- Database file > 10MB with many old closed issues
|
|
- After major project milestones when old issues are no longer relevant
|
|
- Before archiving a project phase
|
|
|
|
**Note:** Compaction is permanent graceful decay. Original content is discarded but recoverable via `bd restore <id>` (from the pre-compaction snapshot, with Dolt history as fallback).
|
|
|
|
## Next steps
|
|
|
|
- Add labels: `bd create "Task" -l "backend,urgent"`
|
|
- Filter ready work: `bd ready --priority 1`
|
|
- Explain the graph: `bd ready --explain`
|
|
- Check graph integrity: `bd graph check`
|
|
- Search issues: `bd list --status open`
|
|
- Detect cycles: `bd dep cycles`
|
|
- Gates for PR/CI sync: [`bd gate`](/cli-reference/gate)
|
|
- More sync scenarios: [`bd dolt`](/cli-reference/dolt)
|
|
- Full command list: [CLI Reference](/cli-reference/index)
|
|
|
|
See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.
|