web-clone

name	web-clone
description	URL-driven website cloning with visual + functional verification

Clone a target website from its URL, replicating both visual appearance and core interactive functionality. Uses Playwright MCP for live page extraction, LLM-driven code generation, and iterative verification with `$visual-verdict` for visual scoring.

<Use_When>

• User provides a target URL and wants the site replicated as working code
• User says "clone site", "clone website", "copy webpage", or "web-clone"
• Task requires both visual fidelity AND functional parity with the original
• Reference is a live URL (not a static screenshot — use $visual-verdict for screenshot-only tasks) </Use_When>

<Do_Not_Use_When>

• User only has screenshot references without a live URL — use $visual-verdict directly
• User wants to modify, redesign, or "improve" the site — use standard implementation flow
• Target requires authentication, payment flows, or backend API parity — out of scope for v1
• Multi-page / multi-route deep cloning — v1 handles single-page scope only </Do_Not_Use_When>

<Scope_Limits> v1 scope: Single page clone of the provided URL.

Included:

• Layout structure (header, nav, content areas, sidebar, footer)
• Typography (font families, sizes, weights, line heights)
• Colors, spacing, borders, border-radius
• Core interactions: navigation links, buttons, form elements, dropdowns, modals, toggles
• Responsive hints from the extracted layout (flexbox/grid patterns)

Excluded:

• Backend API integration or data fetching
• Authentication flows or protected content
• Dynamic/personalized content (user-specific data)
• Multi-page crawling or route graph cloning
• Third-party widget functionality (maps, embeds, chat widgets)
• Image/asset replication (use placeholders for external images)

Legal notice: Only clone sites you own or have explicit permission to replicate. Respect copyright and trademarks. </Scope_Limits>

Playwright MCP server must be available for browser automation.

1. Before first tool use, call ToolSearch("browser") or ToolSearch("playwright") to discover available browser tools.
2. If no browser tools are found, instruct the user:

   Playwright MCP is required. Configure it:
   codex mcp add playwright npx "@playwright/mcp@latest"
   

3. Required tools: browser_navigate, browser_snapshot, browser_take_screenshot, browser_evaluate, browser_wait_for. Optional: browser_click, browser_network_requests.

- `target_url` (required): The URL to clone - `output_dir` (optional, default: current working directory): Where to generate the clone project - `tech_stack` (optional, inferred from project context): HTML/CSS/JS, React, Vue, Svelte, etc.

<Tool_Usage>

• Before first MCP tool use, call ToolSearch("browser") or ToolSearch("playwright") to discover deferred Playwright MCP tools.
• If no browser tools are found, stop immediately and instruct the user to configure Playwright MCP.
• Use browser_snapshot (accessibility tree) for structural understanding — it is far more token-efficient than screenshots.
• Use browser_take_screenshot only when visual verification is needed (Pass 1 baseline, Pass 4 comparison).
• Use browser_evaluate for DOM/style extraction — pass the scripts from this skill EXACTLY as written (do not modify them).
• If running within ralph, use state_write / state_read for web-clone state persistence between iterations.
• Skip Codex consultation for straightforward extraction; use it only if verification repeatedly fails on the same issue. </Tool_Usage>

<State_Management> Persist extraction and progress data so the pipeline can resume if interrupted.

• After Pass 1 completes: Write extraction summary to .omb/state/{scope}/web-clone-extraction.json containing:
  • target_url, extracted_at timestamp
  • screenshot_path (path to target-full.png)
  • landmark_count (number of nav, main, footer, form elements)
  • interactive_count (number of detected interactive elements)
  • extraction_size_kb (approximate size of DOM extraction data)
• After each Pass 4 verification: Append the composite verdict to .omb/state/{scope}/web-clone-verdicts.json.
• When running within ralph: Also persist the visual portion of the composite verdict to .omb/state/{scope}/ralph-progress.json for ralph compatibility, mapping visual.score → top-level score and visual.verdict → top-level verdict.
• On completion or failure: Write final status with completed_at or failed_at timestamp. </State_Management>

<Context_Budget> Pass 1 extraction can produce very large data. Apply these limits proactively:

• DOM tree: If the serialized JSON exceeds ~30KB, reduce depth parameter from 8 to 4 and re-extract. Focus on top-level structure.
• Accessibility snapshot: If it exceeds ~20KB, this is normal for complex pages. Summarize key landmarks rather than keeping the full tree.
• Interactive elements: Cap at 50 elements. If more exist, keep only visible ones (isVisible: true).
• Total extraction context: Aim for under 60KB combined. If exceeded, prioritize: screenshot > accessibility snapshot > interactive elements > DOM styles.
• Image tokens: Full-page screenshots are expensive. Take one baseline in Pass 1 and one comparison in Pass 4. Do not take screenshots between iterations unless debugging a specific region. </Context_Budget>

Pass 1 — Extract

Capture the target page's structure, styles, interactions, and visual baseline.

1. Navigate: browser_navigate to target_url.
2. Wait for render: browser_wait_for with appropriate condition (network idle or timeout of 5s) to ensure full render including lazy-loaded content.
3. Accessibility snapshot: browser_snapshot — captures the semantic tree (roles, names, values, interactive states). This is your primary structural reference.
4. Full-page screenshot: browser_take_screenshot with fullPage: true — save as reference baseline target-full.png.
5. DOM + computed styles: browser_evaluate with the following script. COPY THIS SCRIPT EXACTLY — do not modify it:

   (() => {
     const walk = (el, depth = 0) => {
       if (depth > 8 || !el.tagName) return null;
       const cs = window.getComputedStyle(el);
       return {
         tag: el.tagName.toLowerCase(),
         id: el.id || undefined,
         classes: [...el.classList].slice(0, 5),
         styles: {
           display: cs.display, position: cs.position,
           width: cs.width, height: cs.height,
           padding: cs.padding, margin: cs.margin,
           fontSize: cs.fontSize, fontFamily: cs.fontFamily,
           fontWeight: cs.fontWeight, lineHeight: cs.lineHeight,
           color: cs.color, backgroundColor: cs.backgroundColor,
           border: cs.border, borderRadius: cs.borderRadius,
           flexDirection: cs.flexDirection, justifyContent: cs.justifyContent,
           alignItems: cs.alignItems, gap: cs.gap,
           gridTemplateColumns: cs.gridTemplateColumns,
         },
         text: el.childNodes.length === 1 && el.childNodes[0].nodeType === 3
           ? el.textContent?.trim().slice(0, 100) : undefined,
         children: [...el.children].map(c => walk(c, depth + 1)).filter(Boolean),
       };
     };
     return walk(document.body);
   })()
   

6. Interactive elements: browser_evaluate to catalog all interactable elements. COPY THIS SCRIPT EXACTLY — do not modify it:

   (() => {
     const results = [];
     document.querySelectorAll(
       'button, a[href], input, select, textarea, [role="button"], ' +
       '[onclick], [aria-haspopup], [aria-expanded], details, dialog'
     ).forEach(el => {
       results.push({
         tag: el.tagName.toLowerCase(),
         type: el.type || el.getAttribute('role') || 'interactive',
         text: (el.textContent || '').trim().slice(0, 80),
         href: el.href || undefined,
         ariaLabel: el.getAttribute('aria-label') || undefined,
         isVisible: el.offsetParent !== null,
       });
     });
     return results;
   })()
   

7. Network patterns (optional): browser_network_requests — note XHR/fetch calls for reference. Do not attempt to replicate backends.

Keep all extraction results in working memory for Pass 2.

Pass 2 — Build Plan

Analyze extraction results and decompose into a component plan.

1. Identify page regions: From DOM tree + accessibility snapshot, identify major sections:

   • Navigation bar / header
   • Hero / banner section
   • Main content area(s)
   • Sidebar (if present)
   • Footer
   • Overlay elements (modals, drawers)

2. Map components: For each region, define:

   • Component name and responsibility
   • Key style properties (from computed styles)
   • Content summary (headings, text, images)
   • Child components if nested

3. Create interaction map: From interactive elements list:

   • Navigation links → anchor tags with href
   • Form elements → proper <form> with inputs, labels, validation
   • Buttons → click handlers (toggle, submit, navigate)
   • Dropdowns/modals → show/hide toggle with transitions
   • Accordions/tabs → state-based visibility

4. Extract design tokens: Identify recurring values:

   • Color palette (primary, secondary, background, text colors)
   • Font stack (families, size scale, weight scale)
   • Spacing scale (padding/margin patterns)
   • Border radius values

5. Define file structure:

   {output_dir}/
   ├── index.html          (or App.tsx / App.vue)
   ├── styles/
   │   ├── globals.css      (reset + tokens)
   │   └── components.css   (or scoped styles)
   ├── scripts/
   │   └── interactions.js  (toggle, modal, dropdown logic)
   └── assets/              (placeholder images)
   

   Adapt to tech_stack if specified (React components, Vue SFCs, etc.).

Pass 3 — Generate Clone

Implement the clone from the plan. Work component-by-component.

1. Scaffold: Create the directory structure and base files.
2. Design tokens first: Implement CSS custom properties or Tailwind config from extracted tokens.
3. Layout shell: Build the page-level layout matching the original's flexbox/grid structure.
4. Components: Implement each region top-down:
   • Match DOM structure from extraction (semantic tags, landmark roles)
   • Apply computed styles — prioritize layout properties, then typography, then decorative
   • Use actual extracted text content; use placeholder <img> for external images
5. Interactions: Wire up detected behaviors:
   • Navigation: working <a> tags (to # anchors or stubs for v1)
   • Forms: proper structure with <label>, input types, placeholder text
   • Toggles: JavaScript for dropdowns, modals, accordions
   • Hover/focus states: CSS transitions matching original behavior
6. Responsive: If the original uses responsive breakpoints (detectable from media queries in computed styles or from viewport behavior), add basic responsive rules.

Pass 4 — Verify

Compare the clone against the original across three dimensions.

1. Serve the clone: Start a local server for the generated project:

   npx serve {output_dir} -l 3456 --no-clipboard
   

   If npx serve is unavailable, fall back to: python3 -m http.server 3456 -d {output_dir}. The clone will be accessible at http://localhost:3456.

2. Visual verification:

   • Navigate to the clone with Playwright: browser_navigate to clone URL.
   • Take full-page screenshot of clone.
   • Run $visual-verdict with: reference_images=["target-full.png"], generated_screenshot="clone-full.png", category_hint="web-clone".
   • The visual portion of the verdict feeds directly into the composite verdict below.
   • Visual pass threshold: score >= 85.

3. Structural verification: Compare landmark counts:

   • Count <nav>, <main>, <footer>, <form>, <button>, <a> in both original and clone.
   • Structure passes when all major landmarks exist (missing landmarks = fail).

4. Functional spot-check: Test 2–3 detected interactions via Playwright:

   • Click a navigation link → verify URL change or scroll behavior
   • Toggle a dropdown/modal → verify visibility change
   • Interact with a form field → verify it accepts input
   • Use browser_click and browser_snapshot to verify state changes.

5. Emit composite verdict:

{
  "visual": {
    "score": 82,
    "verdict": "revise",
    "category_match": true,
    "differences": ["Header spacing tighter than original"],
    "suggestions": ["Increase nav gap to 24px"]
  },
  "functional": {
    "tested": 3,
    "passed": 2,
    "failures": ["Dropdown does not open on click"]
  },
  "structure": {
    "landmark_match": true,
    "missing": [],
    "extra": []
  },
  "overall_verdict": "revise",
  "priority_fixes": [
    "Fix dropdown toggle interaction",
    "Increase header nav spacing"
  ]
}

Pass 5 — Iterate

Fix highest-impact issues and re-verify.

1. Prioritize fixes by impact: layout > interactions > spacing > typography > colors.
2. Apply targeted edits: Fix only the issues listed in priority_fixes. Do not refactor working code.
3. Re-verify: Repeat Pass 4.
4. Loop: Continue until overall_verdict is pass OR max 5 iterations reached.
5. Final report: Summarize what was successfully cloned, any remaining differences, and elements that could not be replicated.

<Output_Contract> After each verification pass, emit a composite web-clone verdict JSON:

{
  "visual": {
    "score": 0,
    "verdict": "revise",
    "category_match": false,
    "differences": ["..."],
    "suggestions": ["..."],
    "reasoning": "short explanation"
  },
  "functional": {
    "tested": 0,
    "passed": 0,
    "failures": ["..."]
  },
  "structure": {
    "landmark_match": false,
    "missing": ["..."],
    "extra": ["..."]
  },
  "overall_verdict": "revise",
  "priority_fixes": ["..."]
}

Rules:

• visual follows the VisualVerdict shape from $visual-verdict
• functional.tested/passed are counts; failures list specific interaction failures
• structure.landmark_match is true when all major HTML landmarks (nav, main, footer, forms) are present
• overall_verdict: pass when visual.score >= 85 AND functional.failures is empty AND structure.landmark_match is true
• priority_fixes: ordered by impact, drives the next iteration </Output_Contract>

<Iteration_Thresholds>

• Visual pass: score >= 85
• Functional pass: zero failures on tested interactions
• Structure pass: all major landmarks present
• Overall pass: all three dimensions pass
• Max iterations: 5 (report best achieved result if threshold not met) </Iteration_Thresholds>

<Error_Handling>

• Playwright MCP unavailable: Stop. Instruct user to configure it. Do not attempt to clone without browser tools.
• Page fails to load: Report the URL and HTTP status. Suggest the user verify the URL is accessible.
• browser_evaluate returns empty: The page may use heavy client-side rendering. Wait longer (browser_wait_for with extended timeout) and retry once.
• Visual score stuck below threshold after 3 iterations: Report the current state as best-effort. List the unresolved differences for the user.
• Extraction data too large for context: Truncate deep DOM branches (depth > 6). Focus on top-level structure and defer nested details to iteration fixes. </Error_Handling>

**User**: "Clone https://news.ycombinator.com"

Pass 1: Navigate to HN. Extract: table-based layout, orange (#ff6600) nav bar, story list with links + points + comments, footer. Screenshot saved.

Pass 2: Regions: nav bar (logo + links), story table (30 rows × title + meta), footer. Tokens: orange #ff6600, gray #828282, Verdana font, 10pt base. Interaction map: story links (external), comment links, "more" pagination.

Pass 3: Generate index.html with HN-style table layout, CSS matching extracted colors/fonts, working <a> tags for stories.

Pass 4: Visual score=78 (font size off, spacing between stories too tight). Functional 2/2 (links work). Structure match=true.

Pass 5 iteration 1: Fix font to Verdana 10pt, increase row padding → score=88. Functional 2/2. Structure match. → overall_verdict: pass. Done.

<Final_Checklist>

• Pass 1 extraction completed and summarized (screenshot + accessibility tree + DOM styles + interactions)
• Pass 2 component plan created with file structure
• Pass 3 clone generated and files written to output_dir
• Clone serves locally without errors
• Pass 4 composite verdict emitted with all three dimensions
• overall_verdict is pass, or max 5 iterations reached with best-effort report
• When in ralph: visual verdict persisted to ralph-progress.json
• Extraction summary persisted to web-clone-extraction.json </Final_Checklist>