diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index db02b834..ca91ee38 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,4 @@ {"id":"bd-03r","title":"Document deletions manifest in AGENTS.md and README","description":"Parent: bd-imj\n\n## Task\nAdd documentation about the deletions manifest feature.\n\n## Locations to Update\n\n### AGENTS.md\n- Explain that deletions.jsonl is tracked in git\n- Document that `bd delete` records to the manifest\n- Explain cross-clone propagation mechanism\n\n### README.md \n- Brief mention in .beads directory structure section\n- Link to detailed docs if needed\n\n### docs/deletions.md (new file)\n- Full technical documentation\n- Format specification\n- Pruning policy\n- Git history fallback\n- Troubleshooting\n\n## Acceptance Criteria\n- AGENTS.md updated with deletion workflow\n- README.md mentions deletions.jsonl purpose\n- New docs/deletions.md with complete reference","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T14:56:49.13027-08:00","updated_at":"2025-11-25T15:17:23.145944-08:00","closed_at":"2025-11-25T15:17:23.145944-08:00"} -{"id":"bd-055","title":"Fix hyphenated prefix parsing in ExtractIssuePrefix (GH #395)","description":"","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T15:22:22.395177-08:00","updated_at":"2025-11-26T16:46:57.8927-08:00","closed_at":"2025-11-26T16:46:57.8927-08:00"} {"id":"bd-0b2","title":"Need --no-git-history flag to disable git history backfill during import","description":"During JSONL migration (beads.jsonl → issues.jsonl), the git history backfill mechanism causes data loss by finding issues in the old beads.jsonl git history and incorrectly treating them as deleted.\n\nA --no-git-history flag for 'bd import' and 'bd sync' would allow users to disable the git history fallback when it's causing problems.\n\nUse cases:\n- JSONL filename migrations\n- Repos with complex git history\n- Debugging import issues\n- Performance (skip slow git scans)\n\nRelated: bd-0gh (migration causes spurious deletions)","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-26T22:28:22.5286-08:00","updated_at":"2025-11-26T23:14:22.957335-08:00","closed_at":"2025-11-26T23:14:22.957335-08:00"} {"id":"bd-1pj6","title":"Proposal: Custom status states via config","description":"Proposal to add 'custom status states' via `bd config`.\nUsers could define an optional issue status enum (e.g., awaiting_review, review_in_progress) in the config.\nThis would enable multi-step pipelines to process issues where each step correlates to a specific status.\n\nExamples:\n- awaiting_verification\n- awaiting_docs\n- awaiting_testing\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-20T18:55:48.670499-05:00","updated_at":"2025-11-20T18:55:48.670499-05:00"} {"id":"bd-2em","title":"Expand checkHooksQuick to verify all hook versions","description":"Currently checkHooksQuick only checks post-merge hook version. Should also check pre-commit, pre-push, and post-checkout for completeness. Keep it lightweight but catch more outdated hooks.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:47.432243-08:00","updated_at":"2025-11-25T19:50:21.378464-08:00","closed_at":"2025-11-25T19:50:21.378464-08:00"} @@ -11,7 +10,6 @@ {"id":"bd-4l5","title":"bd prime: Detect ephemeral branches and adjust workflow output","description":"When 'bd prime' runs on a branch with no upstream (ephemeral branch), it should output a different SESSION CLOSE PROTOCOL.\n\n**Current output (wrong for ephemeral branches):**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync\n[ ] 4. git commit -m \"...\"\n[ ] 5. bd sync\n[ ] 6. git push\n```\n\n**Needed output for ephemeral branches:**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync --from-main (pull updates from main)\n[ ] 4. git commit -m \"...\"\n[ ] 5. (no push - branch is ephemeral)\n```\n\n**Detection:** `git rev-parse --abbrev-ref --symbolic-full-name @{u}` returns error code 128 if no upstream.\n\nAlso update Sync \u0026 Collaboration section to mention `bd sync --from-main` for ephemeral branches.\n\n**Use case:** Gastown polecats work on ephemeral local branches that are never pushed. Their code gets merged to main via local merge, and beads changes stay local (communicated via gm mail to Overseer).","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-11-25T16:55:24.984104-08:00","updated_at":"2025-11-25T17:12:46.604978-08:00","closed_at":"2025-11-25T17:12:46.604978-08:00"} {"id":"bd-4pv","title":"bd export only outputs 1 issue after auto-import corrupts database","description":"When auto-import runs and purges issues (due to git history backfill bug), subsequent 'bd export' only exports 1 issue even though the database should have many.\n\nReproduction:\n1. Have issues.jsonl with 55 issues\n2. Auto-import triggers and purges all issues via git history backfill\n3. Run 'bd export' - only exports 1 issue (the last one created before corruption)\n\nThe database gets into an inconsistent state where most issues are purged but export doesn't realize this.\n\nWorkaround: Rebuild database from scratch with 'rm .beads/beads.db \u0026\u0026 bd init --prefix bd'","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:40.828866-08:00","updated_at":"2025-11-26T22:28:40.828866-08:00"} {"id":"bd-4t7","title":"Auto-import runs during --no-auto-import operations via stats/ready commands","description":"Even when using --no-auto-import flag, certain commands like 'bd stats' and 'bd ready' still trigger auto-import internally, which can cause the git history backfill bug to corrupt data.\n\nExample:\n bd stats --no-auto-import\n # Still prints 'Purged bd-xxx (recovered from git history...)'\n\nThe flag should completely disable auto-import for the command, but it appears some code paths still trigger it.\n\nWorkaround: Use --allow-stale instead, or --sandbox mode.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:59.305898-08:00","updated_at":"2025-11-26T22:28:59.305898-08:00"} -{"id":"bd-6xd","title":"Standardize on issues.jsonl as canonical filename","description":"## Background\n\nThe codebase has confused and contradictory references to both `issues.jsonl` and `beads.jsonl`. This arose from a misconception that `issues.jsonl` was polluted with 100k test issues, but analysis shows:\n\n- issues.jsonl git history: 253 blobs, 54 MB total (max blob 2.1 MB)\n- beads.jsonl git history: 1140 blobs, 353 MB total (6.5x larger!)\n\nThe 'pollution' was never as big as remembered. Meanwhile, 99% of user installs use `issues.jsonl`.\n\n## The Problem\n\nCode has contradictory comments:\n```go\n// cmd/bd/autoimport.go:88\n// Try canonical JSONL filenames in precedence order (issues.jsonl is canonical)\n\n// internal/configfile/configfile.go:24\nJSONLExport: \"beads.jsonl\", // Default to canonical name (was issues.jsonl)\n```\n\n## Current State\n\n### Code References (excluding tests)\n- `beads.jsonl`: 51 references in Go code\n- `issues.jsonl`: 84 references in Go code\n\n### Documentation References\n- `beads.jsonl`: 59 references\n- `issues.jsonl`: 62 references\n\n## Proposed Solution\n\n1. Make `issues.jsonl` the **only** canonical name\n2. Support `beads.jsonl` only as legacy (auto-migrate to issues.jsonl)\n3. Switch beads repo itself back to using issues.jsonl\n4. Update all code and docs for consistency\n\n## Files Requiring Changes\n\n### High Priority (logic changes)\n- `internal/configfile/configfile.go` - Change default from beads.jsonl to issues.jsonl\n- `internal/beads/beads.go` - Reverse preference order, prefer issues.jsonl\n- `cmd/bd/version_tracking.go` - Reverse preference order\n- `cmd/bd/doctor/fix/database_config.go` - Reverse preference order\n- `cmd/bd/autoimport.go` - Already prefers issues.jsonl (correct)\n- `cmd/bd/init.go` - Update gitattributes setup, comments\n\n### Medium Priority (user-facing messages)\n- `cmd/bd/import.go` - Update example paths in error messages\n- `cmd/bd/sync.go` - Update diff display path\n- `cmd/bd/status.go` - Update git log path\n- `cmd/bd/staleness.go` - Update help message\n- `cmd/bd/init_contributor.go` - Update output messages\n- `cmd/bd/clean.go` - Update help text\n- `cmd/bd/cleanup.go` - Update help text\n\n### Lower Priority (internal/comments)\n- `internal/importer/importer.go` - Update comments and paths\n- `cmd/bd/merge.go` - Update comment\n- `cmd/bd/doctor.go` - Multiple references\n- `cmd/bd/doctor/fix/sync.go` - Variable naming\n- `cmd/bd/doctor/fix/deletions.go` - Path reference\n\n### Documentation\n- README.md - ~8 references to update\n- docs/DELETIONS.md\n- docs/CLI_REFERENCE.md\n- docs/ARCHITECTURE.md\n- docs/TROUBLESHOOTING.md\n- docs/PROTECTED_BRANCHES.md\n- docs/GIT_INTEGRATION.md\n- docs/MULTI_REPO_AGENTS.md\n- docs/MULTI_REPO_MIGRATION.md\n- docs/TESTING.md (acknowledges the inconsistency)\n\n## Migration Strategy\n\n1. Add migration in `bd init`: if beads.jsonl exists and issues.jsonl doesn't, rename it\n2. Update `bd doctor` to detect and offer to fix the naming\n3. Keep reading beads.jsonl as fallback for one version cycle\n4. Remove beads.jsonl fallback in future version\n\n## For Beads Repo Itself\n\n1. `git mv .beads/beads.jsonl .beads/issues.jsonl`\n2. Update .gitattributes if present\n3. Commit with clear message","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-26T19:33:34.169595-08:00","updated_at":"2025-11-26T21:00:34.038454-08:00","closed_at":"2025-11-26T21:00:34.038454-08:00"} {"id":"bd-736d","title":"Refactor path canonicalization into helper function","description":"The path canonicalization logic (filepath.Abs + EvalSymlinks) is duplicated in 3 places:\n- beads.go:131-137 (BEADS_DIR handling)\n- cmd/bd/main.go:446-451 (--no-db cleanup)\n- cmd/bd/nodb.go:26-31 (--no-db initialization)\n\nRefactoring suggestion:\nExtract to a helper function like:\n func canonicalizePath(path string) string\n\nThis would:\n- Reduce code duplication\n- Make the logic easier to maintain\n- Ensure consistent behavior across all path handling\n\nRelated to bd-e16b implementation.","status":"closed","priority":3,"issue_type":"chore","created_at":"2025-11-02T18:33:47.727443-08:00","updated_at":"2025-11-25T22:27:33.738672-08:00","closed_at":"2025-11-25T22:27:33.738672-08:00"} {"id":"bd-81a","title":"Add programmatic tip injection API","description":"Allow tips to be programmatically injected at runtime based on detected conditions. This enables dynamic tips (not just pre-defined ones) to be shown with custom priority and frequency.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-11T23:29:46.645583-08:00","updated_at":"2025-11-25T17:52:35.096882-08:00","closed_at":"2025-11-25T17:52:35.096882-08:00","dependencies":[{"issue_id":"bd-81a","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:46.646327-08:00","created_by":"daemon"}]} {"id":"bd-8a5","title":"Refactor: deduplicate FindJSONLInDir and FindJSONLPath","description":"## Background\n\nAfter fixing bd-tqo, we now have two nearly identical functions for finding the JSONL file:\n- `autoimport.FindJSONLInDir(dbDir string)` in internal/autoimport/autoimport.go\n- `beads.FindJSONLPath(dbPath string)` in internal/beads/beads.go\n\nBoth implement the same logic:\n1. Prefer issues.jsonl\n2. Fall back to beads.jsonl for legacy support\n3. Skip deletions.jsonl and merge artifacts\n4. Default to issues.jsonl if nothing found\n\n## Problem\n\nCode duplication means bug fixes need to be applied in multiple places (as we just experienced with bd-tqo).\n\n## Proposed Solution\n\nExtract shared logic to a utility package that both can import. Options:\n1. Create `internal/jsonlpath` package with the core logic\n2. Have `autoimport` import `beads` and call `FindJSONLPath` (but APIs differ slightly)\n3. Move to `internal/utils` if appropriate\n\nNeed to verify no import cycles would be created.\n\n## Affected Files\n- internal/autoimport/autoimport.go\n- internal/beads/beads.go","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-26T23:45:18.974339-08:00","updated_at":"2025-11-26T23:45:18.974339-08:00"} @@ -43,9 +41,7 @@ {"id":"bd-mnap","title":"Investigate performance issues in VS Code Copilot (Windows)","description":"Beads unusable in Windows 11 VS Code Copilot chat with Sonnet 4.5.\nSummary event happens every 3-4 turns, taking 3 minutes.\nCopilot summarizes after ~125k tokens despite model supporting 1M.\nLarge context size of beads might be triggering aggressive summarization.\nNeed workaround or optimization for context size.\n","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:30.124918-05:00","updated_at":"2025-11-20T18:56:30.124918-05:00"} {"id":"bd-nq41","title":"Fix Homebrew warning about Ruby file location","description":"Homebrew warning: Found Ruby file outside steveyegge/beads tap formula directory.\nWarning points to: /opt/homebrew/Library/Taps/steveyegge/homebrew-beads/bd.rb\nIt should likely be inside a Formula/ directory or similar structure expected by Homebrew taps.\n","status":"closed","priority":2,"issue_type":"chore","created_at":"2025-11-20T18:56:21.226579-05:00","updated_at":"2025-11-26T22:25:37.362928-08:00","closed_at":"2025-11-26T22:25:37.362928-08:00"} {"id":"bd-p6vp","title":"Clarify .beads/.gitattributes handling in Protected Branches docs","description":"Protected Branches docs quick start leaves untracked `.beads` directory and `.gitattributes`.\nQuestion: Are these changes meant to be checked into the protected branch?\nNeed to clarify if these should be ignored or committed, or if the instructions are missing a step.\n","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:25.79407-05:00","updated_at":"2025-11-26T22:25:47.574326-08:00","closed_at":"2025-11-26T22:25:47.574326-08:00"} -{"id":"bd-pbj","title":"bd doctor --fix should run bd sync to commit untracked deletions.jsonl","description":"After running bd cleanup -f, the deletions.jsonl file is created but left untracked. bd doctor --fix should notice this and run bd sync to commit it.\n\nCurrent behavior:\n- bd cleanup -f creates/updates deletions.jsonl\n- git status shows deletions.jsonl as untracked\n- bd doctor --fix does not notice or fix this\n\nExpected behavior:\n- bd doctor --fix should detect untracked .beads/*.jsonl files\n- Should offer to run bd sync to commit them\n\nRelated: The git hooks were also missing deletions.jsonl from their staging loops - that's been fixed in this session.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T20:29:33.901199-08:00","updated_at":"2025-11-26T20:33:03.296592-08:00","closed_at":"2025-11-26T20:33:03.296592-08:00"} {"id":"bd-qsm","title":"Auto-compact deletions during bd sync","description":"Parent: bd-imj\n\n## Task\nOptionally prune deletions manifest during sync when threshold exceeded.\n\n**Note: Opt-in feature** - disabled by default to avoid sync latency.\n\n## Implementation\n\nIn `bd sync`:\n```go\nfunc (s *Syncer) Sync() error {\n // ... existing sync logic ...\n \n // Auto-compact only if enabled\n if s.config.GetBool(\"deletions.auto_compact\", false) {\n deletionCount := deletions.Count(\".beads/deletions.jsonl\")\n threshold := s.config.GetInt(\"deletions.auto_compact_threshold\", 1000)\n \n if deletionCount \u003e threshold {\n retentionDays := s.config.GetInt(\"deletions.retention_days\", 7)\n if err := s.compactor.PruneDeletions(retentionDays); err != nil {\n log.Warnf(\"Failed to auto-compact deletions: %v\", err)\n // Non-fatal, continue sync\n }\n }\n }\n \n // ... rest of sync ...\n}\n```\n\n## Configuration\n```yaml\ndeletions:\n retention_days: 7\n auto_compact: false # Opt-in, disabled by default\n auto_compact_threshold: 1000 # Trigger when \u003e N entries (if enabled)\n```\n\n## Acceptance Criteria\n- [ ] Auto-compact disabled by default\n- [ ] Enabled via config `deletions.auto_compact: true`\n- [ ] Sync checks deletion count only when enabled\n- [ ] Auto-prunes when threshold exceeded\n- [ ] Failure is non-fatal (logged warning)\n- [ ] Test: no compaction when disabled\n- [ ] Test: compaction triggers when enabled and threshold exceeded","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-25T09:57:04.522795-08:00","updated_at":"2025-11-25T15:03:01.469629-08:00","closed_at":"2025-11-25T15:03:01.469629-08:00"} -{"id":"bd-red","title":"bd sync should only commit .beads/ files, not all staged changes","description":"Currently bd sync commits ALL staged files, not just .beads/*.jsonl. This can lead to:\n- Unintended commits of work-in-progress code\n- Surprise for users/agents who staged files but weren't ready to commit\n- Mixing beads sync commits with actual code changes\n\nExpected behavior: bd sync should only stage and commit .beads/ files, leaving other staged changes alone.\n\nOptions:\n1. Stash other staged changes, commit only .beads/, restore stash\n2. Use git add .beads/ \u0026\u0026 git commit -m '...' -- .beads/ to only commit beads files\n3. Warn if non-beads files are staged and require --force to proceed","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T20:35:40.212006-08:00","updated_at":"2025-11-26T20:46:26.106545-08:00","closed_at":"2025-11-26T20:46:26.106545-08:00"} {"id":"bd-s0z","title":"Consider extracting error handling helpers","description":"Evaluate creating FatalError() and WarnError() helpers as suggested in ERROR_HANDLING.md to reduce boilerplate and enforce consistency. Prototype in a few files first to validate the approach.","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-24T00:28:57.248959-08:00","updated_at":"2025-11-24T00:28:57.248959-08:00"} {"id":"bd-t3b","title":"Add test coverage for internal/config package","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:22.91657-05:00","updated_at":"2025-11-20T21:21:22.91657-05:00","dependencies":[{"issue_id":"bd-t3b","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.201036-05:00","created_by":"daemon"}]} {"id":"bd-tne","title":"Add Claude setup tip with dynamic priority","description":"Add a predefined tip that suggests running `bd setup claude` when Claude Code is detected but not configured. This tip should have higher priority (shown more frequently) until the setup is complete.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:29:29.871324-08:00","updated_at":"2025-11-25T17:52:35.044989-08:00","closed_at":"2025-11-25T17:52:35.044989-08:00","dependencies":[{"issue_id":"bd-tne","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:29.872081-08:00","created_by":"daemon"}]} diff --git a/examples/claude-code-skill/references/CLI_REFERENCE.md b/examples/claude-code-skill/references/CLI_REFERENCE.md index c6415af4..704c22b4 100644 --- a/examples/claude-code-skill/references/CLI_REFERENCE.md +++ b/examples/claude-code-skill/references/CLI_REFERENCE.md @@ -1,477 +1,559 @@ -# CLI Reference +# CLI Command Reference -Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output. +**For:** AI agents and developers using bd command-line interface +**Version:** 0.21.0+ -## Contents +## Quick Navigation -- [Quick Reference](#quick-reference) -- [Global Flags](#global-flags) -- [Core Commands](#core-commands) - - [bd ready](#bd-ready) - Find unblocked work - - [bd create](#bd-create) - Create new issues - - [bd update](#bd-update) - Update issue status, priority, assignee - - [bd close](#bd-close) - Close completed work - - [bd show](#bd-show) - Show issue details - - [bd list](#bd-list) - List issues with filters -- [Dependency Commands](#dependency-commands) - - [bd dep add](#bd-dep-add) - Create dependencies - - [bd dep tree](#bd-dep-tree) - Visualize dependency trees - - [bd dep cycles](#bd-dep-cycles) - Detect circular dependencies -- [Monitoring Commands](#monitoring-commands) - - [bd stats](#bd-stats) - Project statistics - - [bd blocked](#bd-blocked) - Find blocked work -- [Data Management Commands](#data-management-commands) - - [bd export](#bd-export) - Export database to JSONL - - [bd import](#bd-import) - Import issues from JSONL -- [Setup Commands](#setup-commands) - - [bd init](#bd-init) - Initialize database - - [bd quickstart](#bd-quickstart) - Show quick start guide -- [Common Workflows](#common-workflows) -- [JSON Output](#json-output) -- [Database Auto-Discovery](#database-auto-discovery) -- [Git Integration](#git-integration) -- [Tips](#tips) +- [Basic Operations](#basic-operations) +- [Issue Management](#issue-management) +- [Dependencies & Labels](#dependencies--labels) +- [Filtering & Search](#filtering--search) +- [Advanced Operations](#advanced-operations) +- [Database Management](#database-management) -## Quick Reference +## Basic Operations -| Command | Purpose | Key Flags | -|---------|---------|-----------| -| `bd ready` | Find unblocked work | `--priority`, `--assignee`, `--limit`, `--json` | -| `bd list` | List all issues with filters | `--status`, `--priority`, `--type`, `--assignee` | -| `bd show` | Show issue details | `--json` | -| `bd create` | Create new issue | `-t`, `-p`, `-d`, `--design`, `--acceptance` | -| `bd update` | Update existing issue | `--status`, `--priority`, `--design` | -| `bd close` | Close completed issue | `--reason` | -| `bd dep add` | Add dependency | `--type` (blocks, related, parent-child, discovered-from) | -| `bd dep tree` | Visualize dependency tree | (no flags) | -| `bd dep cycles` | Detect circular dependencies | (no flags) | -| `bd stats` | Get project statistics | `--json` | -| `bd blocked` | Find blocked issues | `--json` | -| `bd export` | Export issues to JSONL | `--json` | -| `bd import` | Import issues from JSONL | `--dedupe-after`, `--dry-run` | -| `bd init` | Initialize bd in directory | `--prefix` | -| `bd quickstart` | Show quick start guide | (no flags) | +### Check Status + +```bash +# Check database path and daemon status +bd info --json + +# Example output: +# { +# "database_path": "/path/to/.beads/beads.db", +# "issue_prefix": "bd", +# "daemon_running": true, +# "agent_mail_enabled": false +# } +``` + +### Find Work + +```bash +# Find ready work (no blockers) +bd ready --json + +# Find stale issues (not updated recently) +bd stale --days 30 --json # Default: 30 days +bd stale --days 90 --status in_progress --json # Filter by status +bd stale --limit 20 --json # Limit results +``` + +## Issue Management + +### Create Issues + +```bash +# Basic creation +# IMPORTANT: Always quote titles and descriptions with double quotes +bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json + +# Create with explicit ID (for parallel workers) +bd create "Issue title" --id worker1-100 -p 1 --json + +# Create with labels (--labels or --label work) +bd create "Issue title" -t bug -p 1 -l bug,critical --json +bd create "Issue title" -t bug -p 1 --label bug,critical --json + +# Examples with special characters (all require quoting): +bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json +bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json + +# Create multiple issues from markdown file +bd create -f feature-plan.md --json + +# Create epic with hierarchical child tasks +bd create "Auth System" -t epic -p 1 --json # Returns: bd-a3f8e9 +bd create "Login UI" -p 1 --json # Auto-assigned: bd-a3f8e9.1 +bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2 +bd create "Tests" -p 1 --json # Auto-assigned: bd-a3f8e9.3 + +# Create and link discovered work (one command) +bd create "Found bug" -t bug -p 1 --deps discovered-from: --json +``` + +### Update Issues + +```bash +# Update one or more issues +bd update [...] --status in_progress --json +bd update [...] --priority 1 --json + +# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents) +# NOTE: This command is intentionally NOT exposed via the MCP server +# Agents should use 'bd update' with field-specific parameters instead +bd edit # Edit description +bd edit --title # Edit title +bd edit --design # Edit design notes +bd edit --notes # Edit notes +bd edit --acceptance # Edit acceptance criteria +``` + +### Close/Reopen Issues + +```bash +# Complete work (supports multiple IDs) +bd close [...] --reason "Done" --json + +# Reopen closed issues (supports multiple IDs) +bd reopen [...] --reason "Reopening" --json +``` + +### View Issues + +```bash +# Show dependency tree +bd dep tree + +# Get issue details (supports multiple IDs) +bd show [...] --json +``` + +## Dependencies & Labels + +### Dependencies + +```bash +# Link discovered work (old way - two commands) +bd dep add --type discovered-from + +# Create and link in one command (new way - preferred) +bd create "Issue title" -t bug -p 1 --deps discovered-from: --json +``` + +### Labels + +```bash +# Label management (supports multiple IDs) +bd label add [...]