msd-core/docs/how-to/run-phases-autonomously.md

# How to run phases autonomously

Run all remaining phases — or a bounded range of them — unattended, so MSD moves through discuss → plan → execute for each phase without you driving every step.

For background on what the phase loop is doing during an autonomous run, see [The phase loop](../explanation/the-phase-loop.md).

---

## Prerequisites

- An active project with `.planning/ROADMAP.md` and `.planning/STATE.md`
- All phases you want to run must be in a state that autonomous mode can drive (pending or in-progress; not already complete)
- Any design decisions you care about should already be in `PROJECT.md` or captured via a prior `/msd-discuss-phase` — autonomous mode can surface grey areas interactively only when you use `--interactive`

---

## Run all remaining phases

```bash
/msd-autonomous
```

MSD reads `ROADMAP.md`, discovers every incomplete phase in numeric order, and runs discuss → plan → execute on each one. After all phases complete it automatically runs the milestone lifecycle: audit → complete → cleanup.

---

## Run a specific range of phases

Use `--from` and `--to` to bound the run. Both flags accept decimal phase numbers (e.g. `3.1`).

```bash
/msd-autonomous --from 3          # phases 3, 4, 5 … (skip already-done phases 1 and 2)
/msd-autonomous --to 5            # phases up to and including 5
/msd-autonomous --from 3 --to 5   # exactly phases 3, 4, and 5
```

When `--to` is reached the lifecycle step is skipped, because not all milestone phases are done. The completion banner tells you how to resume:

```text
Resume with: /msd-autonomous --from 6
```

---

## Run a single phase

To run exactly one phase without triggering the milestone lifecycle, use `--only N`:

```bash
/msd-autonomous --only 4
```

If the phase is already complete, autonomous mode exits immediately with a message rather than re-running it.

---

## Run with plan convergence

Use `--converge` when you want each phase to run the plan-review convergence loop before execution. Both `/msd-autonomous` and `/msd-progress --next --auto` support this flag.

```bash
# Needed only for /msd-progress --next --converge and standalone /msd-plan-review-convergence
# (/msd-autonomous --converge overrides the gate for its own run):
msd config-set workflow.plan_review_convergence true

# Via autonomous (multi-phase or single-phase):
/msd-autonomous --only 4 --converge
/msd-autonomous --from 3 --to 5 --converge --all --max-cycles 5

# Via progress --next --auto (step-chaining with convergence):
/msd-progress --next --auto --converge
/msd-progress --next --auto --converge --codex --max-cycles 4
```

`--cross-ai` is accepted as an alias for `--converge`. Reviewer flags supported by `/msd-plan-review-convergence` pass through unchanged, including `--codex`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.

An explicit `--converge` on `/msd-autonomous` overrides the gate for that run: convergence runs even when `workflow.plan_review_convergence` is `false`, and without the flag autonomous plans with `msd-plan-phase`. The gate still governs `/msd-progress --next --converge` and standalone `/msd-plan-review-convergence`, which stop with the enable command when it is not enabled.

---

## Run with interactive discuss

By default, autonomous mode answers discuss questions automatically using smart discuss (batch table proposals). If you want to answer design questions yourself while keeping plan and execute out of the main context:

```bash
/msd-autonomous --interactive
```

In interactive mode:
- `/msd-discuss-phase` runs inline and waits for your answers
- On runtimes that support nested background dispatch, planning and execution are dispatched as background agents so you can discuss the next phase while the current one builds; on Claude Code, planning and execution run inline (the next phase's discuss does not overlap)
- The main context stays lean — only discuss conversations accumulate (on runtimes with background dispatch; on Claude Code, inline plan/execute also accumulate)

---

## Run on a non-Claude runtime

To run autonomously on a runtime that does not support the `AskUserQuestion` tool (for example Codex CLI or Antigravity), add `--text`:

```bash
/msd-autonomous --text
/msd-autonomous --from 3 --text
```

All interactive prompts become plain numbered lists; type the choice number to respond. When combined with `--converge`, `--text` is also forwarded to the convergence loop via `CONVERGENCE_ARGS` so reviewer prompts inside plan-review convergence use the same plain-text mode.

---

## What safety gates still apply

Autonomous mode does not bypass MSD's quality pipeline. Each phase still:

- Runs the plan-checker before execution
- Reads `VERIFICATION.md` after execution and routes on the result
- Pauses and asks you what to do when verification status is `human_needed` or `gaps_found`
- Stops and presents options (fix and retry, skip phase, or stop) if any step fails

The only difference from manual execution is that `passed` verification advances automatically — you are not prompted between phases unless a decision is required.

The package legitimacy gate also remains active. If a plan includes a `checkpoint:human-verify` task for a suspicious package, the executor will stop and surface the checkpoint. Autonomous mode will not silently install flagged packages.

---

## When not to use autonomous mode

Do not use `/msd-autonomous` when:

- **Phases have unsettled design decisions.** If you have not run `/msd-discuss-phase` and your `PROJECT.md` does not capture your preferences, smart discuss will make autonomous choices you may not agree with. Run discuss interactively first, or use `--interactive`.

- **You need fine-grained control over a single phase.** For one phase, `/msd-execute-phase N` gives you step-by-step output and lets you react before continuing. Use `--only N` if you want the autonomous quality pipeline on a single phase but do not need step-by-step interaction.

- **The phase has novel or high-risk work.** Autonomous mode skips pauses unless it hits a blocker. On a phase where you expect surprises, stay in the loop with manual execution.

- **You are mid-phase with partial execution.** Autonomous mode picks up incomplete phases but it does not resume a partially-executed wave. Use `/msd-execute-phase N` to finish a phase that is already in progress.

If a run stops partway through, see [Debug a failed execution](debug-a-failed-execution.md) for how to diagnose what went wrong.

---

## Checking progress during a run

Autonomous mode prints a progress banner before each phase:

```text
 MSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
```

If you need to check where the run stands mid-session, open another terminal and run:

```bash
/msd-progress
```

---

## Resuming after a stop

If autonomous mode stops — whether you chose "Stop autonomous mode" from the blocker prompt, or the session was interrupted — resume from where it left off:

```bash
/msd-autonomous --from 4     # replace 4 with the first incomplete phase number
```

MSD skips already-complete phases automatically, so it is safe to re-run from an earlier phase number if you are not sure where the run stopped.

If a prior run recorded a `Deferred Verification` entry in `STATE.md`, later `/msd-autonomous` reruns skip that phase instead of re-entering the same deferral prompt. Resume deferred work with the exact command shown in the table:

```bash
/msd-verify-work 4          # for verification_deferred_human
/msd-plan-phase 6 --gaps   # for verification_deferred_gaps
```

---

## Related

- [Execute a phase](execute-a-phase.md)
- [Debug a failed execution](debug-a-failed-execution.md)
- [Commands](../COMMANDS.md)
- [Docs index](../README.md)