[Feature]: Integrate Beads for dependency-aware task execution (v3.0)

[pedroalmeida415]

🎯 Summary

Integrate Beads - a lightweight git-based issue tracker designed for AI agents - to replace Smart Ralph's linear task execution with dependency-aware parallel execution.

⚠️ Breaking Change: This would be a major architectural change targeting v3.0

---

🚀 Why Beads?

Current Smart Ralph	With Beads
Linear task list with [P] markers	True dependency DAG with blocks relationships
Custom .ralph-state.json management	Git-native state via JSONL (auto-sync)
Manual parallel task detection	bd list --ready finds all unblocked tasks in ~10ms
Large .progress.md context loading	bd prime provides compact 1-2k token context
Custom completion verification	bd doctor detects orphaned work automatically
Race conditions with parallel temp files	Hash-based IDs prevent collisions

---

📊 Key Benefits

1. Smarter Parallel Execution

Current: Linear scan for [P] markers
         1.1 → 1.2 → [P]1.3 → [P]1.4 → 1.5

With Beads: True dependency resolution
         1.1 ──blocks──► 1.2 ──blocks──┬──► 1.3 ──┐
                                       │          ├──blocks──► 1.5
                                       └──► 1.4 ──┘

bd list --ready automatically returns [1.3, 1.4] when 1.2 completes

2. Simplified State Management

# No more custom state file parsing
bd list --ready --json    # What can run now?
bd show $ID --json        # Task details
bd close $ID              # Mark complete
bd sync                   # Push state to git

3. Better Context Efficiency

• bd prime: ~1-2k tokens of structured workflow context
• vs. reading entire .progress.md which can grow unbounded

4. Built-in Audit Trail

git commit -m "feat(auth): implement OAuth2 (bd-a3f8e9)"
#                                            ↑ issue ID in commit

5. Cross-Spec Tracking

bd create --title "user-auth" --related bd-xyz789
# Native relationship tracking replaces relatedSpecs array

---

🔧 Proposed Changes

Phase 1: Non-Breaking Additions

• Add bd sync to ALL_TASKS_COMPLETE protocol
• Include Beads issue IDs in commit messages
• Use bd doctor for completion verification

Phase 2: Task Management (Breaking)

• task-planner creates Beads issues with --blocks relationships
• Coordinator uses bd list --ready instead of taskIndex
• Replace .ralph-state.json with Beads as source of truth

Phase 3: Context Optimization

• Inject bd prime output into spec-executor context
• Store learnings in Beads issue notes vs .progress.md

---

📋 Migration Path

1. v2.x: Add optional Beads support (feature flag)
2. v3.0: Beads becomes default, legacy mode deprecated
3. v3.1+: Remove legacy .ralph-state.json support

---

🔗 References

• Beads Repository
• Beads Agent Instructions
• Beads FAQ

---

💬 Discussion

Looking for feedback on:

1. Is the migration path reasonable?
2. Should we support both modes long-term or fully migrate?
3. Any concerns about adding Beads as a dependency?

cc @tzachbon

[pedroalmeida415]

Draft PR on the way for this

[pedroalmeida415]

Draft here: #48

Needs some polishing so I'll be making some changes throughout the next hours, just FYI

[pedroalmeida415]

Just saw issue #46

@tzachbon Do you think it is basically the same thing as what I'm proposing here with Beads?

[pedroalmeida415]

I think there might be some overlap but I can definitely see the two working together tbh. Beads can help us get rid of the exhaustive arbitrary rules in the agents instructions that specify things like parallelism, dependency, orphan-tasks and whatnot

[tzachbon]

Just saw issue #46

@tzachbon Do you think it is basically the same thing as what I'm proposing here with Beads?

Oh I definitely don't see it as a conflict. It's just another flavor of spec driven development

[tzachbon]

I love the idea. It could make the current specs and tasks dependencies much more robust. Can't wait to see the PR.

[pedroalmeida415]

Good to know! I'll start work off of your speckit branch so we don't end up with too many conflicts

[pedroalmeida415]

Did some experimenting for a while but couldn't find a satisfactory way of integrating it into the flow yet. Will be doing some more tinkering tomorrow.

The main value propositions I see to adding Beads are:

1. No overhead of keeping tasks order, index, and context in sync, effectively replacing ralph-state.json and tasks.md.
2. Commit messages can include bead hash for traceability
3. Trivial parallelism (bd ready --json → dispatch N parallel subagents, each claims their own issue)
4. Clear stop condition (ran out of available tasks)

Simply running bd ready when spec-executor yields back to orchestrator -> shows all available tasks -> dispatch one or multiple agents in parallel depending on the dependency graph which dictates available tasks.

spec-executors then have the responsibility of claiming their beads and closing them, possibly creating new beads with issues discovered on-the-fly. They grab the task context easily by doing bd show <id> --json (gives narrow context, just that task) and/or bd dep tree <id> for dependencies if needed.

Cons:

1. New dependency (user has to install Beads binary)
2. Couldn't find a cohesive way to wire Beads up with the rest of the flow;
3. If it ain't broke, don't fix it? (Maybe the tasks.md and ralph-state.json are just good enough honestly);

[tzachbon]

Did some experimenting for a while but couldn't find a satisfactory way of integrating it into the flow yet. Will be doing some more tinkering tomorrow.

The main value propositions I see to adding Beads are:

1. No overhead of keeping tasks order, index, and context in sync, effectively replacing ralph-state.json and tasks.md.
2. Commit messages can include bead hash for traceability
3. Trivial parallelism (bd ready --json → dispatch N parallel subagents, each claims their own issue)
4. Clear stop condition (ran out of available tasks)

Simply running bd ready when spec-executor yields back to orchestrator -> shows all available tasks -> dispatch one or multiple agents in parallel depending on the dependency graph which dictates available tasks.

spec-executors then have the responsibility of claiming their beads and closing them, possibly creating new beads with issues discovered on-the-fly. They grab the task context easily by doing bd show <id> --json (gives narrow context, just that task) and/or bd dep tree <id> for dependencies if needed.

Cons:

1. New dependency (user has to install Beads binary)
2. Couldn't find a cohesive way to wire Beads up with the rest of the flow;
3. If it ain't broke, don't fix it? (Maybe the tasks.md and ralph-state.json are just good enough honestly);

IMO when it can be programmatic, it should be. It's more robust for tracking dependencies, so generally a good idea. Maybe keep tasks.md for user control over LLM tasks when needed.

For integrating into the repo (smart-ralph marketplace), it's probably better to create a new plugin from scratch. We can test it, verify it works well, then integrate to the existing plugin. Thoughts?

EDIT: it would also help you avoid the code conflicts