Refactoring a Live Site with Coding Agents

Requires the bascik skill for component rules and the bascik-migrate skill for the framework-to-Bascik procedure; this skill runs that procedure route by route until every route matches production except documented, verified defect corrections. It is opt-in, so projects created with npm create bascik@rc do not include it. Install it with npx skills add bascikdev/bascik --skill bascik-refactor.

Procedure

Read node <skills-dir>/bascik/scripts/read-doc.mjs /how-to/agent-migration first, then references/production-parity.md for the full method.

1. Record the inventories in docs/migration/ and generate the breakpoint matrix with scripts/breakpoint-matrix.mjs. No target exists yet, so run the inventory scripts on production alone, without --target: scripts/interaction-crawl.mjs --discover drafts interactions.json (review it and remove "draft"), scripts/presence-by-route.mjs and scripts/state-capture.mjs record layers and open states, and scripts/capture-baselines.mjs --states records the production baselines, ids <route>@<caseId>, in artifacts/baselines/. Copy scripts/llms-txt.mjs and scripts/worker-response-policy.mjs into the project's scripts/ before the config or Worker uses them. Compare and audit a production build (bascik --build, then bascik --server on port 8080), never the dev server.
2. Fill in references/templates/execution-contract.md and the references/templates/prompt-pack-index.md; every prompt reads the contract first.
3. Migrate route by route with references/templates/one-route.md and repair with references/templates/one-failure.md. Run scripts/production-defects.mjs on production first, then scripts/run-checks.mjs for every parity check in one command. Iterate with --cases <ids> (a phone, a tablet, a desktop and the route's breakpoint edges) and --only <checks>; production's side comes from the production cache, so only the target is loaded. Those runs print PARTIAL and decide nothing: a run that leaves out cases or checks cannot be signed. The gate is the full docs/migration/breakpoints.json matrix with every check, and "done" is decided only there; pass --refresh-prod at the start of every check stage and review round, and whenever production changed (sign-off refuses cached production more than a day old).
4. Review each route side by side: an agent with image input follows references/templates/visual-review.md, then a person reviews the scripts/review-page.mjs page and signs docs/migration/review/<route>.json.
5. Run the queue with references/templates/driver-agent.md: PASS needs every check, a visual review with no differences and a human pass verdict (review-page.mjs --verify). No findings is not a PASS on its own. Escalate framework issues in its reproducible format.
6. Log every intentional difference in references/templates/decisions-ledger.md; a row that changes pixels also gets an accepted.json entry for compare-route.mjs --accepted. A PD- row from production-defects.mjs that a reviewer finds is not a defect gets an accepted.json entry with "defect": ["PD-xxxxxx"] and a ledger row of the entry's id instead of a design change, so it is neither a fix target nor a copied-defect. --reject PD-xxxxxx is for one iteration run only: review-page.mjs refuses a gate run that used it. Elements with the same text and kind share a PD- id, so check every element a rejection covers.

Components and TypeScript

Fix defects, not just parity differences