Web Reconstruction

English | 简体中文

A Claude Code skill for reverse-first reconstruction of live/legacy websites with mechanical, pass/fail delivery gates. Turn a named customer or legacy site into a completed, backend-editable, multi-tenant implementation - and prove it with pixel, layout, typography, motion, content, asset, and language gates before handoff.

The methodology is stack-agnostic. A reference stack (Nuxt 3 + Spring Boot + PostgreSQL + Redis + MinIO) is described in references/architecture-and-api.md as a concrete example; map the concepts onto your own framework and paths.

Why this skill exists

Most "rebuild this website" workflows stop at a visually similar page. This skill enforces three things that prevent fake-completion:

• Reverse-first: capture the live site's DOM/CSS/JS/assets/motion/responsive breakpoints before writing frontend code. A hand-written approximation that gets patched toward the target is an invalid starting path.
• Hard delivery gates: every claim (visual, typography, motion, content, asset, language, backend editability, runtime artifact) must pass numeric thresholds backed by saved evidence. No "it looks close enough".
• Stop Guard: the agent cannot hand off, summarize as complete, or switch tasks until final-delivery-gate.json reports status: "pass" and deliverable: true - or a proven external blocker is documented.

Install as a Claude Code skill

Copy this directory into your skills folder:

cp -r . ~/.claude/skills/web-reconstruction

Then invoke it in Claude Code with $web-reconstruction (or /web-reconstruction), or just describe the task - the description in SKILL.md triggers it automatically.

Prerequisites

• Node.js + Playwright for the .mjs capture/audit scripts (npm i -D playwright then npx playwright install chromium).
• Python 3.9+ for the .py gate evaluators (standard library only, no pip packages required).
• A workspace with your own frontend/backend/admin stack to refactor onto.

Scripts

All scripts are stack-agnostic - they take URLs, a delivery matrix, and output paths.

Script	Language	Purpose
scripts/capture_delivery_evidence.mjs	Node/Playwright	Capture multi-viewport screenshots, layout metrics, computed typography/effects, hover states, and motion evidence from baseline + target URLs.
scripts/audit_online_reconstruction.mjs	Node/Playwright	Audit route ownership markers, HTTP status, network/console health, broken media, video readiness, and accidental CJK text on configured locales.
scripts/evaluate_visual_delivery_gate.py	Python	Evaluate the visual child gate from pixel-diff summary + layout metrics.
scripts/evaluate_interaction_delivery_gate.py	Python	Evaluate the typography/hover/effect/motion child gate.
scripts/evaluate_final_delivery_gate.py	Python	Aggregate child gates + required evidence into the final deliverability decision.
scripts/generate_delivery_review_report.py	Python	Generate the handoff review report with required vs actual thresholds.

Example usage:

# 1. Capture evidence (baseline = live site, target = your refactor)
node scripts/capture_delivery_evidence.mjs \
  --baseline-url https://legacy.example.com \
  --target-url http://localhost:8083 \
  --matrix references/required-delivery-matrix.json \
  --output ./evidence/my-tenant

# 2. Audit route ownership / assets / language
node scripts/audit_online_reconstruction.mjs \
  --base-url http://localhost:8083 \
  --locales cn,en \
  --pages /,about,products,news,contact \
  --forbid-cjk-locales en \
  --output ./evidence/my-tenant/online-reconstruction-audit.json

# 3. Evaluate child gates
python scripts/evaluate_visual_delivery_gate.py \
  ./evidence/my-tenant/pixel-diff-summary.json \
  --layout-metrics ./evidence/my-tenant/layout-metrics.json \
  --matrix references/required-delivery-matrix.json \
  --output ./evidence/my-tenant/delivery-gate.json

python scripts/evaluate_interaction_delivery_gate.py \
  ./evidence/my-tenant/style-motion-summary.json \
  --matrix references/required-delivery-matrix.json \
  --output ./evidence/my-tenant/interaction-delivery-gate.json

# 4. Aggregate final gate
python scripts/evaluate_final_delivery_gate.py \
  --visual ./evidence/my-tenant/delivery-gate.json \
  --interaction ./evidence/my-tenant/interaction-delivery-gate.json \
  --matrix references/required-delivery-matrix.json \
  --evidence-dir ./evidence/my-tenant \
  --output ./evidence/my-tenant/final-delivery-gate.json

# 5. Generate handoff report
python scripts/generate_delivery_review_report.py \
  --tenant my-tenant \
  --visual ./evidence/my-tenant/delivery-gate.json \
  --interaction ./evidence/my-tenant/interaction-delivery-gate.json \
  --final ./evidence/my-tenant/final-delivery-gate.json \
  --matrix references/required-delivery-matrix.json \
  --output ./evidence/my-tenant/delivery-review-report.md

Run any script with --help to see all options.

Customize the delivery matrix

references/required-delivery-matrix.json is a default template. Copy it into your tenant evidence folder and customize:

• viewports - the widths to verify (defaults: 2048, 1920, 1440, 1366, 1280, 1024, 768, 430, 390).
• routeGroups / routes - the public routes and locale variants to cover (never use a home-only matrix).
• requiredSections - CSS selectors for header/nav/hero/footer/etc.
• styleChecks / interactions - typography properties and hover/carousel/scroll/form behaviors to compare.
• requiredGateFiles - the evidence artifacts the final gate must find.

Do not delete required coverage just because a selector is inconvenient; mark an item optional only when the live site genuinely lacks that feature, and document why.

Gate threshold quick reference

Standard	Threshold
Viewport screenshot pixel diff	<= 1.0%
Full-page screenshot pixel diff	<= 2.0%
Core first-screen section pixel diff	<= 0.5%
Core layout metric delta (width/height/x/y)	<= 2px
Numeric typography/effect delta (size/line-height/letter-spacing/offset)	<= 1px
Animation duration / autoplay interval delta	<= 80ms
Animation delay / stagger delta	<= 50ms
Broken assets (images/fonts/downloads/media)	0
Accidental Chinese on English pages	0
Console/network/hydration errors	0
Responsive breakpoint behavior	match at every required width
Font family / weight / transform / decoration / named effect	exact match
Build / typecheck / backend test / Docker / admin / form gates	pass

A 6% pixel diff is always a failed gate, never "close enough".

Repository layout

web-reconstruction-skill/
├── SKILL.md                          # Skill entry: rules, refactor loop, quality bar
├── agents/openai.yaml                # Agent metadata (display name, default prompt)
├── references/
│   ├── architecture-and-api.md       # Reference stack contract (example: Nuxt + SpringBoot)
│   ├── refactor-workflow.md          # End-to-end workflow + acceptance checklist
│   ├── online-reconstruction-gates.md# 14 hard gates for live-site reconstruction
│   └── required-delivery-matrix.json # Default delivery matrix template
└── scripts/                          # Stack-agnostic verification scripts

License

MIT - see LICENSE.