opencode-beads 0.4.0 → 0.5.1

package/README.md

@@ -26,7 +26,7 @@ Optionally, pin to a specific version for stability:
 
 ```json
 {
-  "plugin": ["opencode-beads@0.4.0"]
+  "plugin": ["opencode-beads@0.5.1"]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-beads",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "A plugin for OpenCode that provides integration with the beads issue tracker.",
   "author": "Josh Thomas <josh@joshthomas.dev>",

package/vendor/commands/create.md

@@ -5,7 +5,7 @@ argument-hint: [title] [type] [priority]
 
 Create a new beads issue. If arguments are provided:
 - $1: Issue title
-- $2: Issue type (bug, feature, task, epic, chore)
+- $2: Issue type (bug, feature, task, epic, chore, decision)
 - $3: Priority (0-4, where 0=critical, 4=backlog)
 
 If arguments are missing, ask the user for:

package/vendor/commands/decision.md

@@ -0,0 +1,111 @@
+---
+description: Record, list, and manage project decisions with rationale tracking
+argument-hint: record|list|show|supersede
+---
+
+Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.
+
+Decisions use `--type decision`. The description field holds the structured decision record.
+
+## Record a Decision
+
+When the user wants to record a decision (or you invoke `bd decision record`):
+
+1. Gather the following (ask if not provided):
+   - **Title**: Short summary of what was decided (required)
+   - **Rationale**: Why this was chosen (required)
+   - **Alternatives**: What else was considered (optional but encouraged)
+   - **Affects**: Issue IDs this decision impacts (optional)
+   - **Priority**: How important (default P2)
+
+2. Create the issue with structured description:
+
+```bash
+bd create "<title>" --type decision \
+  --description "$(cat <<'EOF'
+## Decision
+
+<one-sentence summary of what was decided>
+
+## Rationale
+
+<why this was chosen>
+
+## Alternatives Considered
+
+- **<alt 1>**: <why rejected>
+- **<alt 2>**: <why rejected>
+
+## Affects
+
+- <issue IDs or area descriptions>
+EOF
+)"
+```
+
+3. If `--affects` issue IDs were provided, link them:
+```bash
+bd dep add <decision-id> <affected-id> --type related
+```
+
+4. Show the created decision to the user.
+
+## List Decisions
+
+```bash
+bd list --type decision
+```
+
+To see all decisions including closed/superseded:
+```bash
+bd list --type decision --all
+```
+
+## Show a Decision
+
+```bash
+bd show <decision-id>
+```
+
+Include comments for discussion history:
+```bash
+bd comments <decision-id>
+```
+
+## Supersede a Decision
+
+When a decision is replaced by a new one:
+
+1. Record the new decision (as above)
+2. Link the new decision to the old one:
+   ```bash
+   bd dep add <new-id> <old-id> --type related
+   ```
+3. Add a comment on the old decision:
+   ```bash
+   bd comments add <old-id> "Superseded by <new-id>: <brief reason>"
+   ```
+4. Close the old decision:
+   ```bash
+   bd close <old-id> --reason "Superseded by <new-id>"
+   ```
+
+## Add Context to an Existing Decision
+
+Use comments to append discussion, implementation notes, or revisit rationale:
+```bash
+bd comments add <decision-id> "Implementation note: ..."
+```
+
+## Search Decisions
+
+```bash
+bd search "keyword" --type decision
+```
+
+## Conventions
+
+- **Status**: `open` = active decision, `closed` = superseded or reversed
+- **Description format**: Use the structured template above for consistency
+- **Linking**: Use `related` dependency type to connect decisions to affected issues
+- **Labels**: Use labels for categorizing decisions (e.g., `architecture`, `tooling`, `process`)

package/vendor/commands/list.md

@@ -9,7 +9,7 @@ List beads issues with optional filtering.
 
 - **--status, -s**: Filter by status (open, in_progress, blocked, closed)
 - **--priority, -p**: Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
-- **--type, -t**: Filter by type (bug, feature, task, epic, chore)
+- **--type, -t**: Filter by type (bug, feature, task, epic, chore, decision)
 - **--assignee, -a**: Filter by assignee
 - **--label, -l**: Filter by labels (comma-separated, must have ALL labels)
 - **--label-any**: Filter by labels (OR semantics, must have AT LEAST ONE)

package/vendor/commands/search.md

@@ -29,7 +29,7 @@ Unlike `bd list`, which requires you to specify which field to search, `bd searc
 
 - **--status, -s**: Filter by status (open, in_progress, blocked, closed)
 - **--assignee, -a**: Filter by assignee
-- **--type, -t**: Filter by type (bug, feature, task, epic, chore)
+- **--type, -t**: Filter by type (bug, feature, task, epic, chore, decision)
 - **--label, -l**: Filter by labels (must have ALL specified labels)
 - **--label-any**: Filter by labels (must have AT LEAST ONE)
 - **--limit, -n**: Limit number of results (default: 50)

package/vendor/commands/daemon.md

@@ -1,58 +0,0 @@
----
-description: Manage background sync daemon
-argument-hint: [start] [stop] [status]
----
-
-Manage the per-project background daemon that handles database connections and syncs with git.
-
-## Per-Project Daemon (LSP Model)
-
-Each project runs its own daemon at `.beads/bd.sock` for complete database isolation.
-
-> On Windows this file stores the daemon's loopback TCP endpoint metadata—leave it in place so bd can reconnect.
-
-**Why per-project daemons?**
-- Complete database isolation between projects
-- No cross-project pollution or git worktree conflicts
-- Simpler mental model: one project = one database = one daemon
-- Follows LSP (Language Server Protocol) architecture
-
-**Note:** Global daemon support was removed in v0.16.0. The `--global` flag is no longer functional.
-
-## When to Use Daemon Mode
-
-**✅ You SHOULD use daemon mode if:**
-- Working in a team with git remote sync
-- Want automatic commit/push of issue changes
-- Need background auto-sync (5-second debounce)
-- Making frequent bd commands (performance benefit from connection pooling)
-
-**❌ You DON'T need daemon mode if:**
-- Solo developer with local-only tracking
-- Working in git worktrees (use --no-daemon to avoid conflicts)
-- Running one-off commands or scripts
-- Debugging database issues (direct mode is simpler)
-
-**Local-only users:** Direct mode (default without daemon) is perfectly fine. The daemon mainly helps with git sync automation. You can still use `bd sync` manually when needed.
-
-**Performance note:** For most operations, the daemon provides minimal performance benefit. The main value is automatic JSONL export (5s debounce) and optional git sync (--auto-commit, --auto-push).
-
-## Common Operations
-
-- **Start**: `bd daemon start` (or auto-starts on first `bd` command)
-- **Stop**: `bd daemon stop`
-- **Status**: `bd daemon status`
-- **Health**: `bd daemon status --all` - 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)
-
-The daemon provides:
-- Connection pooling and caching
-- Better performance for frequent operations
-- Automatic JSONL sync (5-second debounce)
-- Optional git sync

package/vendor/commands/daemons.md

@@ -1,242 +0,0 @@
-# bd daemons - Daemon Management
-
-Manage bd daemon processes across all repositories and worktrees.
-
-## Synopsis
-
-```bash
-bd daemons <subcommand> [flags]
-```
-
-## Description
-
-The `bd daemons` command provides tools for discovering, monitoring, and managing multiple bd daemon processes across your system. This is useful when working with multiple repositories or git worktrees.
-
-## Subcommands
-
-### list
-
-List all running bd daemons with metadata.
-
-```bash
-bd daemons list [--search DIRS] [--json] [--no-cleanup]
-```
-
-**Flags:**
-- `--search` - Directories to search for daemons (default: home, /tmp, cwd)
-- `--json` - Output in JSON format
-- `--no-cleanup` - Skip auto-cleanup of stale sockets
-
-**Example:**
-```bash
-bd daemons list
-bd daemons list --search /Users/me/projects --json
-```
-
-### health
-
-Check health of all bd daemons and report issues.
-
-```bash
-bd daemons health [--search DIRS] [--json]
-```
-
-Reports:
-- Stale sockets (dead processes)
-- Version mismatches between daemon and CLI
-- Unresponsive daemons
-
-**Flags:**
-- `--search` - Directories to search for daemons
-- `--json` - Output in JSON format
-
-**Example:**
-```bash
-bd daemons health
-bd daemons health --json
-```
-
-### stop
-
-Stop a specific daemon gracefully.
-
-```bash
-bd daemons stop <workspace-path|pid> [--json]
-```
-
-**Arguments:**
-- `<workspace-path|pid>` - Workspace path or PID of daemon to stop
-
-**Flags:**
-- `--json` - Output in JSON format
-
-**Example:**
-```bash
-bd daemons stop /Users/me/projects/myapp
-bd daemons stop 12345
-bd daemons stop /Users/me/projects/myapp --json
-```
-
-### restart
-
-Restart a specific daemon gracefully.
-
-```bash
-bd daemons restart <workspace-path|pid> [--search DIRS] [--json]
-```
-
-Stops the daemon gracefully, then starts a new one in its place. Useful after upgrading bd or when a daemon needs to be refreshed.
-
-**Arguments:**
-- `<workspace-path|pid>` - Workspace path or PID of daemon to restart
-
-**Flags:**
-- `--search` - Directories to search for daemons
-- `--json` - Output in JSON format
-
-**Example:**
-```bash
-bd daemons restart /Users/me/projects/myapp
-bd daemons restart 12345
-bd daemons restart /Users/me/projects/myapp --json
-```
-
-### logs
-
-View logs for a specific daemon.
-
-```bash
-bd daemons logs <workspace-path|pid> [-f] [-n LINES] [--json]
-```
-
-**Arguments:**
-- `<workspace-path|pid>` - Workspace path or PID of daemon
-
-**Flags:**
-- `-f, --follow` - Follow log output (like tail -f)
-- `-n, --lines INT` - Number of lines to show from end (default: 50)
-- `--json` - Output in JSON format
-
-**Example:**
-```bash
-bd daemons logs /Users/me/projects/myapp
-bd daemons logs 12345 -n 100
-bd daemons logs /Users/me/projects/myapp -f
-bd daemons logs 12345 --json
-```
-
-### killall
-
-Stop all running bd daemons.
-
-```bash
-bd daemons killall [--search DIRS] [--force] [--json]
-```
-
-Uses escalating shutdown strategy:
-1. RPC shutdown (2 second timeout)
-2. SIGTERM (3 second timeout)
-3. SIGKILL (1 second timeout)
-
-**Flags:**
-- `--search` - Directories to search for daemons
-- `--force` - Use SIGKILL immediately if graceful shutdown fails
-- `--json` - Output in JSON format
-
-**Example:**
-```bash
-bd daemons killall
-bd daemons killall --force
-bd daemons killall --json
-```
-
-## Common Use Cases
-
-### Version Upgrade
-
-After upgrading bd, restart all daemons to use the new version:
-
-```bash
-bd daemons health  # Check for version mismatches
-bd daemons killall # Stop all old daemons
-# Daemons will auto-start with new version on next bd command
-
-# Or restart a specific daemon
-bd daemons restart /path/to/workspace
-```
-
-### Debugging
-
-Check daemon status and view logs:
-
-```bash
-bd daemons list
-bd daemons health
-bd daemons logs /path/to/workspace -n 100
-```
-
-### Cleanup
-
-Remove stale daemon sockets:
-
-```bash
-bd daemons list  # Auto-cleanup happens by default
-bd daemons list --no-cleanup  # Skip cleanup
-```
-
-### Multi-Workspace Management
-
-Discover daemons in specific directories:
-
-```bash
-bd daemons list --search /Users/me/projects
-bd daemons health --search /Users/me/work
-```
-
-## Troubleshooting
-
-### Stale Sockets
-
-If you see stale sockets (dead process but socket file exists):
-
-```bash
-bd daemons list  # Auto-cleanup removes stale sockets
-```
-
-### Version Mismatch
-
-If daemon version != CLI version:
-
-```bash
-bd daemons health  # Identify mismatched daemons
-bd daemons killall # Stop all daemons
-# Next bd command will auto-start new version
-```
-
-### Daemon Won't Stop
-
-If graceful shutdown fails:
-
-```bash
-bd daemons killall --force  # Force kill with SIGKILL
-```
-
-### Can't Find Daemon
-
-If daemon isn't discovered:
-
-```bash
-bd daemons list --search /path/to/workspace
-```
-
-Or check the socket manually:
-
-```bash
-ls -la /path/to/workspace/.beads/bd.sock
-```
-
-## See Also
-
-- [bd daemon](daemon.md) - Start a daemon manually
-- [AGENTS.md](../AGENTS.md) - Agent workflow guide
-- [README.md](../README.md) - Main documentation