Factory
Open source / public proof
Inspect proof

Factory run map / public operating contract

The complete run—from ticket to verified draft PR.

Factory is not a swarm that runs until it feels finished. It is a bounded delivery system: one phase per fresh session, one executable gate after every phase, and a deliberate stop whenever the next decision belongs to you.

Run one phasescripts/run.sh <slug>

Execution contract

Fresh context. Persistent evidence.

scripts/run.sh <slug> runs exactly one phase, gates the phase that just closed, and stops whenever the next decision belongs to you.

One phase per fresh session

Compact state and run artifacts cross sessions

Every closed phase must pass its gate

Autonomous phaseNeeds youLeaf agentsExecutable gateTerminal state

Phase map / 0 → 6

The complete run, without the tiny boxes.

01Understand0 Intake / 0b Isolate / 1 Diagnose
  1. 0

    Intake

    gate.py --phase 0

    Classify a ticket, Sentry URL, or written request. Separate the reported symptom from evidence and turn the ask into criteria that can fail.

    Runs as
    Opus
    Speaks
    Triage verdict
    Closes when
    intake.md is written
  2. 0b

    Isolate

    gate.py --phase 0b

    Create a worktree and branch from a recorded baseline. If isolation is impossible, Factory asks before touching the active checkout.

    Runs as
    Sonnet
    Speaks
    Where the run writes
    Closes when
    Worktree + baseline SHA, or your consent to in-place
  3. 1

    Diagnosis

    gate.py --phase 1

    Reproduce the problem, trace the cause, and use at most two leaf-agent attempts. Light-depth runs move from a proven baseline directly to planning.

    Runs as
    Opus
    Speaks
    Root-cause synthesis
    Closes when
    diagnosis.md exists; skipped at light depth
02Decide2 Human plan / 2b Grill
  1. 2

    Human plan

    NEEDS-YOU

    Review the acceptance criteria, milestone demonstrations, release targets, and open decisions. Revise the plan until it is clear.

    Runs as
    You
    Speaks
    Plan + rediff
    Closes when
    The plan contains a Flag key line
  2. 2b

    Grill

    gate.py --phase 2b

    Facts go to one leaf agent per round. Decisions come back to you one question at a time. Three rounds are allowed before an honest blocked state.

    Runs as
    You + one leaf per round
    Speaks
    One summary per round
    Closes when
    No blocking question remains unanswered
03Build3 Agent plan / 4 Milestones
  1. 3

    Agent plan

    gate.py --phase 3

    Translate the human plan into bounded milestones. The equivalence review checks scope, then Factory seals both plans against unreviewed edits.

    Runs as
    Opus
    Speaks
    Gate decision
    Closes when
    SAME-SCOPE verdict and approved scope lock
  2. 4

    Milestones

    gate.py --phase 4

    Test and review one stage at a time. Defer optional ideas, demonstrate the result, and verify any authorized preview before continuing.

    Runs as
    Opus + leaves
    Speaks
    Per-milestone verdict
    Closes when
    Every milestone has a commit and checkpoint receipt
04Prove5 Proof / 6 Stop
  1. 5

    Proof

    gate.py --phase 5

    Scan full changed files and callers, rerun the acceptance matrix, and use independent reviewers to challenge invariants and the whole change.

    Runs as
    Opus + leaves
    Speaks
    Whole-change verdict
    Closes when
    Change scan + AC matrix + reviewer PASS
  2. 6

    Stop

    Terminal gate

    Report tokens, sessions, receipts, and the draft PR. The record permits delivered, delivered-with-gaps, blocked, or intentionally-unchanged.

    Runs as
    You
    Speaks
    Final report + PR URL
    Closes when
    Terminal state is set and the gate output is quoted

Human boundary

Factory knows when not to continue.

Isolation consent, scope revisions, preview publication, unanswered product questions, and the final claim remain explicit human boundaries.

01

No worktree?

Factory asks before working in place and records whose consent allowed it.

02

Open question?

The grill returns one decision at a time. Code waits until the blocking frontier is empty.

03

Budget exhausted?

The loop stops, names the cap, and reports what remains instead of quietly retrying.

04

New idea?

Factory records it for the handoff. The approved milestone continues unless an existing criterion requires a revised plan.

Bounded autonomy

What stops the loop.

Signalrun.sh does
Approved plan changesBlock the next milestone until human review and a new scope lock.
Preview awaits publicationPrint NEEDS-YOU; an unattended run cannot publish.
Next phase is 2, 2b, or 6Print NEEDS-YOU and exit 0. Run /factory resume <slug>, then rerun.
The closed phase gate says BLOCKEDPrint the reasons and exit 1. Nothing starts on an unpassed predecessor.
state.terminal is setExit 0. The run is over.
sessions_used reaches sessions_maxExit 0 and name the cap.
Two sessions change neither phase nor milestoneRerun the gate for the reasons, then exit 1.
leaves_used exceeds leaves_maxBlock at the gate. Only a blocked terminal may still close.

Terminal gate

The record permits one ending.

delivered

Every acceptance criterion is proven.

delivered-with-gaps

Named gaps were explicitly accepted by you.

blocked

A fact, decision, gate, or budget prevents correct delivery.

intentionally-unchanged

Evidence shows that changing code is not the right treatment.

Keep the map

Screen it. Share it. Print it.

The long edition keeps the whole system on one canvas. The A4 edition splits the flow only at a phase boundary and repeats the reading context.

Screen map / PDF Print edition / A4