Plan Compass

Plan Compass extends staged workflow with the compass choreography preset: discover → design → review → execute → verify. Use it when a task is large enough that you want BMO to slow down, turn the approach into an inspectable plan, wait for approval before changing files, and carry the same plan through verification.

The preset is useful for multi-step refactors, release work, incident follow-up, and other tasks where “just start editing” is too loose. It keeps plan intake, plan quality, durable promotion, milestones, and verification targets on one operator path.

[choreography]
preset = "compass"

[options.staged_workflow]
enabled = true
require_approval_before_execute = true

[options.quality_gates.gates.plan]
enabled = true
mode = "send_back"

The TUI surfaces the selected horizon and checklist milestones in the plan content, then keeps the run-approval cockpit available until execution is approved.

Operator entry

• TUI slash: /compass, /compass ingest, /compass promote, /compass mission
• CLI: bmo plan ingest, bmo plan promote, bmo plan mission, bmo plan activate

What Plan Compass coordinates

• Plan intake: /compass ingest and bmo plan ingest normalize an existing Markdown plan into compass metadata so the current session can review, approve, and execute it.
• Plan strength: when the plan quality gate runs in send_back mode, weak plans are returned for more design work instead of moving straight to file edits.
• Durable promotion: /compass promote and bmo plan promote can promote the session plan into a durable artifact. Exec-horizon promotion can also bind long-running work to maintainer artifact outside this repository, with optional workstream binding.
• Approval-time activation: durable plans can opt in to activation on approval with compass.activate_on_approve or options.plan_compass.auto_activate_on_durable_approve.
• Verification carry-through: plans can include verification_targets; BMO runs them when the workflow reaches the verify state.
• Milestone progress: exec-horizon plans, or plans with exec_workstream_plan, show Milestones N/M done in the plan panel and /compass status when the plan body uses - [ ] / - [x] checklist lines.
• Milestone delegation: /compass milestones spawn [--all] delegates unchecked milestones to local task subagents after /approve. Set spawn_milestones_on_approve = "next" or "all" in [options.plan_compass] to opt in automatically. The milestone_spawns metadata records whether each child finishes as done, failed, or cancelled; plan body checkboxes remain manual. Each new binding retains an input_digest for the ordered milestone titles, execution-plan reference, and verification targets. If those inputs change while a child is active, BMO refuses further milestone dispatch until the active children are reconciled. Older active bindings without a digest require the same reconciliation; checkbox progress and unrelated prose do not change the retained inputs. BMO saves a pending work_id and unique attempt_id before preparing a child, then saves the child identity before starting execution. Competing controllers compare the current stored plan atomically. A failed or interrupted launch retains its pending attempt; later commands inspect that binding rather than launch another worker for the same milestone. A definite preparation refusal records launch_disposition: not_started and leaves the unchecked work eligible for a new attempt. Generic failures do not establish that execution was absent. Plan writes and clearing refuse to erase active attempts. Completed attempts remain in the plan metadata when a later attempt is created. For attempts carrying both work and attempt IDs, BMO records a write-once worker_result after collection: a durable proposal_id, an inspected no_changes result, retained patchless evidence, or a child failure. The default read-only task child has no worktree; its evidence result references the actual persisted terminal assistant message with result_message_id and result_content_sha256. BMO checks that output against its exact child run and attempt. This records candidate output; it does not assert that the shared workspace was unchanged. Proposal provenance names the exact persisted child run and attempt. Generic child terminal notifications cannot settle that binding before collection. An unavailable result or failed acknowledgment retains the active attempt. BMO persists the collection receipt in the existing child run ledger before acknowledging it in the plan. /compass milestones spawn recovers that exact receipt, including evidence, clean and failed results, and returns without launching another child when recovery succeeds. It can also recover a committed proposal whose receipt acknowledgment was lost; it does not reconstruct a missing result from process success. Missing or changed retained output remains unavailable. A child status or collected proposal does not complete the checkbox or verify the integrated repository. Review and apply proposals through Patch Proposals.
• Submit hint: when staged workflow is on but the session is not using the compass preset, complex free-text tasks may show an advisory /compass nudge instead of changing presets automatically.

Copy-paste preset blocks live in docs/topics/config/operating-packs.md in the BMO repository.

Review a delegated proposal

For a completed attempt with a recorded proposal result, request a shadow review using the parent session, work, attempt, and result-run identities retained in the plan metadata:

bmo workstream proposals review-milestone <parent-session-id> <work-id> <attempt-id> <result-agent-run-id>

BMO reloads the exact worker receipt and checks the proposal’s child-run and attempt provenance before recording the review decision. Repeating the command replays that decision. Missing receipts or conflicting provenance fail before a review is recorded; stale source, unreadable diffs, missing validation, and disabled policy remain visible in the decision.

This command always uses shadow review, including when live proposal actions are enabled. It does not invoke a quality judge or accept, materialize, or apply the proposal. Continue through Patch Proposals for those operator actions; an applied proposal still requires verification of the integrated repository.