# Factory skip-plan entry — design

audience: AI coding agents first. slug: `factory-skip-plan`
source request: owner 2026-08-15, verbatim: "I need the factory to be able to 'skip' the plan phase, if i want to brainstorm with you for example and you make the spec and plan, i dont want to run another expensive planner agent. i want to just insert the plans into the factory and run straight from the build part."

## Contract

`factory adw_plan_build_test_quality <path> --skip-plan` (flag threads through the `factory` wrapper → adw argparse): when set, the `plan` phase runs NO planner agent. All other phases (request capture, build, verify/test/fix loops, commit) are unchanged.

Rules:
- `--skip-plan` is VALID only when the prompt argument is a path to an existing, non-empty markdown file under a `docs/plans/` or `docs/specs/` directory (any repo). Anything else — freeform prompt, missing file, non-plan path — refuses at startup with one-line guidance: a bare sentence still needs the planner. Never a silent fallback to planning.
- The build phase currently receives `previous=plan` where `plan` is the planner call's `PlanOutput` envelope (see `adw_plan_build_test_quality.py` phase "plan" → `hitl.resolve_plan_decisions(...)`, consumed by build's `AgentCall(..., previous=plan)`). The skip path synthesizes that SAME envelope deterministically — read `PlanOutput` in `adw_modules/data_types.py` and fill every field build/gates consume: the authored doc's content is the plan body; artifacts list = the doc path copied into `context_handoff/` (satisfying `gates.artifacts_exist` + `gates.files_non_empty`); summary = the doc's H1/outcome line. No model call anywhere in the skip path.
- The phase still RUNS as a phase (kind: code, name "plan", description noting "authored plan accepted, planner skipped") so tracing/observability (sssf.db, /factory page) shows an honest phase row, not a gap.
- hitl plan-decision resolution: read what `hitl.resolve_plan_decisions` does with a PlanOutput; an authored doc carries no pending decisions — the skip path must produce the already-resolved shape (no interactive gate can fire from a doc).
- Scope: implement on `adw_plan_build_test_quality` ONLY (the composition the owner uses). Other adw_plan_* compositions inherit later if wanted — note in the plan doc, do not build.

## Testing

Factory suite green (`python3 -m pytest modules/harness/factory/tests/ -q`, 246 baseline; NEVER weaken a gate). New tests, hermetic in the existing test style: (1) skip with a valid plan doc → planner agent never invoked (assert zero planner calls), build receives a valid PlanOutput, run proceeds; (2) skip with freeform prompt → startup refusal with guidance, exit nonzero; (3) skip with missing/empty path → same refusal; (4) trace shows the "plan" phase row with the skip description.

## Acceptance (owner-visible)

One real run: `factory adw_plan_build_test_quality docs/plans/<real-doc>.md --skip-plan` goes green end-to-end with zero planner tokens spent (trace shows no planner agent call), visible on /factory.