Common Workflows

These are the most common ways developers use BMO in day-to-day work. Treat them as starting points, not scripts. If you want the conceptual map first, see Workflow map. If you are turning a prompt into a reusable instruction or static review artifact, use the patterns in Prompt Engineering Patterns instead of expanding these examples inline.

Understand a codebase

What does this project do?
Where is the main entry point?
Explain the folder structure and the role of each directory.
What are the most important files I should know about?

Start a new project? Run /init first. BMO will analyze the codebase and write the configured project context file (AGENTS.md by default), which improves new sessions in that project.

Add a feature

Add a rate-limiter to the API endpoint in internal/api/handler.go.
The limit should be 100 requests per minute per IP.
Use the existing middleware pattern in internal/middleware/.

BMO will read the relevant files, propose edits, and wait for your confirmation before writing.

Fix a bug

There's a nil pointer panic in the auth flow when a token is missing.
The stack trace is: [paste trace here]

Or point it at a test:

The test TestUserLogin is failing. Fix the root cause.

If the run gets complicated or you want to inspect exactly where it went off track, open Agent Debugger with /debugger after the run completes and walk the recorded timeline before retrying.

Plan before a large change

Refactor the database layer to use a repository pattern.
Keep the existing SQL queries but wrap them in a Repository interface.

Use Staged Workflow for large refactors, risky multi-file work, or any change where reviewing intent before edits matters.

Make deliverables artifact-backed

Use ROI when the work needs a durable record beyond the chat transcript: a mission, a run, evidence, and an inspectable status trail. It is a good fit for repeatable delivery work, stakeholder-facing artifacts, review remediation, PDF/book generation, or any task where “done” should mean “there is a named artifact and validation evidence.”

For quick exploration or a small edit, normal chat is enough. For multi-step implementation inside BMO, use staged workflow or a workstream. Add ROI when the outcome should be reusable, auditable, or easy to resume across sessions:

Use ROI for this work.
Create or select a mission for the deliverable, start a run, attach the plan,
diff, test output, and generated artifact paths as evidence, then report final
status with the artifact locations and validation result.

When the ROI MCP server is connected, use the ROI mission, run, evidence, and status tools for that loop. When it is not connected, keep the same shape in BMO-native artifacts: a plan or workstream id, links to changed files, test output, generated artifact paths, and a final status note that can be attached to the ROI record.

If the task already has a BMO workstream, bind the ROI mission to it so the workstream remains the local execution spine while ROI carries the durable delivery record:

bmo workstream set-roi-mission <workstream-id> <mission-id>

For the concept map and operator surfaces, see ROI and bounded self-direction.

Write tests

Write table-driven unit tests for all exported functions in internal/parser/.
Use the existing test style in internal/parser/parser_test.go as a guide.

Review code

Switch to review mode first:

/mode review

Then ask:

Review my changes since the last commit. Look for bugs, missing error handling, and off-by-one errors.

If you want BMO in a safer audit posture before the request starts, switch to a review-oriented mode first or use staged workflow for plan-first review.

For higher-signal reviews, prefer a prompt that states scope, evidence, output order, and certainty:

Review the current unstaged and untracked changes for user-visible regressions.
List findings first, ordered by severity.
For each finding, include file path, evidence, impact, and a concrete fix direction.
Separate confirmed defects from plausible risks.
Do not include style-only comments unless they affect correctness or operator trust.

Switch workflow modes quickly

Use session modes when you want a lighter-weight tool or prompt profile without editing config files:

/mode review
/mode debug
/mode sre

• review is a good fit for auditing diffs and reading code safely.
• debug keeps execution-oriented tools close at hand.
• sre is tuned for incident response, infra-as-code, CI/CD, and production triage.
• Press shift+tab to cycle modes from the keyboard.

For the full mode reference, see Session Modes.

Use multiple agents

Split this task into three parallel lanes:
1. add tests
2. fix the API handler
3. review the final diff

Use this when the work can be decomposed safely. Start with Multi-Agent Workflows for BMO-native parallelism, or Agent Mesh if you want remote peers selected by capability.

Create a commit

Commit my changes with a descriptive message following the conventional commits format.

Explain code

Explain what the Choreography engine does in internal/choreography/engine.go.
Focus on the state transition logic.

Search for something

Where is the config loaded?
What calls the Evaluate function in the policy package?
Find all places where we write to the database.

These prompts work well because BMO has grep, glob, and LSP reference tools available.

Run BMO outside the TUI

Use the CLI when you want the same agent surfaces in scripts, CI, or background automation:

# One-off task
bmo run "Summarize the recent auth changes"

# Headless prompt with a local-only HTTP server enabled
bmo autopilot --auto-approve --server --addr 127.0.0.1:9090 --allow-no-auth "Fix the flaky tests"

# Long-lived local-only HTTP server + schedule daemon
bmo up --addr 127.0.0.1:8080 --allow-no-auth

# Stop the process started by `bmo up` or `bmo autopilot --server-only`
bmo autopilot down

For recurring jobs, add schedules with bmo schedule add ... and inspect them with bmo schedule list or bmo schedule runs <id>. See Automation & Headless for the full workflow.

Keep background work bounded

If you need BMO to do stewardship work when you are not actively chatting with it, use explicit automation surfaces instead of hoping the foreground session will “just keep going”:

• Automation & Headless for one-shot, recipe, or daemon-backed runs
• Compaction for idle-gated background cleanup
• Workflow map for how those branches fit into the wider system