#261 Give fleet members access to beads (and its DB) so PLAN.md / progress.json can be removed from the PM workflow

[Anonymous]

Originally created by: kumaakh

Problem

The PM workflow currently uses three living files in each project sandbox:

• PLAN.md — sprint plan for the doer
• progress.json — turn-by-turn state
• feedback.md — reviewer notes

These files are committed and pushed to the working branch on every turn so that PM, doer, and reviewer stay in sync. That solves coordination, but it has real costs:

• Branch noise — every sprint pollutes git history with PM-state commits that have nothing to do with the change.
• Merge friction when multiple pairs work in parallel — progress.json is the canonical conflict file.
• Cross-sprint visibility is poor — you have to read each branch's PLAN.md separately. There is no global view.
• Recovery after a PM restart involves re-reading per-project files instead of querying one DB.

PM already uses beads (bd CLI, persistent SQLite DB) as the source of truth for tasks, dependencies, status, assignees, and notes. Beads can do everything PLAN.md and progress.json do today — and more (cross-sprint queries, dependency graph, blocked/ready filters, search, audit trail).

Proposal

Make beads the single source of truth for sprint state. Members (doer + reviewer) should have first-class access to the beads DB so PM can drop the markdown/JSON state files entirely.

What members need

1. bd CLI installed on every member. Already true today on local members; needs to be guaranteed on remote members during onboarding (similar to how the Claude/Gemini CLI is installed).
2. Access to the same beads database PM uses. This is the hard part — see options below.
3. Permissions to run bd update, bd close, bd create, bd remember, bd show from inside execute_command / execute_prompt. The doer needs to claim and close issues; the reviewer needs to file findings as new issues.

How to share the DB

Pick one — open question for the design discussion:

Option	How it works	Tradeoffs
A. Sync via git	Commit .beads/issues.jsonl to the repo on a dedicated beads/ branch (or in a sidecar repo). Members bd dolt pull / push like PM does.	Simple, uses existing beads sync. Adds one more push per turn (replaces the 3 state files, so net win).
B. Server-mediated	Fleet server proxies bd commands to PM's local DB on behalf of members. New MCP tools: beads_update, beads_close, etc.	No git involvement. Centralised. Requires building MCP surface and handling concurrency.
C. Shared DB file over network	Members access a network-mounted SQLite file.	Fragile, locking issues, not viable for remote members.

A and B are both reasonable. A is closer to how beads is meant to be used (it has built-in dolt push/pull); B gives PM more control over who can do what.

What goes away

• PLAN.md — replaced by bd list --epic <sprint-id> --tree
• progress.json — replaced by bd show <task-id> + bd list --status=in_progress
• feedback.md — replaced by bd create for each finding (already partially done — see PM skill's reviewer protocol)

Sprint-specific requirements (requirements.md, design notes, technotes) stay in the project sandbox — those are documentation, not state.

Acceptance criteria

• [ ] Members have bd available (verified during register_member onboarding).
• [ ] A documented mechanism for members to read/write the same beads DB PM uses (option A, B, or other).
• [ ] PM skill updated: single-pair-sprint.md, simple-sprint.md, multi-pair-sprint.md, doer-reviewer.md no longer reference PLAN.md / progress.json / feedback.md as living state files.
• [ ] Existing PM workflows continue to function — e.g., `/pm status`, `/pm recover`, verify checkpoints, doer→reviewer handoff — all driven from beads.
• [ ] Migration path for in-flight sprints (one-shot import of PLAN.md → beads tasks).

Out of scope

• Replacing requirements.md or design notes — those are project documentation, not sprint state.
• Changing how beads itself works internally (no CLI changes proposed here).

Why now

The current model's coordination overhead grows with sprint count and pair count. Beads has matured enough that "PM uses beads, members use markdown" is now an avoidable inconsistency. Centralising on beads removes git noise, simplifies the PM skill, and makes cross-sprint observability free.