From 7658c4a8e8d6cd68803f4ed42195d38f378e1100 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 19 Oct 2025 22:24:14 -0700 Subject: [PATCH] Add command documentation and improve daemon UX - Added human-readable uptime formatting (51m 59s vs 3119.4 seconds) - Fixed daemon stop race condition with SIGKILL - Added markdown docs for 19 commands: blocked, comments, compact, daemon, delete, dep, epic, export, import, label, list, quickstart, rename-prefix, renumber, reopen, repos, restore, stale, sync - Closed: bd-159, bd-152, bd-168 - Deleted test issues: bd-144, bd-145 Amp-Thread-ID: https://ampcode.com/threads/T-9f7c3fed-62de-4bcd-a059-8c1b77cdb841 Co-authored-by: Amp --- .beads/issues.jsonl | 7 +++---- cmd/bd/daemon.go | 33 +++++++++++++++++++++++++++++++-- commands/blocked.md | 15 +++++++++++++++ commands/comments.md | 28 ++++++++++++++++++++++++++++ commands/compact.md | 31 +++++++++++++++++++++++++++++++ commands/daemon.md | 35 +++++++++++++++++++++++++++++++++++ commands/delete.md | 32 ++++++++++++++++++++++++++++++++ commands/dep.md | 38 ++++++++++++++++++++++++++++++++++++++ commands/epic.md | 26 ++++++++++++++++++++++++++ commands/export.md | 24 ++++++++++++++++++++++++ commands/import.md | 36 ++++++++++++++++++++++++++++++++++++ commands/label.md | 33 +++++++++++++++++++++++++++++++++ commands/list.md | 30 ++++++++++++++++++++++++++++++ commands/quickstart.md | 17 +++++++++++++++++ commands/rename-prefix.md | 24 ++++++++++++++++++++++++ commands/renumber.md | 29 +++++++++++++++++++++++++++++ commands/reopen.md | 22 ++++++++++++++++++++++ commands/repos.md | 25 +++++++++++++++++++++++++ commands/restore.md | 28 ++++++++++++++++++++++++++++ commands/stale.md | 25 +++++++++++++++++++++++++ commands/sync.md | 28 ++++++++++++++++++++++++++++ 21 files changed, 560 insertions(+), 6 deletions(-) create mode 100644 commands/blocked.md create mode 100644 commands/comments.md create mode 100644 commands/compact.md create mode 100644 commands/daemon.md create mode 100644 commands/delete.md create mode 100644 commands/dep.md create mode 100644 commands/epic.md create mode 100644 commands/export.md create mode 100644 commands/import.md create mode 100644 commands/label.md create mode 100644 commands/list.md create mode 100644 commands/quickstart.md create mode 100644 commands/rename-prefix.md create mode 100644 commands/renumber.md create mode 100644 commands/reopen.md create mode 100644 commands/repos.md create mode 100644 commands/restore.md create mode 100644 commands/stale.md create mode 100644 commands/sync.md diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index a9b62902..21a9555d 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -48,8 +48,6 @@ {"id":"bd-141","title":"Add daemon RPC support for comments and label subcommands","description":"The 'bd comments' and 'bd label' subcommands don't work in direct mode because they don't inherit PersistentPreRun from root command. Need to add daemon RPC handlers similar to how show/update/create work.\n\nAffected commands:\n- bd comments \u003cid\u003e\n- bd comments add \u003cid\u003e \"text\"\n- bd label list \u003cid\u003e\n- bd label add \u003cid\u003e \u003clabel\u003e\n- bd label remove \u003cid\u003e \u003clabel\u003e\n\nSolution: Add RPC handlers in daemon.go for these operations and update the CLI commands to use daemon RPC when available (check daemonClient != nil pattern used in other commands).","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-19T16:08:42.16553-07:00","updated_at":"2025-10-19T21:14:12.233179-07:00","closed_at":"2025-10-19T21:14:12.233179-07:00"} {"id":"bd-142","title":"MCP server workspace routing broken - using wrong server for workspace","description":"When working in ~/src/beads, AI agent is calling mcp__beads-wyvern__* functions which are configured for ~/wyvern workspace. This causes MCP commands to fail or operate on wrong database.\n\nExpected: Should use correct MCP server based on current workspace\nActual: Using beads-wyvern MCP server when in beads repo\n\nNeed to investigate:\n- How MCP server routing/selection works\n- Why wrong server is being selected\n- How to fix workspace detection","notes":"Root cause: Using multiple MCP servers (beads-adar, beads-wyvern, beads-vc, beads) instead of single MCP server with global daemon. AI randomly selects wrong server for workspace.\n\nFixed:\n1. Started global daemon: bd daemon --global\n2. Simplified config to single MCP server in ~/.config/amp/settings.json\n3. Updated AGENTS.md to emphasize single MCP server as RECOMMENDED approach\n4. Marked legacy multiple-server approach with warning about workspace routing issues\n\nUser needs to restart Amp for config changes to take effect.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-19T18:32:04.513755-07:00","updated_at":"2025-10-19T20:52:23.598206-07:00","closed_at":"2025-10-19T18:35:00.167234-07:00"} {"id":"bd-143","title":"Renumber command fails with foreign key constraint error","description":"When running 'bd renumber --force' after deleting issues, the command fails with: 'failed to rename bd-73 to temp ID: failed to update issue ID: constraint failed: FOREIGN KEY constraint failed (787)'. This suggests the renumber implementation doesn't properly handle foreign key constraints during the ID swap process. May need to disable foreign keys temporarily or use a different renumbering strategy.","notes":"Deeper investigation: All child tables (dependencies, labels, events, dirty_issues, issue_snapshots, compaction_snapshots, comments) have FK constraints to issues(id) ON DELETE CASCADE. When renumbering tries to UPDATE issues SET id = temp-uuid WHERE id = bd-32, the FK checks fire immediately despite PRAGMA foreign_keys = OFF being called. Issue might be that Go sql.DB connection pooling means the PRAGMA isn't applied to the actual connection doing the UPDATE. Testing with explicit connection (s.db.Conn()) to ensure PRAGMA sticks.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-19T19:33:20.324768-07:00","updated_at":"2025-10-19T20:52:23.598384-07:00","closed_at":"2025-10-19T19:35:57.175627-07:00"} -{"id":"bd-144","title":"Concurrent test issue 2","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T19:51:16.598972-07:00","updated_at":"2025-10-19T20:52:23.598558-07:00"} -{"id":"bd-145","title":"Concurrent test issue 1","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T19:51:16.670081-07:00","updated_at":"2025-10-19T20:52:23.598726-07:00"} {"id":"bd-146","title":"Single-user issue","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:51:36.918878-07:00","updated_at":"2025-10-19T20:52:23.598889-07:00"} {"id":"bd-147","title":"Direct mode test","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:19.768858-07:00","updated_at":"2025-10-19T20:52:23.599056-07:00"} {"id":"bd-148","title":"Direct mode test2","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:25.87028-07:00","updated_at":"2025-10-19T20:52:23.599218-07:00"} @@ -57,14 +55,14 @@ {"id":"bd-15","title":"Implement full cross-type cycle prevention in AddDependency","description":"Expand cycle prevention in AddDependency to check for cycles across ALL dependency types, not just 'blocks'. Currently only 'blocks' type dependencies are checked for cycles, allowing cross-type circular dependencies to form (e.g., A blocks B, B parent-child A). This can cause semantic confusion and is a maintenance hazard for future operations that traverse dependencies.","design":"Implementation approach:\n1. Modify the cycle check in AddDependency (postgres.go:559-599)\n2. Remove the 'type = blocks' filter from the recursive CTE\n3. Check for cycles regardless of dependency type being added\n4. Return a clear error message indicating which types form the cycle\n\nTrade-offs to consider:\n- This is more mathematically correct (no cycles in dependency DAG)\n- May break legitimate use cases where cross-type cycles are intentional\n- Need to evaluate whether ANY cross-type cycles are valid in practice\n- Alternative: make this configurable with a --allow-cycle flag\n\nBefore implementing, should investigate:\n- Are there legitimate reasons for cross-type cycles?\n- What's the performance impact on large graphs (1000+ issues)?\n- Should certain type combinations be allowed to cycle?","acceptance_criteria":"- AddDependency prevents cycles across all dependency types, not just 'blocks'\n- Clear error message when cycle would be created, including dependency types\n- All existing tests pass\n- Performance benchmarked on large dependency graphs (100+ issues)\n- Decision documented on whether to add --allow-cycle flag or exception rules","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.599577-07:00","closed_at":"2025-10-16T20:31:19.174534-07:00"} {"id":"bd-150","title":"Direct mode test clean","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T19:52:56.4305-07:00","updated_at":"2025-10-19T20:52:23.600206-07:00"} {"id":"bd-151","title":"Multi-repo daemon routing fails in testing","description":"Test 4 from DAEMON_ARCHITECTURE.md showed daemon starts but doesn't route requests correctly to multi-repo databases. When running bd list in repo A after creating an issue, it shows 0 issues. Debug output shows 'daemon socket not ready after 5 seconds' despite daemon process running.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-19T20:01:18.977976-07:00","updated_at":"2025-10-19T20:52:23.600406-07:00","closed_at":"2025-10-19T20:07:40.203797-07:00"} -{"id":"bd-152","title":"Daemon stop has race condition with SIGKILL","description":"When stopping daemon, sometimes see 'Warning: daemon did not stop after 5 seconds, sending SIGKILL' followed by 'Error killing process: os: process already finished'. Indicates timing issue where process exits between check and kill.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-10-19T20:01:18.979589-07:00","updated_at":"2025-10-19T20:52:23.600571-07:00"} +{"id":"bd-152","title":"Daemon stop has race condition with SIGKILL","description":"When stopping daemon, sometimes see 'Warning: daemon did not stop after 5 seconds, sending SIGKILL' followed by 'Error killing process: os: process already finished'. Indicates timing issue where process exits between check and kill.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-19T20:01:18.979589-07:00","updated_at":"2025-10-19T21:49:35.916052-07:00","closed_at":"2025-10-19T21:49:35.916052-07:00"} {"id":"bd-153","title":"Implement storage cache eviction and memory limits","description":"Implement LRU cache eviction and memory pressure detection for daemon storage cache to prevent unbounded memory growth.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.761129-07:00","updated_at":"2025-10-19T20:52:23.600736-07:00","closed_at":"2025-10-19T20:14:24.888631-07:00"} {"id":"bd-154","title":"Clean up MCP integration for daemon reliability","description":"Ensure MCP server properly handles daemon lifecycle, connection failures, and recovery scenarios.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.764086-07:00","updated_at":"2025-10-19T20:52:23.600903-07:00","closed_at":"2025-10-19T20:15:11.006871-07:00"} {"id":"bd-155","title":"Add daemon health checks and monitoring","description":"Add health check endpoint that validates daemon state, storage connections, and resource usage.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.764154-07:00","updated_at":"2025-10-19T20:52:23.601114-07:00","closed_at":"2025-10-19T20:14:38.291678-07:00"} {"id":"bd-156","title":"Implement daemon crash recovery and restart","description":"Detect stale daemon processes, clean up orphaned resources, and auto-restart daemon after crashes.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-19T20:13:59.766856-07:00","updated_at":"2025-10-19T20:52:23.601346-07:00","closed_at":"2025-10-19T20:15:02.211576-07:00"} {"id":"bd-157","title":"Implement resource limits and connection pooling","description":"Add configurable limits for connections, file descriptors, and memory usage.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T20:13:59.768745-07:00","updated_at":"2025-10-19T20:52:23.601547-07:00"} {"id":"bd-158","title":"Add daemon telemetry and metrics","description":"Track and report daemon metrics: request count, latency, cache hits/misses, error rates.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-19T20:13:59.77094-07:00","updated_at":"2025-10-19T20:52:23.601784-07:00"} -{"id":"bd-159","title":"Improve daemon visibility and status reporting","description":"Add clear daemon status output, uptime reporting, and user-friendly error messages.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.772435-07:00","updated_at":"2025-10-19T20:52:23.602042-07:00"} +{"id":"bd-159","title":"Improve daemon visibility and status reporting","description":"Add clear daemon status output, uptime reporting, and user-friendly error messages.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.772435-07:00","updated_at":"2025-10-19T21:44:50.340047-07:00","closed_at":"2025-10-19T21:44:50.340047-07:00"} {"id":"bd-16","title":"Refactor duplicate flush logic in PersistentPostRun","description":"PersistentPostRun contains a complete copy of the flush logic instead of calling flushToJSONL(). This violates DRY principle and makes maintenance harder. Refactor to use flushToJSONL() with a force parameter to bypass isDirty check, or extract shared logic into a helper function. Located in cmd/bd/main.go:104-138.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.602241-07:00","closed_at":"2025-10-18T09:44:24.167574-07:00"} {"id":"bd-160","title":"Add daemon/client version compatibility checks","description":"Verify daemon and client versions are compatible before allowing connections.","status":"open","priority":1,"issue_type":"task","created_at":"2025-10-19T20:13:59.774304-07:00","updated_at":"2025-10-19T20:52:23.602618-07:00"} {"id":"bd-161","title":"Enhance label functionality and documentation","description":"Improve beads label system to support cross-cutting concerns and contextual metadata beyond structured fields (status, priority, type).\n\nCurrent state: Basic label storage exists (labels table, Add/GetLabels methods)\nTarget state: Full label lifecycle management with CLI, filtering, automation, and documentation\n\nCore principles:\n- Labels for cross-cutting concerns (technical metadata, scope, effort, quality gates)\n- Structured fields for workflow state (status, priority, type remain primary)\n- Multi-dimensional tagging without schema changes\n\nSee removed LABELS.md for detailed use cases and design rationale.","status":"open","priority":2,"issue_type":"epic","created_at":"2025-10-19T20:45:24.163728-07:00","updated_at":"2025-10-19T20:52:23.602796-07:00"} @@ -74,6 +72,7 @@ {"id":"bd-165","title":"Document label best practices and use cases","description":"Create documentation covering:\n- When to use labels vs structured fields\n- Common label sets (coding agents, open source, product dev, SRE)\n- Naming conventions (kebab-case, specificity, present tense)\n- Anti-patterns (too many labels, overlapping, personal labels)\n- Label lifecycle management\n\nContent from LABELS.md analysis document.","status":"open","priority":3,"issue_type":"task","created_at":"2025-10-19T20:45:36.867864-07:00","updated_at":"2025-10-19T20:52:23.603503-07:00"} {"id":"bd-166","title":"Implement label CLI commands (add, remove, list)","description":"Add CLI commands for label management:\n- bd label add \u003cissue\u003e \u003clabel...\u003e\n- bd label remove \u003cissue\u003e \u003clabel...\u003e\n- bd label list \u003cissue\u003e\n- bd labels (list all labels in use)\n\nBackend already has AddLabel/GetLabels/RemoveLabel methods in storage layer.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T20:49:44.344807-07:00","updated_at":"2025-10-19T21:14:12.231668-07:00","closed_at":"2025-10-19T21:14:12.231668-07:00"} {"id":"bd-167","title":"MCP server tools should accept workspace_root parameter","description":"","design":"After set_context is called, Amp appears to inject workspace_root as a parameter to subsequent tool calls. The beads-mcp server should accept this parameter (likely ignore it or map it to working_dir) to avoid errors.","notes":"Oracle review found two additional issues: 1) Missing workspace_root on where_am_i tool, 2) set_context should always set env vars even when DB not found (so init works right after). Both fixed.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-19T21:17:06.93365-07:00","updated_at":"2025-10-19T21:36:07.030443-07:00","closed_at":"2025-10-19T21:29:38.326609-07:00"} +{"id":"bd-168","title":"Update commands/ directory with new commands (comments, labels, etc)","description":"The commands/ directory contains documentation for bd commands, but several new commands have been added that aren't documented there yet: 'comments', 'labels', and possibly others. Need to audit what's missing and add documentation.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-19T21:54:04.65288-07:00","updated_at":"2025-10-19T21:57:28.943347-07:00","closed_at":"2025-10-19T21:57:28.943347-07:00"} {"id":"bd-17","title":"Test issue with explicit ID","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.603831-07:00","closed_at":"2025-10-16T10:07:34.124331-07:00"} {"id":"bd-18","title":"Critical bug","description":"","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.604005-07:00","closed_at":"2025-10-14T14:16:08.107546-07:00"} {"id":"bd-19","title":"Verify auto-export works","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-16T20:46:08.971822-07:00","updated_at":"2025-10-19T20:52:23.604167-07:00","closed_at":"2025-10-14T14:16:09.268591-07:00"} diff --git a/cmd/bd/daemon.go b/cmd/bd/daemon.go index 41d97417..cd7d68a3 100644 --- a/cmd/bd/daemon.go +++ b/cmd/bd/daemon.go @@ -268,6 +268,25 @@ func isDaemonRunning(pidFile string) (bool, int) { return true, pid } +func formatUptime(seconds float64) string { + if seconds < 60 { + return fmt.Sprintf("%.1f seconds", seconds) + } + if seconds < 3600 { + minutes := int(seconds / 60) + secs := int(seconds) % 60 + return fmt.Sprintf("%dm %ds", minutes, secs) + } + if seconds < 86400 { + hours := int(seconds / 3600) + minutes := int(seconds/60) % 60 + return fmt.Sprintf("%dh %dm", hours, minutes) + } + days := int(seconds / 86400) + hours := int(seconds/3600) % 24 + return fmt.Sprintf("%dd %dh", days, hours) +} + func showDaemonStatus(pidFile string, global bool) { if isRunning, pid := isDaemonRunning(pidFile); isRunning { scope := "local" @@ -342,7 +361,7 @@ func showDaemonHealth(global bool) { fmt.Printf("%s Daemon Health: %s\n", statusIcon, health.Status) fmt.Printf(" Version: %s\n", health.Version) - fmt.Printf(" Uptime: %.1f seconds\n", health.Uptime) + fmt.Printf(" Uptime: %s\n", formatUptime(health.Uptime)) fmt.Printf(" Cache Size: %d databases\n", health.CacheSize) fmt.Printf(" Cache Hits: %d\n", health.CacheHits) fmt.Printf(" Cache Misses: %d\n", health.CacheMisses) @@ -551,8 +570,18 @@ func stopDaemon(pidFile string) { } fmt.Fprintf(os.Stderr, "Warning: daemon did not stop after 5 seconds, sending SIGKILL\n") + + // Check one more time before SIGKILL to avoid race condition + if isRunning, _ := isDaemonRunning(pidFile); !isRunning { + fmt.Println("✓ Daemon stopped") + return + } + if err := process.Kill(); err != nil { - fmt.Fprintf(os.Stderr, "Error killing process: %v\n", err) + // Ignore "process already finished" errors + if !strings.Contains(err.Error(), "process already finished") { + fmt.Fprintf(os.Stderr, "Error killing process: %v\n", err) + } } os.Remove(pidFile) fmt.Println("✓ Daemon killed") diff --git a/commands/blocked.md b/commands/blocked.md new file mode 100644 index 00000000..0bd7e189 --- /dev/null +++ b/commands/blocked.md @@ -0,0 +1,15 @@ +--- +description: Show blocked issues +argument-hint: [] +--- + +Show all issues that are blocked by dependencies. + +Use `bd blocked` to see which issues have blockers preventing them from being worked on. This is the inverse of `bd ready` - it shows what's NOT ready. + +Blocked issues have one or more dependencies with type "blocks" that are still open. Once all blocking dependencies are closed, the issue becomes ready and will appear in `bd ready`. + +Useful for: +- Understanding why work is stuck +- Identifying critical path items +- Planning dependency resolution diff --git a/commands/comments.md b/commands/comments.md new file mode 100644 index 00000000..0cffe659 --- /dev/null +++ b/commands/comments.md @@ -0,0 +1,28 @@ +--- +description: View or manage comments on an issue +argument-hint: [issue-id] +--- + +View or add comments to a beads issue. + +## View Comments + +To view all comments on an issue: +- $1: Issue ID (e.g., bd-123) + +Use the beads CLI `bd comments ` to list all comments. Show them to the user with timestamps and authors. + +## Add Comment + +To add a comment: +- $1: "add" +- $2: Issue ID +- $3: Comment text (or use -f flag for file input) + +Use `bd comments add "comment text"` to add a comment. Confirm the comment was added successfully. + +Comments are useful for: +- Progress updates during work +- Design notes or technical decisions +- Links to related resources +- Questions or blockers diff --git a/commands/compact.md b/commands/compact.md new file mode 100644 index 00000000..29f6d3d4 --- /dev/null +++ b/commands/compact.md @@ -0,0 +1,31 @@ +--- +description: Compact old closed issues using semantic summarization +argument-hint: [--all] [--id issue-id] [--dry-run] +--- + +Reduce database size by summarizing closed issues no longer actively referenced. + +## Compaction Tiers + +- **Tier 1**: Semantic compression (30+ days closed, ~70% size reduction) +- **Tier 2**: Ultra compression (90+ days closed, ~95% size reduction) + +## Usage + +- **Preview candidates**: `bd compact --dry-run` +- **Compact all eligible**: `bd compact --all` +- **Compact specific issue**: `bd compact --id bd-42` +- **Force compact**: `bd compact --id bd-42 --force` (bypass age checks) +- **View statistics**: `bd compact --stats` + +## Options + +- **--tier**: Choose compaction tier (1 or 2, default: 1) +- **--workers**: Parallel workers (default: 5) +- **--batch-size**: Issues per batch (default: 10) + +## Important + +This is **permanent graceful decay** - original content is discarded. Use `bd restore ` to view full history from git if needed. + +Useful for long-running projects to keep database size manageable. diff --git a/commands/daemon.md b/commands/daemon.md new file mode 100644 index 00000000..ce3d7fdc --- /dev/null +++ b/commands/daemon.md @@ -0,0 +1,35 @@ +--- +description: Run background sync daemon +argument-hint: [--global] [--stop] [--status] [--health] +--- + +Run a background daemon that manages database connections and optionally syncs with git. + +## Daemon Modes + +- **Local daemon**: Socket at `.beads/bd.sock` (per-repository) +- **Global daemon**: Socket at `~/.beads/bd.sock` (all repositories) + +## Common Operations + +- **Start**: `bd daemon` or `bd daemon --global` +- **Stop**: `bd daemon --stop` or `bd daemon --global --stop` +- **Status**: `bd daemon --status` or `bd daemon --global --status` +- **Health**: `bd daemon --health` - shows uptime, cache stats, performance metrics +- **Metrics**: `bd daemon --metrics` - detailed operational telemetry + +## Sync Options + +- **--auto-commit**: Automatically commit JSONL changes +- **--auto-push**: Automatically push commits to remote +- **--interval**: Sync check interval (default: 5m) + +## Migration + +- **--migrate-to-global**: Migrate from local to global daemon + +The daemon provides: +- Connection pooling and caching +- Better performance for frequent operations +- Automatic JSONL sync +- Optional git sync diff --git a/commands/delete.md b/commands/delete.md new file mode 100644 index 00000000..217e3d87 --- /dev/null +++ b/commands/delete.md @@ -0,0 +1,32 @@ +--- +description: Delete issues and clean up references +argument-hint: [issue-ids...] [--force] +--- + +Delete one or more issues and clean up all references. + +## Safety Features + +- **Preview mode**: Default shows what would be deleted +- **--force**: Required to actually delete +- **--dry-run**: Preview collision detection +- **Dependency checks**: Fails if issue has dependents (unless --cascade or --force) + +## Batch Deletion + +- Delete multiple: `bd delete bd-1 bd-2 bd-3 --force` +- Delete from file: `bd delete --from-file deletions.txt --force` + +## Dependency Handling + +- **Default**: Fails if issue has dependents not in deletion set +- **--cascade**: Recursively delete all dependent issues +- **--force**: Delete and orphan dependents + +## What Gets Deleted + +1. All dependency links (any type, both directions) +2. Text references updated to "[deleted:ID]" in connected issues +3. Issue removed from database + +This operation cannot be undone. Use with caution! diff --git a/commands/dep.md b/commands/dep.md new file mode 100644 index 00000000..e4f27e3f --- /dev/null +++ b/commands/dep.md @@ -0,0 +1,38 @@ +--- +description: Manage dependencies between issues +argument-hint: [command] [from-id] [to-id] +--- + +Manage dependencies between beads issues. + +## Available Commands + +- **add**: Add a dependency between issues + - $1: "add" + - $2: From issue ID + - $3: To issue ID + - $4: Dependency type (blocks, related, parent-child, discovered-from) + +- **remove**: Remove a dependency + - $1: "remove" + - $2: From issue ID + - $3: To issue ID + +- **tree**: Show dependency tree for an issue + - $1: "tree" + - $2: Issue ID + +- **cycles**: Detect dependency cycles + +## Dependency Types + +- **blocks**: Hard blocker (from blocks to) - affects ready queue +- **related**: Soft relationship - for context only +- **parent-child**: Epic/subtask relationship +- **discovered-from**: Track issues found during work + +## Examples + +- `bd dep add bd-10 bd-20 --type blocks`: bd-10 blocks bd-20 +- `bd dep tree bd-20`: Show what blocks bd-20 and what bd-20 blocks +- `bd dep cycles`: Check for circular dependencies diff --git a/commands/epic.md b/commands/epic.md new file mode 100644 index 00000000..d9e825c7 --- /dev/null +++ b/commands/epic.md @@ -0,0 +1,26 @@ +--- +description: Epic management commands +argument-hint: [command] +--- + +Manage epics (large features composed of multiple issues). + +## Available Commands + +- **status**: Show epic completion status + - Shows progress for each epic + - Lists child issues and their states + - Calculates completion percentage + +- **close-eligible**: Close epics where all children are complete + - Automatically closes epics when all child issues are done + - Useful for bulk epic cleanup + +## Epic Workflow + +1. Create epic: `bd create "Large Feature" -t epic -p 1` +2. Link subtasks: `bd dep add bd-10 bd-20 --type parent-child` (epic bd-10 is parent of task bd-20) +3. Track progress: `bd epic status` +4. Auto-close when done: `bd epic close-eligible` + +Epics use parent-child dependencies to track subtasks. diff --git a/commands/export.md b/commands/export.md new file mode 100644 index 00000000..e0bbbd31 --- /dev/null +++ b/commands/export.md @@ -0,0 +1,24 @@ +--- +description: Export issues to JSONL format +argument-hint: [-o output-file] +--- + +Export all issues to JSON Lines format (one JSON object per line). + +## Usage + +- **To stdout**: `bd export` +- **To file**: `bd export -o issues.jsonl` +- **Filter by status**: `bd export --status open` + +Issues are sorted by ID for consistent diffs, making git diffs readable. + +## Automatic Export + +The daemon automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export. + +Export is used for: +- Git version control +- Backup +- Sharing issues between repositories +- Data migration diff --git a/commands/import.md b/commands/import.md new file mode 100644 index 00000000..6d154d89 --- /dev/null +++ b/commands/import.md @@ -0,0 +1,36 @@ +--- +description: Import issues from JSONL format +argument-hint: [-i input-file] +--- + +Import issues from JSON Lines format (one JSON object per line). + +## Usage + +- **From stdin**: `bd import` (reads from stdin) +- **From file**: `bd import -i issues.jsonl` +- **Preview**: `bd import -i issues.jsonl --dry-run` +- **Resolve collisions**: `bd import -i issues.jsonl --resolve-collisions` + +## Behavior + +- **Existing issues** (same ID): Updated with new data +- **New issues**: Created +- **Collisions** (same ID, different content): Detected and reported + +## Collision Handling + +When merging branches or pulling changes, ID collisions can occur: + +- **--dry-run**: Preview collisions without making changes +- **--resolve-collisions**: Automatically remap colliding issues to new IDs +- All text references and dependencies are automatically updated + +## Automatic Import + +The daemon automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed. + +## Options + +- **--skip-existing**: Skip updates to existing issues +- **--strict**: Fail on dependency errors instead of warnings diff --git a/commands/label.md b/commands/label.md new file mode 100644 index 00000000..d916d44b --- /dev/null +++ b/commands/label.md @@ -0,0 +1,33 @@ +--- +description: Manage issue labels +argument-hint: [command] [issue-id] [label] +--- + +Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type). + +## Available Commands + +- **add**: Add a label to an issue + - $1: "add" + - $2: Issue ID + - $3: Label name + +- **remove**: Remove a label from an issue + - $1: "remove" + - $2: Issue ID + - $3: Label name + +- **list**: List labels on a specific issue + - $1: "list" + - $2: Issue ID + +- **list-all**: Show all labels used across all issues + +## Common Label Use Cases + +- Technical scope: `backend`, `frontend`, `api`, `database` +- Quality gates: `needs-review`, `needs-tests`, `security-review` +- Effort sizing: `quick-win`, `complex`, `spike` +- Context: `technical-debt`, `documentation`, `performance` + +Use `bd label add