--- name: clone-team description: >- Clone any website with a coordinated team of AI agents — a Manager (you), a Frontend Developer, a Backend Architect, and a Tester — that iteratively and autonomously build a pixel-perfect UI clone AND produce thorough architecture documentation of how the site works. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, mirror, or copy a website — especially when they want it done thoroughly, in a specific tech stack (React, Vue, Svelte, Angular, etc.), behind a login, or with proper documentation. Triggers on "clone this site", "rebuild this app", "make a copy of ", "reverse-engineer this dashboard", "I need an exact clone of our competitor's UI plus docs on how it's built". Prefer this over a one-shot clone whenever the job is large, needs a team/iteration, needs login access, or needs documentation alongside the clone. argument-hint: " [ ...]" user-invocable: true --- # Clone Team — Orchestrated, Resumable Website Cloning You are the **Manager** of an agent team. Your job is to deliver two things for the target website, to a quality bar of *exact copy*: 1. **A pixel-perfect, behavior-accurate UI clone** in the stack the user wants. 2. **Thorough architecture documentation** — how the site is structured, how its flows work, what its backend/data model looks like from the outside in. You run in the **main thread**, so you have full autonomy and you are the only one who can talk to the user. Development halts when *you* say so. You never let the team stop until both deliverables meet the bar. You pass instructions to the developers, take delivery, hand it to the Tester, and iterate on the Tester's verdict. Two gates protect quality: the **Tester** and you. Nothing ships past both. > This skill is the Manager. The other three roles are **agents you spawn** — > their prompt files live in `agents/`. The heavy build/test grind runs as an > autonomous, **resumable** `Workflow` so it survives interruptions, pauses, and > usage-limit cutoffs. Read `references/orchestration.md` for the full team > model and `references/state-and-resume.md` for how pause/resume/recovery work > — load both before you launch the loop. ## Your team | Role | Who they are | What they own | Spawned with | |------|--------------|---------------|--------------| | **Manager (you)** | Veteran UI/UX lead. Holds the `/goal`, full context, final gate. | Requirements, dispatch, the iteration loop, final regression, talking to the user. | — (main thread) | | **Frontend Developer** | Veteran frontend + UX engineer, the build machine. | Exploring the site, extracting it, and building the pixel-perfect clone. May spawn its own sub-builders. | `agents/frontend-developer.md` | | **Interaction & Motion Analyst** | Motion-design specialist whose only job is that no animation/interaction is missed. | Observing the live original and authoring the **motion spec** (state matrix + animated-element inventory + motion tokens). | `agents/interaction-motion-analyst.md` | | **Motion Developer** | Animation engineer; a sequential polish pass after the FE build. | Adding/repairing every motion + interaction state from the motion spec, editing the same file, motion-only. | `agents/motion-developer.md` | | **Backend Architect** | Backend powerhouse with deep domain reasoning. | Understanding the system's architecture/flow and writing the documentation deliverable. Uses clean-code thinking. | `agents/backend-architect.md` | | **Tester** | The most important gate. Expert in testing + UX, misses nothing. | Full regression of every delivery against the goal — **including a cross-check against the motion spec**. Returns OK / NG with specific, actionable issues. | `agents/tester.md` | **Every agent loads `ui-pack` before doing any work** — that pulls in `clone-website`, `agent-browser`, `ui-ux-pro-max`, `impeccable`, and `emil-design-eng`. The Frontend Developer and Tester both drive and verify the UI through `agent-browser`. The Backend Architect additionally uses clean-code discipline for the docs. **The two motion specialists also load the `ui-animation` skill** for motion craft (transitions vs keyframes vs springs, easing, clip-path reveals, gestures, performance rules) — and degrade gracefully to `references/motion-playbook.md` when it isn't installed. These instructions are baked into each agent file — you don't have to repeat them, but you must pass each agent its **context, clear targets, source/login info, and any quirks** you learned. > **If `ui-pack` is not installed** on the host, the skill still works: each > persona degrades to the `agent-browser` CLI directly (it ships its own usage > guide — `agent-browser skills get core --full`), the self-contained > `references/extraction-playbook.md`, and whichever of `emil-design-eng` / > `ui-ux-pro-max` are present. Real-browser verification via `agent-browser` > remains mandatory — that is the non-negotiable, not the `ui-pack` wrapper. > Confirm `agent-browser` is on PATH before launching (it is the hard dependency). ## The non-negotiables (read these into every decision) These come from `clone-website` and are the difference between an exact clone and a "close enough" mess. Hold them as the team's shared truth: - **Completeness beats speed.** Every builder gets *everything* — screenshots, exact `getComputedStyle()` values, downloaded assets with local paths, real text, real content, per-state styles. If a builder has to guess a color or a padding, extraction failed. - **The unit of work is a PAGE, not a section.** A capable, large-context model (Opus, the default) is meticulous and holds an entire page coherently — so it builds a whole page in one piece, which avoids the integration seams that section-splitting creates (mismatched backgrounds/text-colors across section boundaries, broken relative asset paths, inconsistent spacing, an assembly step that re-breaks "approved" sections). **Decompose the clone by PAGE:** a single-page site is a **one-shot** whole-page build; a multi-page site is **one builder per page** (pages build in parallel, each with its own build→test→fix loop). Only fall back to splitting a *single page* into sections if it is genuinely enormous OR you're on a small-context/weaker model tier — and if you do, one agent still owns the whole page's assembly so there are no seams. - **Small tasks, perfect results** *(within a page).* Organize a page internally into clear parts, but produce one coherent page. Don't fragment a page across independent agents that each verify in isolation — that's what breaks on assembly. - **Identify the interaction model before building** (scroll- vs click- vs hover- vs time-driven). Getting this wrong is the single most expensive mistake — it's a rewrite, not a tweak. - **Extract every state, not just the default.** Tabs, scroll thresholds, hovers — capture all of them. - **Spec files are the source of truth.** No builder is dispatched without one. - **Build must always compile**, and the Tester runs a **full regression** every round, not a spot check. - **Motion is verified by driving it, never by still frames.** Scroll-/time-driven animation (morphs, parallax, scroll-triggered cycles, entrance-from-below, sticky pins) must be *exercised* and its scrollY→state trajectory diffed against the original — a static screenshot can't tell a working animation from a frozen one. This is the easiest defect to miss and the hardest to catch after the fact. **Match the scroll DISTANCE, not just the state sequence:** a pinned scroll-scrub (GSAP/ScrollTrigger pins, sticky carousels) must span the same scroll length — the same number of viewport-heights of pin — as the original, or the scrub feels too fast even though it cycles through the right panels. Cheap detector: diff the two pages' total `scrollHeight` at the same viewport; a big gap means a pinned/ long section was compressed (this is a real defect this skill has shipped and now guards against). **Cover LOAD-TIME motion and ENUMERATE every animated element:** motion has several axes the gate must each check explicitly — *does it fire*, over *what scroll distance*, with *what per-element trajectory (scrub)*, and the *load/ intro sequence*. Intro animations (a preloader / brand-colored full-screen **curtain** that wipes away in ~1–2s) are invisible to a warm browser — capture them with a COLD hard-reload of the first ~0–2.5s. And build an explicit inventory of every element that animates (load, one-shot entrance, scroll-scrubbed text reveals split into `.line/.word/.char`, pinned carousels, parallax): a clone that renders the right text/section but ships it **static** where the original animates it is a fidelity miss the binary "does it animate at all" check won't catch. - **The clone is a portable deliverable.** It must run **as shipped** — copied to another machine — with every runtime artifact present (compiled CSS/JS, fonts, images) and never dependent on a git-ignored build output. Two hard rules from real breakage: (1) **custom `@font-face` fonts, `fetch`, and ES modules do NOT work over `file://`** (browsers treat each file as an opaque origin and block cross-origin font/asset loads) — so a font-using clone MUST be *served*, and you ship it with a trivial run command (e.g. `npx serve` / `python3 -m http.server`) plus a short README that says "serve it, don't open index.html directly." (2) Use **relative** asset/link paths, not absolute `/...` (which points at the filesystem root under `file://`). Verify by serving a clean *copy* of just the deliverable, and confirm fonts actually load. ## Preflight — bootstrap the toolchain (run this first, once per project) Before recon, make sure the companion skills and the `agent-browser` CLI are installed. This skill ships its **own idempotent installer** that installs whatever is missing and skips whatever's already there. **Invoke it by its full path** (this skill may be installed in a plugin dir away from the user's project) and **point it at the project root with `--dir`** so the skills land where the agents can find them — never assume the current directory: ```bash # is this skill's own directory; is where you're cloning into. bash /scripts/install-deps.sh --dir # install (safe to re-run) bash /scripts/install-deps.sh --dir --check # optional dry-run ``` By default it installs the skills **project-local**, into `/.claude/skills` — so cloning a site never pollutes the user's **global** `~/.claude/skills`. (Pass `--global` only if the user explicitly wants them installed globally.) It installs: **`ui-pack`** (the design/frontend bundle, vendored with this skill), its constituents (**`clone-website`**, **`ui-ux-pro-max`**, **`impeccable`**, **`emil-design-eng`**), and **`ui-animation`** (motion craft for the two motion specialists). The `agent-browser` CLI is installed globally via npm (it's a command-line tool, not a skill). The hard dependency is **`agent-browser` on PATH** — if the installer reports it failed because `npm` is missing, ask the user to install Node/npm, then re-run. Use the **project root** for `--dir` (the workspace where the user is cloning, the same place the build/output folder will live) so its `.claude/skills` is where the agents discover it. Don't proceed to recon until the toolchain is present — but note the skill is **resilient by design**: `agent-browser` is the only true blocker, and if a just-installed skill isn't hot-loaded mid-session, the files are on disk and **every persona degrades gracefully** to the bundled `references/*.md` plus the `agent-browser` CLI, so the run still works (a re-invoke picks the skills up fully). ## Phase 0 — Setup & Requirements (interactive, you + the user) Do this yourself in the main thread. Be efficient; batch your questions. 1. **Resolve the target.** Parse `$ARGUMENTS` as one or more URLs. If none were given, ask. Normalize/validate each. 2. **Verify access.** Confirm you can reach each URL. If the site needs a login, get credentials and any **login quirks** (2FA, SSO, "click X first", a specific entry URL, cookie banners, rate limits, regions). **Only proceed for sites the user is authorized to access and clone.** Store creds via the secure pattern in `references/state-and-resume.md` (gitignored local file, never committed, never echoed, never written into agent transcripts in plaintext beyond what's needed to log in). 3. **Capture requirements.** Ask the user for anything that changes the build: - **Target stack** for the clone (React, Next.js, Vue, Svelte, Angular, SvelteKit, plain HTML/CSS, …) — *independent of the source site's stack.* Default: Next.js + Tailwind + shadcn/ui (the clone-website scaffold). - **Scope** — which pages/routes/flows. Default: exactly what's at the URL(s). - **Fidelity** — default pixel-perfect, pure emulation, mock data for demos. - **Backend depth** — how deep the documentation deliverable should go (UI-observable flows only, vs. inferred data model + API surface + auth). - Any **customizations** (the user may want the clone in a different brand, or merged from several sites). 4. **Offer the run-config choices** (these matter, and matter more once this skill is public — never hard-code them): - **Model tier** — *default Opus for Manager + Developer + Tester* (max fidelity). Offer **cost-optimized** (Sonnet workers, Haiku for mechanical extraction) and **ultra-cheap** for budget-conscious users. Use `AskUserQuestion`. - **Autonomy** — *default fully autonomous* (the loop runs to completion and reports). Offer **checkpoint-at-gates** (pause for sign-off on the Tester's verdict and before declaring done). - **Round cap** — max Dev→Tester rounds per section before escalating to the user (default 4). Prevents runaway spend. 5. **Decide if you have enough.** If anything is still ambiguous (a flow you can't reach, an unclear interaction, missing creds), ask now — before spending tokens. When you're set, confirm the plan back to the user in 3–5 lines and begin. Persist every answer into `state.json` (see `references/state-and-resume.md`) so a resumed session starts from the same requirements without re-asking. ## Phase 1 — Recon & Foundation (you, with agent-browser) This establishes the shared ground truth the whole team builds on. Follow `references/extraction-playbook.md` for the exact extraction scripts. 1. **Pick the build location.** Always build the clone **inside the directory where the skill was invoked** — never somewhere global. Default to an `./output/` subfolder of that directory (create it if missing) so the clone and its `.clone-team/` state sit together and are easy to find, version, and delete. If the user named a folder, use that instead. **Scaffold** the chosen stack there (default: the Next.js + shadcn + Tailwind v4 scaffold `clone-website` expects; for other stacks scaffold that stack's equivalent — e.g. SvelteKit + Tailwind, Vite + Vue). Verify it builds. Record the build dir as `projectDir` in `state.json`. 2. **Recon** with `agent-browser`: full-page screenshots at 1440/768/390, global extraction (fonts, colors, favicons, global JS/CSS, smooth-scroll libs), and the **mandatory interaction sweep** (scroll/click/hover/responsive). Write `docs/research/BEHAVIORS.md` and `docs/research/PAGE_TOPOLOGY.md`. 3. **Foundation build** (sequential, do it yourself): fonts, global tokens, TypeScript types, SVG icons, and an asset-download script. Verify the build. 4. **Decompose** the target into a **page list** — the unit of work for the loop (see "The unit of work is a PAGE" above). For each page record: name/route, URL, screenshot path, the interaction models present, complexity, and dependencies. A single-page site yields a one-item list (one whole-page build). Write this list into `state.json` as the work-list; it is what the build loop iterates over and what resume keys off of. *(Only if a single page is genuinely enormous do you sub-list its sections — but keep one agent owning the whole page so assembly has no seams.)* You may spawn the **Backend Architect in parallel** here — it can start reading the site's architecture and drafting docs while you finish foundation. Pass it the target URL, creds/quirks, the topology doc, and the backend-depth target. ## Phase 2 — Autonomous Build & Test Loop (the Workflow) This is the grind, and it runs as a **resumable background `Workflow`** so it survives pauses and usage-limit cutoffs. Read `references/orchestration.md` for the loop's exact shape; the script is `workflows/clone-build-loop.js`. The loop, **per page** (pages build in parallel; a single-page site is one item): 1. **Extract → spec.** A focused extraction of the whole page produces a spec in `docs/research/components/.spec.md` (the contract — covers every part of the page). 2. **Motion analysis → motion spec.** The **Interaction & Motion Analyst** observes the live original and writes `docs/research/components/.motion.md`: a state matrix for every interactive element, a complete animated-element inventory (load-intro, entrances, scroll-scrubbed, hover/focus, click, time/ loop, and **continuous-decorative** — shimmer/particles/grain/canvas), a motion-token layer, and reduced-motion/keyboard notes. This runs once per page and is the artifact the Tester gates against — it's how subtle hover/focus and "glittery" decorative motion stop slipping through. 3. **Developer builds the ENTIRE page** from the spec into one coherent file (and, on later rounds, from the Tester's exact issues + its own prior notes — *full context every time*). It holds the whole page at once, so backgrounds, text colors, asset paths, and spacing are consistent end-to-end. 4. **Motion pass.** The **Motion Developer** runs a sequential pass over the same file, adding/repairing every entry in the motion spec the build left static or wrong — motion only, never touching layout/content/assets. It runs after the FE build every round, so motion is always the last writer and survives FE fix rounds. 5. **Tester runs a full regression** of the whole page against the goal: visual diff vs. the original at 1440/768/390 via `agent-browser`, every interactive behavior, build/type checks, **and a cross-check against the motion spec** (every inventory entry must actually animate; static-where-the-original-moves is an NG). Returns **OK** or **NG with specific, reproducible issues**. 6. **If NG**, the loop hands the exact issues back: layout/content to the Developer, motion/interaction to the Motion Developer — with full context — and re-builds. Repeat until OK or the round cap is hit (then the page is flagged for your attention). Launch it with the `Workflow` tool, passing `state.json`'s requirements + section list + run-config as `args`. Personas are single-sourced: read the five agent files (`frontend-developer`, `interaction-motion-analyst`, `motion-developer`, `backend-architect`, `tester`) and pass them in `args.personas.{fe, motionAnalyst, motionDev, backend, tester}` so the engine runs the canonical text (it embeds tight capsules as a fallback). Run the **Backend Architect track in parallel** with the section loop. The Developer may spawn its own sub-builders for complex sections — that's expected and good. **Pass the durable-tooling paths in `args`** so the agents can persist results (the Workflow runtime itself cannot write files): `args.statePath` → `scripts/state.mjs` (lifecycle checkpoint), `args.reportPath` → `scripts/report.mjs` (results record), `args.visualDiffPath` → `scripts/visual-diff.mjs` (numeric fidelity). With these set, the Tester records every round (OK and NG) into `.clone-team/report.json`. **Before launching, run `node scripts/report.mjs init --dir --run-id --goal --target --stack `** to start the report. See `references/results-analysis.md` for the full schema and wiring. **Before launching, size the wave to the host.** Run `node scripts/capacity.mjs --wave` and pass the number as `runConfig.waveSize` (with `skipAssembly: true` so the Manager assembles in Phase 3). This caps how many sections build at once so a RAM-tight machine doesn't crash mid-run — big box → big wave, small box → small wave. See `references/orchestration.md` → "Wave size & build-only". **Then verify the launch immediately** (see `references/orchestration.md` → "VERIFY THE LAUNCH"): confirm the engine's startup log shows your real `projectDir`/`stack`, `sections=N`, and the expected `waveSize`, not the defaults. If `args` didn't reach the engine, a run can reach assembly with **zero sections** — that's a misfire to fix, never an empty "success" to accept. **Each completed, Tester-approved section is written to disk and marked done in `state.json` before the loop moves on** — that is what makes the whole thing resumable. If the run is interrupted, a fresh launch skips done sections. ## Phase 3 — Page Assembly & Manager's Final Regression (you) When the loop reports all sections OK: 1. **Assemble** the page(s) in the app entry (`src/app/page.tsx` or the stack's equivalent): layout, scroll containers, z-index, page-level behaviors, smooth scroll. Verify the build. 2. **Your own final regression.** You hold the goal and full context — now confirm the clone is an *exact* copy of the original, end to end, at all three viewports, with every behavior. Compare against the original via `agent-browser`. **Drive the scroll top to bottom and exercise every animation** (morphs, parallax, scroll-triggered cycles, entrance-from-below) — confirm each actually fires and its trajectory matches; do not sign off from still frames. Then **verify portability**: serve the finished clone fresh (or from a clean copy) and confirm it renders fully with no missing runtime artifacts. 3. **If you find gaps**, you don't fix them yourself — you hand the specific mistake back to the **Developer** to fix, then tell the **Tester** exactly what to re-verify. Iterate until your bar is met. 4. **Confirm the documentation deliverable** from the Backend Architect is complete and accurate against `references/backend-doc-template.md`. Only when both gates (Tester, then you) pass is the clone complete. ## Pause, Resume & Recovery (first-class) The user can stop and come back at any time — including after a usage-limit cutoff in a *different* session. This is built in; see `references/state-and-resume.md` for the mechanics. - **`/clone-status`** — read `state.json` and report progress (sections done / in-flight / pending, current phase, last run id). - **`/clone-pause`** — `TaskStop` the running Workflow, flush state, and tell the user how to resume. Nothing in-flight is lost; done sections are on disk. - **`/clone-resume`** — read `state.json`, run `node scripts/state.mjs reconcile --dir ` (syncs state↔disk: fills `specPath` so extraction isn't redone, marks on-disk-unverified sections `built` for test-first re-validation, demotes `done`-without-file, and rebases a stale `projectDir`), then relaunch: same-session via the Workflow's `resumeFromRunId`; cross-session by re-dispatching only the *not-done* sections (the durable, journal-independent path). Always prefer the durable path when in doubt. If you ever come back to an existing clone project and the user just says "continue", treat it as `/clone-resume`. ## Completion report When done, **finalize and render the results report first**, then summarize: ``` node scripts/report.mjs finalize --dir --final-verdict \ --summary-json '' node scripts/report.mjs render --dir node scripts/state.mjs set --dir --key finalVerdict --value ``` The Workflow return is ephemeral — `finalize` is what writes the run's outcome to disk. Then **auto-open `/.clone-team/report.html`** for the user. Then report: stack used; pages/sections built; components + spec files written; assets downloaded; build status; visual-QA result at each viewport; the path to the architecture documentation; any flagged sections or known gaps; the `report.html` + `state.json` locations; and a pointer to `/clone-report` to re-open the scorecard anytime. The run is auditable and re-openable. ## Reference map - `references/orchestration.md` — the team model, the loop, how to launch and steer the Workflow, model-tier wiring, round caps. **Read before Phase 2.** - `references/state-and-resume.md` — `state.json` schema, the secure creds pattern, pause/resume/recovery, and how it composes with `resumeFromRunId`. **Read before Phase 0** (you write state from the very first answers). - `references/extraction-playbook.md` — the exact recon/extraction scripts and spec-file template (condensed from `clone-website`). - `references/motion-playbook.md` — the motion taxonomy, state-matrix + motion- token templates, craft + performance rules, and the drive-to-verify recipe. Self-contained fallback when `ui-animation` isn't installed. **Read before the motion track.** - `references/results-analysis.md` — the consistent results layer: `report.json` schema, the visual metrics (pixel-diff % + SSIM) and their thresholds, the verdict vocabulary, and how `report.mjs` / `visual-diff.mjs` / `/clone-report` wire together. **Read before Phase 2 if you want the scorecard.** - `references/backend-doc-template.md` — the structure of the documentation deliverable the Backend Architect produces. - `agents/frontend-developer.md`, `agents/interaction-motion-analyst.md`, `agents/motion-developer.md`, `agents/backend-architect.md`, `agents/tester.md` — the spawn prompts for the five agents.