autopilot

Autopilot -- Beads/BMAD Reconciliation Loop

Autopilot bridges two systems: Beads (issue tracker where bugs and tasks accumulate) and BMAD (sprint planning where work gets prioritized and executed). Issues arrive ad-hoc via Beads; autopilot folds them into the BMAD plan, executes the plan, and closes issues as work completes.

If no BMAD project exists, autopilot falls back to plain Beads mode — picking up ready tasks and implementing them directly.

Usage

/autopilot                       # Run with defaults (max 50 iterations)
/autopilot --max-iterations 10   # Limit iterations
/autopilot --skip-reconcile      # Skip orphan reconciliation

Phase 0: Pre-flight (runs once)

1. Detect mode: Check if _bmad-output/ exists.
   • BMAD mode: Full reconciliation + sprint execution
   • Plain Beads mode: Skip to Phase 2 PICKUP path (no reconciliation, just bd ready → implement → close)
2. Check sprint-status: Read _bmad-output/implementation-artifacts/sprint-status.yaml. If missing, run /bmad-bmm-sprint-planning to generate it.
3. Bootstrap issues: Run bd list --status=open and bd list --status=in_progress. If zero open issues but sprint-status has backlog stories, run /relay:bmad-import to create Beads issues from the plan.
4. Parse args: --max-iterations (default 50), --skip-reconcile (default false).

Phase 1: Reconcile orphans (each iteration, unless skipped)

Orphan issues are Beads issues without a bmad-story label — they exist in the tracker but aren't part of the sprint plan. This phase integrates them:

1. bd list --status=open — get all open issues
2. Read sprint-status.yaml — get tracked story keys
3. Filter orphans (no bmad-story label)
4. For each orphan (bd show <id>):
   • Fits existing epic — add as new story under that epic, update sprint-status.yaml, add labels (bmad-story, epic-N, story-N.M)
   • Warrants new epic — create epic section in epics.md, add to sprint-status.yaml, add labels
   • Quick fix (<30 min) — leave for PICKUP (no BMAD overhead needed)
5. If anything was added, re-run /bmad-bmm-sprint-planning to update priorities

Phase 2: Execute (Ralph Loop)

Invoke /ralph-loop with the per-iteration behavior:

/ralph-loop "<prompt>" --max-iterations <N> --completion-promise "AUTOPILOT_COMPLETE"

Each iteration:

1. Reconcile (if not skipped) — run Phase 1
2. Assess — /bmad-bmm-sprint-status for recommendation
3. Execute based on recommendation:

Recommendation	Action
dev-story	/bmad-bmm-dev-story → /verify → close matching Beads issue if verify passes, else iterate
create-story	/bmad-bmm-create-story, continue
code-review	/bmad-bmm-code-review, close issue if passes
retrospective	/bmad-bmm-retrospective, create follow-ups via /relay:issue
all done	Check bd ready for PICKUP work, else AUTOPILOT_COMPLETE

PICKUP path (no BMAD work remaining, but Beads has tasks): bd ready → claim → implement → /verify → close if passes, else iterate → next iteration.

Verify protocol (applies to dev-story and PICKUP):

1. /verify Phase 1+2 — regression tests + acceptance evals

2. If fail → fix implementation, re-run /verify (up to 3 retries before escalating)

3. /verify Phase 3 — write lock-down tests for new code

4. /verify --tests-only — final confirmation all tests pass

5. Only then close the Beads issue and move to next iteration

6. Exit when no BMAD work AND no bd ready tasks → emit AUTOPILOT_COMPLETE

Beads/BMAD label mapping

Label	Meaning
bmad-story	Tracked in BMAD sprint-status
epic-N	Belongs to epic N
story-N.M	Maps to sprint-status key N-M-slug-name

Error handling

• No recommendation → check bd ready for PICKUP
• BMAD skill fails → log, skip, continue to next iteration
• bd fails → report error, stop (Beads is the source of truth — can't continue without it)
• Malformed sprint-status.yaml → /bmad-bmm-sprint-planning to regenerate