Workflow

The skill runs as a standalone clone or a migration phase selected explicitly by --handoff <website/handoff.json>. Migration mode reuses the migration-owned Wix site/project and binding intent. Standalone mode provisions one real Wix CLI Headless Astro project.

The implemented extraction/build scope is one home page. --scope must be home and --urls is not accepted. A later approved workflow must define resolution, evidence conflicts, and shared ownership for additional pages.

When a migration handoff allows only plan, complete project context plus frozen extraction/build planning and stop resumably. When it allows build, continue through implementation and verification on the migration-owned project.

Browser preflight

Before browser capture run:

Use --fix for supported remediation. In this repository, align to the documented NVM/Yarn toolchain first. For a sandboxed browser/network failure, request the required escalation and retry before it becomes a global blocker.

Stage order

1. Provision or verify the Wix project boundary when build mode requires it.
2. Resolve the requested URL to one public home page and destination / route.
3. Capture browser observations at desktop/tablet/mobile with normalization audit and persist typed, sanitized, hash-bound replay packets.
4. Run the independent semantic, structural, behavior, and visual detector ensemble; segment visible regions and assign ownership.
5. Plan recursive jobs and extract foundation, metadata, shared chrome, sections, and arbitrarily nested components deepest-first.
6. Classify and recover gaps within the bounded local budget.
7. Enforce the rendered-content boundary, then validate/harden hashes and freeze accepted or provisional specs. Content extraction must use browser-rendered text and exclude script, style, noscript, and template descendants. Preserve visible pre/code content with explicit provenance. If source-code contamination is still detected, omit only the affected strings, create an owned local gap, and continue unrelated units.
8. Derive the build plan and component-selection evidence from the manifest. If an approved registry item is selected, expose only its resolved binding and contractRef to the builder.
9. Build foundation, metadata, chrome, recursive children, then ordered sections.
10. Build and run unit/page browser QA; revise only affected owners.
11. Produce the final gap report and, when applicable, the migration receipt.

Resolution/extraction may create observations and specs, but never destination UI. Building consumes only frozen specs, generated selection evidence, and any selected component’s compact agent contract. It may not browse the source, scan the registry, read candidate/review material, or read raw observations. A missing builder fact returns through an owned extraction-gap request.

Page resolution

Normalize the input, remove fragments/query discovery noise, follow redirects with a read-only request, preserve an applicable locale home prefix, inspect canonical URL, and record requested/candidate/resolved/canonical URLs. Ambiguous home identity is a global blocker with an exact user action; do not guess a route or build the supplied non-home page as home.

Capture and safe probing

Capture the clean page after stable settling, controlled scrolling, lazy-content discovery, and consent/obstruction normalization. Retain raw and normalized evidence plus every normalization action.

Probe only public unauthenticated presentation state. Allow scroll, hover, focus, keyboard navigation, resize, bounded wait, tabs, disclosures, menus, and confirmed carousel controls. Block navigation, mutating requests, forms, auth, cart/checkout, purchase/booking, uploads, account/admin state, destructive actions, and unclassified clicks. Reset state between branches and retain an audit of blocked requests/actions.

Freeze and anti-stuck behavior

Every visible concern has one owner, explicit ignore, or owned gap. High-confidence detector results that meet calibrated precision may freeze automatically. Medium results become typed decisions for the orchestrating agent. Low/invalid/abstained results become gaps.

Local gaps never block unrelated work. Try at most two distinct targeted tactics. If the fact remains unavailable, freeze/build the reliable contract provisionally and propagate provisional status only through declared dependencies. The agent may make a conservative evidence-backed layout/semantic choice, but cannot invent copy, assets, links, business actions, or behavior.

Only unresolved home identity, page-wide unusable capture, corrupt artifact integrity, unisolatable safety failure, or inability to assemble/build/serve any viable shell stops the run globally.

Replay a retained immutable capture without reopening the source with:

Replay first verifies spec, dependency, manifest, and observation-packet hashes. A changed detector/projection or typed patch creates a new capture and report; the source capture remains untouched.

Build order and registry

Verify extraction/latest.json and its manifest before creating UI. The build ledger is keyed to manifest/spec hashes; a changed hash invalidates the affected downstream entries.

Install the foundation once, apply metadata, then build shared chrome, recursive child components, and top-level sections in dependency/source order. Use Astro for static UI and React only for useful islands. Preserve exact content/assets, layers, geometry, responsive behavior, accessibility, and observed end states.

Filter the local shadcn-format registry by contract, its approved hash-pinned capability manifest, framework/runtime, license, accessibility, responsive, SSR, RTL, reduced-motion, dependency, and human-approval requirements. Resolve only declared axes, slots, states, and compositions, and record selection/rejection evidence. An eligible selection is copied from its pinned local source only after its exact source hash is verified; exact dependency versions, required Astro integration configuration, and build/registry-installation.json record the installation. The builder consumes the resolved selection and only the selected item’s hash-pinned contract.md; registry internals and candidate material are not agent context. Use a bounded custom builder when no item qualifies and emit a source-neutral qa/registry-opportunities.json; never fetch a floating live-registry component.

Verification and completion

Verify each unit at its required viewports against frozen acceptance fields, then verify the assembled home page. qa/visual-qa.json contains unitAcceptance results for every frozen required criterion and pageAcceptance results for page checks; pending browser evidence is reported as pending, never silently passed. Findings return to their smallest owner. Do not use unrelated global CSS or another section to hide a gap.

Generate final-report.json and .md. For every unresolved/user-accepted gap state what could not be imported reliably and why, evidence/confidence/attempts, provisional output, assumptions/omissions, affected checks/dependencies, and choices to accept, retry/fix, provide material, replace, omit, or leave unresolved.

Record a post-assembly decision with:

No remaining gap plus complete browser verification may become done. Remaining local gaps become done_with_gaps; only a global blocker is blocked. In one-click mode do not pause before assembly for local gaps.