Part VI · Running development

The execution workbench¶

The run cockpit is where a feature gets built — and where you can watch it happen. Execution is not a fire-and-forget job: it is a live workspace showing an agent engineering team at work, with streaming reasoning, per-agent costs, diffs, and direct lines to every agent. And a run is not a precious one-shot: runs are versioned, comparable, and disposable — you can start fresh, race attempts against each other, keep the winner, and discard the rest.

Dispatching a run¶

From the feature's launch pad you dispatch execution with an optional guidance note (up to 2,000 characters) — steering context the dev lead reads before touching the plan: "prefer the existing queue abstraction", "the migration must be reversible". Guidance is how you tilt a run without editing the approved plan.

Two dispatch modes exist: fresh (a new run version, clean slate) and follow-up (continue on the merged work of the current run). Dispatch is validated up front — broken preconditions fail loudly at the button, not twenty minutes into a run.

Once dispatched, the run detaches from your browser. A supervisor owns it server-side; closing the tab changes nothing. Reopen the cockpit and the live stream reattaches to the run in progress.

Who builds: the dev-lead-rooted team¶

Every run is rooted in one orchestrating agent — the dev lead. It reads the approved plan artifact, then drives each task through a fixed per-task discipline:

1. An isolated worktree per task. Each task gets its own git worktree — parallel tasks never trample each other's files, and a failed task's mess is discarded with its worktree.
2. QA first. A QA agent writes the tests for the task's acceptance criteria before implementation, and those tests are then locked (see below).
3. An engineer, sized to the task. Engineers come in four seniority tiers — junior, mid, senior, expert — configurations of the single engineer behaviour that decide which model a task deserves. The dev lead routes by task complexity (simple→junior … critical→expert), and a per-task override always wins; the full tier model lives in Agent rosters. The WHY is cost discipline: an expert-tier model on a config rename is money burned; a junior model on a concurrency bug is time burned.
4. A reviewer. Every task's work is reviewed by a separate reviewer agent before it can merge.

The QA lock¶

The tests QA committed are locked for the rest of the task. If the engineer deletes a locked test, it is restored byte-identical — silently un-failing a test by removing it is structurally impossible. If the engineer modifies one, the change is not reverted (sometimes a test is legitimately wrong) but the exact diff is captured and put in front of the reviewer. The green checkmark stays meaningful: either the original tests pass, or a human-reviewable record explains what changed.

Fix loops, capped¶

When review or tests fail, the dev lead runs a fix loop — but at most two attempts at a given tier, then forced escalation to a more senior tier. The cap exists because the third attempt by the same model on the same problem is rarely different from the second; escalation converts a stall into a bigger hammer. And when a finding collides with a frozen acceptance criterion — the code can't satisfy the spec as written — the run does not quietly reinterpret the spec: it forks a decision record and puts the conflict on the record for a human.

Watching: the live cockpit¶

The cockpit's left side is the conversation spine — the dev lead's live narrative of the run, including streaming reasoning as agents think. The right side is a tabbed workspace:

• Roster — one card per agent in the run: role, lifecycle state (working, done, failed, discarded), current task, and live cost per agent. Costs are real, not estimated: durable per-agent spend is read from the orchestration layer's own cost ledger and joined with the live in-flight delta, so the number on the card is what the run has actually consumed.
• Files — the run's diff surface: what has changed on the branch, as it changes.
• Runs — the scoreboard (below).

The header carries the single global run-state chip and the vitals strip. Failures are loud by design: a failed agent gets an alert-level banner, a failed run persists its failed status — nothing in the cockpit fades to grey and hopes you won't ask.

Talking to agents mid-run¶

Select any roster card and the composer at the bottom targets that agent — not a generic mailbox. Ask the dev lead why it re-ordered tasks; ask the engineer on task 3 what it makes of an error; the reply arrives in that agent's thread. Terminal agents (done, failed, discarded) are read-only — their history remains inspectable, but you cannot message an agent that no longer exists.

Stop halts the run from the header. Stopping is deliberately the cheapest action — discarding or restarting cost strictly more clicks, so the reflex action under uncertainty is the reversible one.

Merging: gates only humans can pass¶

Task work merges through a queue with two hard gates:

• Reviewer verdict. A task merges only with a passing review verdict. A blocked or needs-context verdict stops the queue for that task.
• Human review gates. Plan steps can be marked review_gate: "human" — for those, the merge parks until a person explicitly approves the task in the cockpit. This is structural, not etiquette: no agent can approve a human-gated step, whatever it says in a prompt.

Shipping: the whole-branch review and the E-SHIP gate¶

When the task DAG drains, one more agent pass runs — the whole-branch ship review: the entire branch diff against the feature's acceptance criteria, producing a verdict (green/red), per-AC pass/fail, findings, and the diff stat. Two design choices matter:

• Fail-safe red. If the ship review itself errors, the verdict is red. A broken reviewer never defaults to "ship it".
• No auto-fix loop. A red verdict does not trigger another agent round — deliberately. At the ship boundary, the next move (fix, re-run, re-scope, override) is a human decision, and an automatic loop here would launder that decision into the machine.

A green verdict moves the ship gate to gate_pending, unlocking the ship PR. Alongside sits the E-SHIP preview: a deployed preview environment of the branch, so you UAT the actual behaviour in a browser before anything reaches your mainline. The ship gate card tracks the checklist — review verdict, UAT, PR — in one place.

Runs are comparable and disposable¶

The run model is what makes the cockpit safe to experiment in:

• Versioned history. Every run of a feature is numbered (v1, v2, …) with an immutable record — status, cost, tasks done, findings — and its own branch (foundry/feat-<id>-<slug>[-vN]), so run artifacts never collide.
• Fresh runs are truly fresh. Starting a fresh run snapshots the outgoing run, wipes the working state, and mints v(N+1) in a single transaction. The guarantee: a new run can never accidentally inherit a previous run's "done" bookkeeping and skip work it never did.
• Discard is cheap and safe. Discarding stops the run, frees its worktrees and processes, and marks it discarded — but the branch stays on the remote, read-only. Discard throws away the attempt, never the evidence.
• The scoreboard. The Runs tab lists every run with its cost, task, and finding totals, plus the branch topology. Run the same plan twice — different guidance, different tier emphasis — compare the scoreboard, and select the winner; the selected run is the one the feature ships from.

That is the intended posture toward agent-built software: don't gamble on one attempt being right — make attempts cheap, comparable, and disposable, and keep the judgment human.

Where the record lands¶

Everything consequential from a run outlives it: decisions and findings land in the product registers, run history stays on the feature, branches stay on the remote, and the ship review artifact documents exactly what was verified before you merged.