# run-plan

audience: AI coding agents first. Imperative, BLUF.

Runs an authored plan document through the factory. Thin launcher — the factory owns the loop.

## Resolve the plan doc

First token of the invocation is the slug. Find `docs/plans/*-<SLUG>.md` under the repo.

- No match → STOP. List the available slugs (`ls docs/plans/*.md`). Do not launch.
- More than one match → STOP. Show them, ask which.

## Launch

From inside the repo root:

```bash
cd <repoRoot> && factory adw_plan_build_test_quality docs/plans/<file>.md
```

A path argument resolves to that file's **contents**, so the authored document IS the request. The run is autonomous and blocks in the foreground until it finishes.

Pick a shorter chain only when the user explicitly asks for less:

| Ask | Command |
|---|---|
| skip the verify/fix loop | `factory adw_plan_build docs/plans/<file>.md` |
| doc is already the plan, no re-planning | `factory adw_build docs/plans/<file>.md` |
| full chain incl. docs + review | `factory adw_sdlc docs/plans/<file>.md` |

## Watching it

The run streams to the `/factory` page in the overdeck web UI — timeline, per-phase agent attempts, prompts, gates, logs, diffs. Tell the user that is where they watch it. Terminal equivalent: `factory watch --follow`.

## When it needs a human

The run surfaces a decision instead of guessing. List them with `factory decisions`, answer with `factory answer`. Present the question to the user via `AskUserQuestion` — never answer on their behalf.

## Failure

Non-zero exit → HALT. Surface the factory's own stderr verbatim. NEVER reinterpret it, NEVER relaunch blindly. Re-launching starts a new run from the beginning; there is no resume.

## Do NOT

- Re-implement the phase loop in the conversation. Launch the factory; don't drive it turn by turn.
- Edit `modules/harness/factory/**` to make a run pass. That is the machinery judging the work.