Your first revamp

A revamp is deliberately front-loaded: the first two phases are read-only, and nothing is built until the owner has answered the spec questions. That is what keeps a presentation change from turning into a product change.

The six steps

1. Start the commandRun /repo-revamp:revamp my-old-project with a repository name or a local path. The skill loads and the state machine starts at INTAKE.
2. Read the reconThe agent investigates read-only and writes _revamp/<repo>/RECON.md: the facts, the feature and configuration inventory, the hosting options and the risks. No file in the repository is touched.
3. Answer the specThe agent writes SPEC.md with numbered questions and a recommendation for each. The owner answers in one line per question; the answers are appended as a binding USER DECISIONS block.
4. Let one agent buildOne implementer works in its own worktree on its own branch. It builds the generated site in docs/, runs the gate, commits in logical steps and opens a draft pull request. It never merges and never deploys.
5. Verify before relayingThe orchestrator re-anchors, runs the boundary diff and the gate on a clean worktree, serves the site locally, runs the browser matrix and looks at a page screenshot. An agent's claim is a hypothesis until then.
6. Deploy on the owner's goThe owner does the steps only an owner can do: authorise the host, create the DNS record, approve the certificate. Then the live URLs, the sitemap and the served commit are checked.

What the commands look like

The revamp command is the entry point. The other four commands inspect, verify, deploy and batch.

/repo-revamp:revamp my-old-project
/repo-revamp:revamp-status my-old-project
/repo-revamp:revamp-verify <url-or-dir>
/repo-revamp:revamp-deploy my-old-project github-pages
/repo-revamp:revamp-batch repo-one repo-two --dry-run

Each command takes the argument its own hint names: a repository for revamp, revamp-status and revamp-deploy; a URL or a local directory for revamp-verify; one or more repositories for revamp-batch.

The state file

At every phase boundary the skill writes _revamp/<repo>/STATE.md. It is the first file a resumed session reads, and it is what makes a crash survivable. The template ships with the plugin; this is the top of the file, exactly as it ships:

# STATE — <repo>

Updated at every phase boundary. A fresh session reads this first.

## Identity

- Repository: `<owner>/<repo>`
- Visibility: `<public | private>`
- Default branch: `<branch>` at `<sha>`
- Site branch: `<branch>` at `<sha>`
- Base SHA for the boundary diff: `<sha>`
- Host: `<GitHub Pages | Cloudflare Pages>`
- Subdomain: `<sub>.<zone>`
- Live URL: `<url>`
- Shape: `<product | docs | research>`
- Mode: `<presentation-only | rebuild>`

## Phase

- Current phase: `<0 INTAKE | 1 SPEC | 2 BUILD | 3 REVIEW | 4 DEPLOY | 5 SEO | 6 SHIP | 7 CLOSE>`
- Started: `<date>`
- Last updated: `<date time>`

The rest of the file is the gate table, the open questions for the owner, the agent table, the leftovers and the next action. The gate table is the part that matters most: each row names a check, its state and the evidence line, so a resumed session can see exactly which proof is missing.

The file is internal. It lives outside the repository, beside it, so nothing about the process is ever committed to the site.

When a phase gate fails

A failed gate is not a reason to move on. The playbook treats it as a stop: the phase stays open, the failure is recorded with its evidence line, and the fix happens at the source. If the gate cannot be run at all, that is also a stop, because an unrun check is not a pass.

The same rule applies to the agent's report. A claim that the site is deployed, that a screenshot was reviewed or that a link resolves is a hypothesis until the orchestrator runs the check. The report separates CONFIRMED, UNVERIFIED and NOT DONE, and it leads with the negative when the news is negative.

What you should see

The first phase ends with a recon file and no repository change. The second ends with a spec and a decisions block. The third ends with a branch, a generated docs/ directory, a green gate and a draft pull request. If any of those is missing, the phase is not finished, whatever the agent says.

The revamp-status command prints the phase, the gates, the open questions and the leftovers in five lines. Run it after every pause.

Where the depth is

Each phase has a reference file with the detail: 01-intake.md, 02-spec.md, 03-build.md and so on through 16-maintenance.md. Read the one for the phase you are in, not all of them at once.