Beads vs Kelly Pipeline Assessment — Can Beads Replace Kelly's State Tracking?

Assessor: Carson (dark-factory-kb subagent)

Date: 2026-04-26

Sources: [[steve-yegge-beads]], [[steve-yegge-meow]], [[steve-yegge-gas-town]], Kelly pipeline documentation (METHOD.md, STAGES.md, SOURCES.md)

Assessment Framework

For each Kelly state tracking mechanism, this assessment evaluates:

• **What changes:** How the mechanism would look under a Beads-based system
• **What breaks:** Functionality that Beads cannot replicate or would require significant work to support
• **What improves:** Capabilities that Beads would add or enhance
• **Implementation complexity:** Estimated effort to implement, on a 1–5 scale (1 = trivial, 5 = major rewrite)
• **Recommendation:** Adopt / Partial Adopt / Keep Existing

2. done markers Per Subphase

What It Is

The Kelly pipeline uses explicit DONE markers (typically in memory or a separate marker file) to signal that a subphase has been completed. When a sub-agent finishes its work, it writes a DONE marker that the parent pipeline stage uses as a signal to proceed.

What Changes Under Beads

done markers become Bead state transitions. A subphase completing is a Bead moving from running → done. The equivalent of "this subphase is DONE" is a Dolt query: SELECT * FROM beads WHERE type = 'subphase' AND name = 'coding' AND status = 'done'. The git commit that records the state transition IS the DONE marker — immutable, timestamped, authored.

What Breaks

• **Simple grep-based DONE detection.** Current done markers can be found with `grep -r "DONE" memory/`. Beads require a Dolt query or a custom Beads CLI. This makes manual verification harder.
• **No visual DONE in editor.** A human reviewing the pipeline can't just open a file and see done markers. They need a Beads viewer.
• **Bead overhead for simple cases.** If a subphase is just "read this file," creating a Bead for it is heavier than writing a DONE marker.

What Improves

• **Non-repudiation.** A Bead state transition cannot be accidentally deleted or silently overwritten (Dolt enforces immutability on finalized Beads). done markers in text files can be accidentally removed or corrupted.
• **Typed DONE semantics.** A Bead's `done` state can carry metadata: who marked it done, what the outcome was, what the next Bead depends on. A text DONE marker has none of this.
• **Query across all DONE subphases.** You can ask: "Which subphases were marked done in the last hour? By which agents? On which projects?" — a query that is essentially impossible with text done markers.

Implementation Complexity: **2/5**

done markers are already semantically equivalent to Bead state transitions. Writing a Bead adapter that wraps the existing DONE marker logic is straightforward. The main effort is Dolt schema design and ensuring the adapter is transparent to existing sub-agent code.

Recommendation: **Adopt**

Replace done markers with Bead state transitions. The semantic mapping is natural, the benefits (immutability, auditability, queryability) are significant, and the implementation complexity is low. Existing sub-agent DONE marker code can be wrapped in a thin Bead adapter.

4. heartbeat

What It Is

heartbeat is Kelly's mechanism for agents to periodically check in, confirming liveness and reporting short-term status. It's a lightweight file that agents update (typically every 30 minutes) with their current activity, pending work, and state.

What Changes Under Beads

heartbeat entries become Beads of type heartbeat. Each heartbeat is a short-lived Bead with an author, timestamp, current activity, and a time-to-live (TTL). The Deacon equivalent (or Kelly's heartbeat checker) patrols heartbeat Beads, and if any agent's most recent heartbeat Bead is older than the TTL, it triggers an alert.

What Breaks

• **heartbeat is append-only in practice.** Most implementations append a new heartbeat entry rather than overwriting. Beads are immutable once finalized — appending a new Bead is natural, but the immutability constraint means you can't "edit" a heartbeat to correct it (you'd add a new Bead correcting the previous one).
• **Human readability at a glance.** Opening heartbeat in an editor shows the recent heartbeat history in a simple list. A Beads-based heartbeat requires a viewer or SQL query.
• **Very low overhead.** heartbeat is just a text file append. Setting up a Dolt instance just for heartbeats is heavier than necessary for this use case.

What Improves

• **Heartbeat history queryable.** "Which agents have missed more than 2 heartbeats in the last 24 hours?" — one SQL query vs parsing a text file.
• **Heartbeat attribution.** Each heartbeat Bead has an author. You know exactly which agent process wrote it.
• **TTL enforcement is structural, not convention.** GUPP's Deacon patrols hooks. A Beads-based heartbeat system would have the Deacon equivalent patrol heartbeat Beads structurally — it's not relying on convention, it's enforcing via the data model.

Implementation Complexity: **2/5**

Conceptually simple, but the Dolt overhead may not be justified for this specific use case. If the full Beads/Dolt infrastructure is already in place for TEA and done markers, adding heartbeats is trivial. If setting up Dolt from scratch, heartbeat is too lightweight to justify the infrastructure cost.

Recommendation: **Keep Existing (near term), Migrate if Dolt is already deployed**

If the Dolt/Beads infrastructure is deployed for TEA and done markers, migrate heartbeat to Beads as part of the same deployment. If starting fresh on just this component, keep heartbeat — the overhead of Dolt is not worth the marginal improvement for heartbeats alone.

Summary Table

Architectural Assessment

The Beads/MEOW framework is a genuine advance over the Kelly pipeline's current state tracking for the following reasons:

1. **Unified substrate.** Instead of five separate mechanisms (pipeline state, done markers, TEA audits, heartbeat, memory files), Beads provide a single substrate. All five can coexist on the same Dolt instance, queryable together. Cross-mechanism queries become possible.

1. **Reasoning as first-class data.** Kelly's TEA audit captures reasoning alongside actions, but it's a sidecar. Beads make reasoning (the `reason` field) the primary citizen — the Bead IS the work item, its git history IS the audit. This is a more powerful model.

1. **Network effects.** The more Beads in the system, the more valuable the knowledge graph becomes. A Kelly pipeline with Beads will improve over time as more work items accumulate. A Kelly pipeline with pipeline state and memory files does not.

The main risks are:

• **Migration cost.** The existing Kelly infrastructure is file-based and human-writable. Moving to Dolt requires infrastructure, tooling, and a migration strategy. This is real cost.
• **Human interface regression.** memory is extremely human-friendly. A Beads-based equivalent, even with a view layer, is a regression for the human write path until the interface matures.
• **Vendor/infra lock-in.** Dolt is a specific technology choice. Beads' benefits are tied to the Dolt implementation. If Dolt diverges or becomes unsupported, the migration cost is sunk.

These risks argue for a gradual migration rather than a big-bang rewrite — which is why the partial adopt recommendation is appropriate for most components.