Orchestration

A revamp has four roles, and the separation is the point. The owner decides and clicks the steps only an owner can click. The orchestrator investigates, specifies, verifies, deploys and reports. One implementer builds. A read-only investigator may run beside it.

The loop

Re-anchor, recon, spec, owner answers, one implementer, the agent ships the branch and the draft pull request, verify, deploy on the go, report, record. The loop is deliberately boring. Every step that could be skipped is a step that has produced a wrong site before.

Concurrency

For a single repository, at most two agents run: one implementer and, beside it, read-only investigators. For a batch, one agent per repository, launched together, with the coordinator deploying one repository at a time. Never two agents on one repository, never two agents touching the same DNS zone or the same Cloudflare account at once, and one production pull request at a time per repository.

The brief

A brief is a spec, not a summary. It carries the role line, the spec path and the binding decisions with their timestamp, the repository facts, the numbered scope and an explicit not-in-scope list, the hard rules, the verification bar, the ship sequence, the progress files and the report format.

An agent that has to guess will guess wrong. The brief names the frozen paths, the forbidden reads, the secret rules and the exact commands that count as proof. The template is BRIEF-SITE-BUILDER.template.md.

Progress and handoff

Every agent keeps PROGRESS.md and HANDOFF.md in its worktree from the first edit and commits work in progress early. If the agent is killed by a limit or a crash, the on-disk state is the resume point. If a resume fails outright, a fresh agent gets the complete brief; the work is not re-derived from memory.

The handoff has seven parts: the read order, the state with what is confirmed, the remaining queue in order, what the owner still owes, the lessons of the arc, the verify commands for the next session, and the environment facts.

Tracking

Three files are updated at every boundary. The state file is the live state machine. The queue lists every item with its status: running, queued, finished or held. The handoff is written before every pause or compaction.

When the project uses the working-notes skill, its queue is the queue and its handoff is the handoff. The revamp does not duplicate tracking; it uses the project's own.

Lessons

A lesson qualifies when it is one of five things: a wrong premise that cost time, an agent slip that a rule now forbids, a trap of the machine or the vendor that bit once, a false positive or false negative, or a measurement that overturned an assumption.

It is written as the lesson first, then the evidence that makes it memorable: the number, the row, the error text. Then its origin: date, pull request, repository. Duplicates are merged by adding the new origin. The rule that follows goes into the normative file the same day; the lesson keeps the why, the normative file keeps the what.

Context discipline

The orchestrator does not run investigations beyond a re-anchor; it delegates them. It takes conclusions, not file dumps. A subagent's report is a summary, so the claims that matter are verified rather than relayed. When the context approaches its limit, the handoff is written first and the session compacts second.

What goes wrong, and the counter-measure