# CLAUDE.md — ui-clone-skills development guide

## Project structure

```
ui_clone/          Python package (gates, hooks, pipeline, DAG, metrics)
skills/            3 Claude Code skills (ui-reverse-engineering, ui-capture, visual-debug)
scripts/           Bash automation (extraction, verification, git hooks)
hooks/             Plugin hook registration (hooks.json + shim.sh)
tests/             pytest suite (260 tests)
.claude-plugin/    Plugin manifest (plugin.json, marketplace.json)
```

## Development commands

```bash
uv run python -m pytest tests/ -q          # run all tests
uv run python -m pytest tests/test_gate.py  # run specific module
bash scripts/pre-push-security.sh           # security + cross-ref + version sync
python -m ui_clone.gate tmp/ref/<c> all     # validate all gates
```

## Verification gate (must pass before commit)

```
[] uv run python -m pytest tests/ — 0 failures
[] bash scripts/pre-push-security.sh — 0 blockers
[] bash -n on every modified .sh file
```

## Rules

### Language
- All skill docs (`skills/**/*.md`), README, CHANGELOG: **English only**
- Code comments: English only
- Commit messages: English only

### Naming
- Python package: `ui_clone`
- npm package: `agent-browser`
- GitHub: `vercel-labs/agent-browser`, `rtk-ai/rtk`
- Owner: `voidmatcha`

### Pipeline step numbering
Sub-docs must match SKILL.md pipeline numbering:
- Step 5 = interaction-detection.md
- Step 5c-a = bundle-analysis.md (download + grep; NOT "Step 6")
- Step 5c-b = bundle-verification.md (numerical comparison)
- Step 5d = transition-spec-rules.md (produces external-sdks.json)
- Step 6 = animation-detection.md
- Step 6c = section-audit.md
- Step 6d = transition-coverage.md

### Gate → artifact mapping
Each gate checks artifacts produced BEFORE that gate fires. Dispatch keys live in `ui_clone/gate.py` `VALID_GATES`:
- `reference` (after Phase 1 / `/ui-capture`): static/ref/ ≥5 PNGs, transitions/ref/ ≥1 file, regions.json
- `extraction` (after Step 3): structure.json, head.json, styles.json, fonts.json, visible-images.json, inline-svgs.json, body-state.json, design-bundles.json, css/variables.txt, em-conversion.json (if scalingSystem ≠ px-fixed)
- `bundle` (after 5c-a): bundles/ (≥1 JS chunk; warns <3), interactions-detected.json, scroll-engine.json
- `spec` (after 5d): bundle-map.json, external-sdks.json, transition-spec.json (validates `transitions[0]` has id/trigger/bundle_branch), verify/ ≥5 frames
- `pre-generate` (before Step 7): extracted.json, transition-coverage.json, section-map.json, hover timing resolved, dom-state-diff.json (if hasPreloader), webflow-* (if Webflow), audit artifacts (element-roles, element-groups, layout-decisions, component-map)
- `post-implement` (after each transition impl): extracted.json, transition-spec.json, static/ref ≥5
- `section-compare` (Stop hook): tmp/ref/<c>/sections/result.txt — 0 ❌ FAIL lines and 0 "⚠️ MISSING impl" lines

If you add an artifact check to a gate, ensure the sub-doc that produces it runs BEFORE that gate.

**Phase 0A note:** `canvas-webgl-detection.json` is produced by the pipeline but is *advisory*, not gated — it routes the agent to `canvas-webgl-extraction.md` when needed. No `gate_canvas_*` exists.

### Sub-doc conventions
- Title format: `# <Name> — Step <N>` matching SKILL.md pipeline
- "After this step" links must point to the correct next step per SKILL.md
- `animations-detected.json` is merged into `extracted.json` at Step 6b — not checked by gates directly
- All agent-browser commands must use `--session <name>`
- All JS evals must use IIFE: `(() => { ... })()`

### Version sync
- `plugin.json` and `marketplace.json` versions must match
- `pyproject.toml` version must be updated on release
- `claude-pre-push.sh` enforces this automatically

### Section name detection (scripts)
3 scripts share the same keyword → name mapping for section detection:
- `extract-assets.sh`, `extract-section-html.sh`, `section-clips.sh`
When adding new keywords, update all 3.

### FPS
All video frame extraction uses 60fps. `video-transition-compare.sh` defaults to `FPS=60`.

### Token management
- Large eval output → pipe to file, then Read/Grep specific lines
- Never let DOM/style JSON print to stdout
- Ref screenshots: AE/SSIM diff only, never Read for comparison (except Phase E)

## Review checklist

Run before push — `scripts/review.sh` automates this:

```
[] Tests pass (260+)
[] Security gate passes (11 checks)
[] Sub-doc step numbers match SKILL.md pipeline
[] Gate artifact checks match sub-doc output timing
[] No stale refs to deleted files (validate-gate.sh, run-pipeline.sh, ui_skills.*)
[] README numbers accurate (sub-doc count, token count, FPS)
[] Cross-skill refs use correct relative paths (../visual-debug/...)
[] plugin.json + marketplace.json versions match
[] No hardcoded local paths in SKILL.md (use $SCRIPTS_DIR, $PLUGIN_ROOT)
[] Section name keyword lists consistent across 3 scripts
```