feat: Add state lifecycle ops

.beads/.gitignore

@@ -1,17 +1,10 @@
 # SQLite databases
 *.db
+*.db?*
 *.db-journal
 *.db-wal
 *.db-shm
 
-beads.base.jsonl
-beads.left.jsonl
-beads.right.jsonl
-beads.base.meta.json
-beads.left.meta.json
-beads.right.meta.json
-*.db?*
-
 # Daemon runtime files
 daemon.lock
 daemon.log
@@ -22,8 +15,15 @@ bd.sock
 db.sqlite
 bd.db
 
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
 # Keep JSONL exports and config (source of truth for git)
-!*.jsonl
+!issues.jsonl
+!metadata.json
 !config.json
-
-*.log.gz

.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.claude/commands/speckit.implement.md

@@ -106,7 +106,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Polish and validation**: Unit tests, performance optimization, documentation
 
 8. Progress tracking and error handling:
-   - Find ready tasks using `bd ready --json | jq -r '.[] | select(.labels // [] | contains(["spec:......"])) | select (.issue_type == "task")| [.id, .title] | @tsv'`
+   - Find ready tasks using `bd ready --label "spec:......"`
    - Update Beads Issues progress with Comments and Progress
    - Report progress after each completed task
    - Halt execution if any sequential task fails

.claude/commands/speckit.resume.md

@@ -0,0 +1,53 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md (Beads)
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Read tasks.md structure and use Beads to extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, design + acceptance criteria
+   - **Task comments**: Important notes and modifications to original plan
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Find ready tasks using `bd ready --label "spec:......"`
+   - Update Beads Issues progress with Comments and Progress
+   - Report progress after each completed task
+   - Halt execution if any sequential task fails
+   - For ready tasks, continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to add relevant comments and update the Beads task status to "Closed"
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.

.claude/commands/speckit.tasks.md

@@ -61,17 +61,18 @@ You **MUST** consider the user input before proceeding (if not empty).
    This file does **not** list every task.
    - tasks.md acts as an index for querying Beads
    - For each phase and task described below also create corresponding use beads as shown in Phase 1 example
-   - Phase 1: Setup tasks (project initialization) create a `feature`-type issue using the CLI `bd create` tool
+   - Phase 1: Setup tasks (project initialization) create a `feature`-type issue using the CLI `bd create` command.
       - Set `--parent <epic-id>` from the epic created above
       - Labels:
          - `phase:<phase-name>` (e.g. `phase:setup`, `phase:us1`, `phase:foundational`)
          - All carry the `spec:<feature-slug>` label
-      - For each task, use `create` tool with `issue_type: "task"` and `--parent <feature-id>`
+      - For each task, use `bd create` with `--type task` and `--parent <feature-id>`
       - Tasks must include:
          - `title` (short summary)
-         - `description` (what to implement, where, inputs/outputs)
-         - `priority` (from story priority)
-         - `acceptance` criteria if available
+         - `description` Problem statement (WHY this matters) - immutable (what to implement, where, inputs/outputs)
+         - `design` HOW to build, Which files, references (can change during work)
+         - `acceptance` Acceptance: WHAT success looks like (stays stable)
+         - `priority` (from story priority, 0=critical, 1=high, 2=normal, 3=low)
          - Labels:
             - `story:US1`, `story:US2`, etc. (mapped from spec.md)
             - `component:<area>` (e.g. `component:auth`, `component:db`)
@@ -88,8 +89,8 @@ You **MUST** consider the user input before proceeding (if not empty).
      - List of features (setup, foundational, stories)
      - Beads commands to filter each group:
        ```bash
-       bd list --label: "spec:<slug>" -n 10
-       bd ready -n 5
+       bd list --label "spec:<slug>" -n 10
+       bd ready --label "spec:<slug>" -n 5
        ```
      - MVP and incremental delivery summary
      - Links back to spec.md and plan.md
@@ -110,7 +111,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 Context for task generation: $ARGUMENTS
 
-The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context. Particularly focus on breaking down by user story to enable independent implementation and testing against agreed interfaces and with clear instructions not to duplicate work (Provide assumptions based on task completion by other agents for parallel work).
 
 ## Task Generation Rules
 
@@ -177,8 +178,33 @@ bd create "Login Feature" --description "..." --type "epic" --labels "spec:006-l
 bd create "Setup Phase" --description "..." --type "feature" --deps "parent-child:grid-epic-id" --labels "spec:006-login-auth,phase:setup,component:infra" --priority 1
 ```
 
+**Use --design flag for:**
+- Implementation approach decisions
+- Architecture notes
+- Trade-offs considered
+
+**Use --acceptance flag for:**
+- Definition of done
+- Testing requirements
+- Success metrics
+
+
 ### Task
 
 ```bash
 bd create "Add React LoginForm" --description "..." --type "task" --deps "parent-child:grid-feature-id" --labels "spec:006-login-auth,story:US1,component:webapp" --priority 2
 ```
+
+**Use --design flag for:**
+- Implementation approach decisions
+- HOW to build
+- WHERE to build (which files, which modules to depend on)
+
+**Use --acceptance flag for:**
+- Definition of done
+- Acceptance: WHAT success looks like (stays stable)
+- Testing mechanism
+
+**Use --notes flag for:**
+- Additional context
+- References to research or design docs

.claude/skills/bd-issue-tracking/SKILL.md

@@ -224,11 +224,18 @@ bd ready --assignee alice    # Filter by assignee
 ```
 
 **Create new issue:**
+
+**IMPORTANT**: Always quote title and description arguments with double quotes, especially when containing spaces or special characters.
+
 ```bash
 bd create "Fix login bug"
 bd create "Add OAuth" -p 0 -t feature
 bd create "Write tests" -d "Unit tests for auth module" --assignee alice
 bd create "Research caching" --design "Evaluate Redis vs Memcached"
+
+# Examples with special characters (requires quoting):
+bd create "Fix: auth doesn't handle edge cases" -p 1
+bd create "Refactor auth module" -d "Split auth.go into separate files (handlers, middleware, utils)"
 ```
 
 **Update issue status:**