[FEATURE] Enhanced Beads/Beads-BV Integration for Zeroshot

[RaviTharuma]

Problem

Currently, zeroshot accepts task input from multiple sources (GitHub issues, GitLab issues, Jira, Azure DevOps, markdown files, or inline text). While this flexibility is valuable, the task orchestration and memory management rely entirely on the AI provider's context window and zeroshot's internal SQLite-based state persistence.

This creates several limitations for complex, long-running projects:

1. No Structured Task Graph: When a task spawns subtasks or discovers new issues during implementation, there's no native way to track dependencies, blockers, or hierarchical relationships between tasks.

2. Context Window Bloat: As iterations progress, the planner and validators must re-parse the entire task state from scratch in each cycle. With 5+ iterations on complex tasks, this means redundant context consumption.

3. No Cross-Session Task Memory: While zeroshot has crash-safe SQLite state, there's no semantic compaction or "memory decay" for closed/resolved subtasks. Old work stays in the working set indefinitely.

4. Limited Multi-Task Coordination: If users want to track multiple related tasks (e.g., "Fix auth bug" + "Add auth tests" + "Update auth docs"), they must manually manage separate zeroshot runs or encode everything in a single large issue.

5. No Ready-Work Detection: Zeroshot processes tasks sequentially. It cannot intelligently detect which subtasks are unblocked and ready to work on first.

Beads and Beads-BV solve these exact problems - but zeroshot currently has no integration path.

Proposed Solution

Add optional Beads/Beads-BV backend support as an alternative task orchestration layer for zeroshot. This would enable:

1. Beads as Task Input Source

Allow zeroshot to accept Beads issues as task input:

# Run zeroshot on a specific Beads issue
zeroshot run --beads bd-a1b2

# Run zeroshot on all ready Beads tasks
zeroshot run --beads-ready

# Initialize zeroshot project from existing GitHub issue, auto-create Beads structure
zeroshot run 123 --init-beads

How it works:

• --beads bd-xyz: Zeroshot reads issue description, acceptance criteria, and dependencies from .beads/ via bd show bd-xyz --json
• --beads-ready: Zeroshot queries bd ready --json and presents user with list of unblocked tasks to choose from
• --init-beads: Converts GitHub/GitLab issue into Beads structure with auto-created subtasks

2. Automatic Subtask Discovery and Linking

When the planner agent decomposes work into subtasks, automatically create Beads issues:

# User runs zeroshot on high-level task
zeroshot run "Add user authentication system"

# Zeroshot planner breaks it down:
# → Zeroshot auto-creates in Beads:
#   bd-101: "Add user authentication system" (parent, status: in_progress)
#   bd-102: "Create User model with password hashing" (deps: bd-101)
#   bd-103: "Implement login endpoint" (deps: bd-102)
#   bd-104: "Add JWT token generation" (deps: bd-102)
#   bd-105: "Write auth tests" (deps: bd-103, bd-104)

Implementation:

• Planner output is parsed for subtask list
• Each subtask → bd create with --deps parent:bd-101
• Dependencies automatically tracked in Beads graph
• Zeroshot updates bd-101 status as it progresses through subtasks

3. Beads-BV Integration for Intelligent Task Selection

When multiple tasks are ready, use Beads-BV to prioritize:

# Zeroshot detects 5 ready tasks
zeroshot run --beads-ready --use-bv

# Internally:
# 1. Query `bv --robot-triage --json` for task ranking
# 2. Use `bv --robot-next` to get highest-impact task
# 3. Pass only that task + critical blockers to planner
# 4. Reduce context by ~40-60% vs passing all 5 tasks

Benefits:

• Bottleneck-aware: Work on tasks that unblock the most downstream work
• Context-efficient: Only inject high-priority tasks into planner context
• Deterministic: Same task graph always yields same prioritization

4. Validator Result Persistence in Beads

Store validator results as Beads comments/updates:

# After validator runs tests
bd update bd-103 --status validated --json
bd comment bd-103 "All 15 tests passing. Coverage: 94%. See: test-output.log"

# After validator finds issues
bd update bd-103 --status needs_revision --json
bd comment bd-103 "Integration test failed: AuthService.login() returns 500 when password has special chars"
bd create "Fix: AuthService password escaping" --deps blocks:bd-103 --priority 0

Benefits:

• Audit trail: Every validation result stored in git-tracked .beads/
• Resume-friendly: If zeroshot crashes, validator results persist
• Multi-agent ready: Multiple zeroshot instances can work in parallel, updating different Beads issues

5. Context Compaction via Beads Memory Decay

After 7 days (configurable), auto-summarize closed Beads tasks:

# Zeroshot calls bd compact before each iteration
bd compact --older-than 7d --json

# Closed tasks → summarized
# Open tasks → full detail
# Result: 60-80% context reduction for long-running projects

6. Configuration

Add beads section to zeroshot config:

# .zeroshot/config.yaml (or CLI flags)
beads:
  enabled: true
  use_bv: true  # Enable Beads-BV for intelligent prioritization
  auto_create_subtasks: true  # Auto-create Beads issues from planner decomposition
  auto_link_discovered: true  # Link issues discovered during implementation
  compact_after_days: 7  # Summarize closed tasks older than 7 days
  sync_validator_results: true  # Store validator results as Beads comments

7. Example Workflow

# 1. User points zeroshot at GitHub issue
zeroshot run 456 --init-beads

# Zeroshot:
# - Fetches GitHub issue content
# - Creates bd-201 as parent task
# - Planner decomposes into 8 subtasks (bd-202 to bd-209)
# - Planner identifies dependencies (bd-205 blocks bd-207, bd-208)
# - All created in .beads/ with dependency graph

# 2. Zeroshot uses bv to pick first task
bv --robot-next  # Returns bd-202 (highest impact, zero blockers)

# 3. Implementer agent works on bd-202
# - Makes changes
# - Updates bd-202 status: in_progress

# 4. Validator runs
# - Tests pass
# - zeroshot: `bd close bd-202 --reason "All tests passing"`

# 5. bv recalculates
bv --robot-next  # Returns bd-203 (now unblocked)

# 6. Iteration continues until all subtasks closed
# 7. Final sync
bd sync  # Pushes all task state to git

Alternatives Considered

1. Keep current SQLite-only state

   • Simple but doesn't solve context bloat, dependency tracking, or multi-agent coordination

2. Build custom task graph in zeroshot

   • Reinvents what Beads already does perfectly
   • No git-native sync, no compaction, no multi-agent support

3. Use Beads only, skip Beads-BV

   • Loses intelligent prioritization and context savings

4. Require external project management tools (Jira, Linear)

   • Adds latency, cost, external dependencies
   • Not git-native, not suitable for local/offline workflows

Additional Context

• Beads is production-ready: 13.7k GitHub stars, proven in long-running Claude Code workflows
• Beads-BV is mature: PageRank + critical path analysis with --robot-* flags for agents
• Alignment with zeroshot's goals: Both tools prioritize correctness over speed, multi-agent coordination, and production-grade output
• Low coupling: Beads uses --json flags and Unix patterns - easy to integrate without tight coupling
• User value: This would make zeroshot the go-to tool for complex, multi-week projects with dozens of subtasks
• Your note: "beads is great and better than prd.json alone" - suggests Beads' graph-aware, queryable, hierarchical structure provides clear value over simple JSON task files

Related Resources

• Beads GitHub
• Beads-BV (Beads Viewer)
• Beads + Claude Code Integration