repo-revamp repo-revamp v1.0.1

State machine

The phase state machine

Eight phases in order. A phase's exit gate must be green before the next one starts, and the state file records where the work stopped.

The state machine is the part of the playbook that keeps a revamp honest. It makes the work sequential, gives every phase a testable exit, and leaves a file behind that a fresh session can read. A revamp that starts with "let me just build the site" produces invented claims, a design nobody asked for, and a pull request that has to be reverted.

  1. INTAKERECON.md exists
  2. SPECUSER DECISIONS recorded
  3. BUILDgate green, draft PR open
  4. REVIEWV1–V16 green
  5. DEPLOYlive URLs answer
  6. SEOsitemap submitted
  7. SHIPmerged on the owner's go
  8. CLOSEtracker and handoff updated
The repo-revamp phase state machine Eight phases in order: INTAKE, SPEC, BUILD, REVIEW, DEPLOY, SEO, SHIP and CLOSE. Each phase box carries its exit gate underneath: RECON.md exists, USER DECISIONS recorded, gate green and draft PR open, V1 to V16 green, live URLs answer, sitemap submitted, merged on the owner's go, tracker and handoff updated. Arrows connect the phases in sequence. The phase state machine A phase's exit gate must be green before the next phase starts. INTAKE phase 0 read-only recon EXIT GATE RECON.md exists SPEC phase 1 numbered questions EXIT GATE USER DECISIONS recorded BUILD phase 2 one delegated agent EXIT GATE gate green, draft PR open REVIEW phase 3 the orchestrator verifies EXIT GATE V1–V16 green continues DEPLOY phase 4 coordinator and owner EXIT GATE live URLs answer SEO phase 5 sitemap and metadata EXIT GATE sitemap submitted SHIP phase 6 on the owner's go EXIT GATE merged on the owner's go CLOSE phase 7 record and hand off EXIT GATE tracker and handoff updated phase exit gate next phase

Scroll the diagram sideways to see all of it.

The eight phases and the exit gate that closes each one.

Text alternative: INTAKE closes when RECON.md exists; SPEC when the owner's USER DECISIONS are recorded; BUILD when the local gate is green and a draft pull request is open; REVIEW when the V1 to V16 checks are green; DEPLOY when the live URLs answer; SEO when the sitemap is submitted; SHIP when the merge happens on the owner's explicit go; CLOSE when the tracker and the handoff are updated.

Phase 0 — INTAKE

Read-only. The orchestrator establishes the repository facts: visibility, default branch, licence, tracked files, images, CI, hosting state and the existing documentation. It builds a feature inventory and a configuration inventory, each with evidence, and it decides the site shape: product, docs or research.

INTAKE ends with RECON.md and a proposed host and subdomain. Nothing in the repository changes. If the repository needs a product change to be presentable, that is recorded as a risk, not performed.

Phase 1 — SPEC

The spec is a set of numbered questions, each with a recommendation. The owner answers in one line per question, and the answers are appended to the spec as a binding USER DECISIONS (<time>) block. From that point the spec is the single source of truth: where the spec and a habit conflict, the spec wins.

The questions are the ones that change the work: host and domain, merge posture, screenshots, scope, indexing, call to action. An unanswered question is a stop, not a default.

Phase 2 — BUILD

One delegated agent, one worktree, one branch. The agent reads the spec and the build references, then works in the order the playbook sets: skeleton and builder first, then tokens and templates, then content, then screenshots, diagrams and SEO, then the README and the gates.

The agent commits in logical families with explicit paths, pushes the branch and opens a draft pull request. It never merges, never deploys and never touches DNS or repository settings. The phase ends when the gate is green on the branch and the draft pull request exists.

Phase 3 — REVIEW

The orchestrator verifies. An agent's "shipped" is a hypothesis: the orchestrator re-anchors the checkout, runs the boundary diff, runs the gate on a clean detached worktree, serves the site, sweeps every URL, runs the browser matrix, looks at a page screenshot and reads the claims ledger.

The output is a table of checks with one line of evidence each, and a report that separates CONFIRMED, UNVERIFIED and NOT DONE. A claim that could not be verified is not a pass.

Phase 4 — DEPLOY

The host is created, the custom domain is attached, the certificate is approved and HTTPS is enforced only after the certificate exists. The owner does the steps that only an owner can do; the coordinator does the rest and records every call.

The phase ends when the live root answers over HTTPS, HTTP redirects to it, every sitemap URL returns 200, the social image is 1200 by 630, and the served commit equals the expected head.

Phase 5 — SEO

The sitemap is submitted to Search Console, the repository description and homepage are set, and topics are added. A new site can take days to be crawled; the submission is recorded with the tool's response, never claimed from memory.

Phase 6 — SHIP

Merge only on the owner's explicit go. The site branch is retained, the deployment is repointed if it served a different branch, and the rebuild is verified at the served commit. A merge that happened too early is reverted with a new commit, never a force push.

Phase 7 — CLOSE

The tracker gets a row, the lessons get dated lines with their evidence, the handoff is written and the owner has the report. The state file is updated to match reality. The next revamp starts from a clean, recorded position.

The state file

_revamp/<repo>/STATE.md holds the identity, the phase, the gate table, the open questions, the agents, the leftovers and the next action. It is written at every boundary and read first by any resumed session. The template is in the reference list and the quick start shows it in full.

Why the order matters

INTAKE and SPEC are cheap and prevent the expensive mistakes. BUILD is where the time goes, and it is delegated so the orchestrator keeps the context to verify it. REVIEW, DEPLOY and SEO are checkpoints that cannot be skipped, because each one proves a different thing: that the output is what was promised, that the host serves it, and that search engines can find it.

The phases overlap in only one narrow way: the draft pull request is opened as soon as the code is frozen, so CI runs while the proofs are finished. Everything else is sequential.

The gatesOrchestration