manual_slop/conductor/tracks/beads_mode_20260309/spec.md

Specification: Beads Mode Integration

Overview

Introduce "Beads Mode" as a first-class, project-specific alternative to the current markdown-based implementation tracking (Native Mode). By integrating with Beads, Manual Slop will gain a distributed, git-backed graph issue tracker that allows Implementation Tracks and Tickets to be versioned alongside the codebase using Dolt.

Functional Requirements

• Execution Modes:
  • Native Mode (Default): Continues using conductor/tracks.md and <track_id>/plan.md for task management.
  • Beads Mode: Uses a local .beads repository (backed by Dolt) to store the task graph.
• Project-Level Configuration:
  • Add a mode = "native" | "beads" toggle to the [project] section of manual_slop.toml.
  • This setting is intended to be set during project initialization and remain stable.
• Data Mapping:
  • Tracks as Epics: Each implementation track maps to a top-level Bead.
  • Tickets as Sub-beads: Plan tasks and sub-tasks map to hierarchical Beads (using dot notation).
  • Dependencies: Map task dependencies to Beads' semantic relationships (blocks, relates_to).
• Agent Integration:
  • Beads Toolset: Implement a new MCP toolset (e.g., bd_create, bd_update, bd_ready, bd_list) that allows agents to interact directly with the Beads graph.
  • Compaction Logic: Utilize Beads' compaction/summarization feature to feed agents a concise summary of completed work while keeping the context window focused on the active task.
• GUI Integration (MMA Dashboard):
  • Augmented Visual DAG: Ensure the imgui-node-editor can visualize nodes from the Beads graph when in Beads Mode.
  • Beads Tab: Add a dedicated "Beads" panel/tab within the Operations Hub or MMA Dashboard to browse the Dolt-backed graph.
  • Stream Integration: Tier streams should display Bead IDs and status updates in real-time.

Non-Functional Requirements

• Prerequisites: Users must have the bd CLI and dolt installed to use Beads Mode.
• Sync Integrity: Ensure the GUI state remains synchronized with the local Dolt database.
• Performance: Browsing large task graphs must not impact GUI responsiveness.

Acceptance Criteria

• A project can be toggled to "Beads Mode" in its TOML configuration.
• Creating a new track in Beads Mode initializes a corresponding Epic Bead.
• The Visual DAG correctly renders nodes and links queried from the Beads backend.
• Agents can successfully query for "ready" tasks and update their status using Beads-specific tools.
• Completed tasks are automatically summarized using the compaction protocol before being sent to agent context.

Out of Scope

• Hosting a central Beads/Dolt server (focus is on local distributed tracking).
• Converting existing Native Mode projects to Beads Mode automatically (initial implementation focus).