docs(clone-app): design-capture, unity-re, build-spec rubrics + contract/report updates

plugins/clone-app/skills/clone-app/references/clone-build-spec-template.md

@@ -0,0 +1,54 @@
+# Clone Build Spec — {APP_TITLE}
+
+> The standalone build contract. A fresh session with only this file and the
+> `$WORK/` artifacts it references must be able to build a pixel-perfect,
+> production-ready clone. Reference every artifact by **absolute path + summary**.
+
+**Package:** {PACKAGE}  ·  **Date:** {DATE}  ·  **Selected stack:** {STACK}
+
+## 1. Product overview & parity target
+What the app does; the parity bar (pixel-perfect visual + feature-complete).
+
+## 2. Design system
+From `$WORK/design-tokens.json` (confidence: {…}): color palette + roles, type
+scale (fonts + sizes), spacing scale, corner radii, light/dark theme. Note where
+confidence is med/low and screenshots are the source of truth.
+
+## 3. Screen-by-screen spec
+For **each** screen: purpose · layout · components · states (empty/loading/error)
+· navigation in/out · matching screenshot (`$WORK/screenshots/NN.png`).
+
+## 4. Navigation map / IA
+The full screen graph + entry points.
+
+## 5. API contract
+From `$WORK/payloads.json`: per endpoint — host, method, path, auth,
+request body, response shape, headers.
+
+## 6. Data model
+Entities, fields, relationships (from payloads + RE digest).
+
+## 7. Asset inventory
+Icons, fonts, drawables — extract from `$WORK/output` or recreate. List each.
+
+## 8. Acceptance criteria
+Per screen and per flow — the testable definition of done for prod quality.
+
+## 9. Out of scope / assumptions
+Explicit exclusions and assumptions.
+
+## 10. Artifact references
+Absolute paths to: `design-tokens.json`, `design-digest.md`, `screenshots/`,
+`payloads.json`, `re-digest.md` (+ `unity-digest.md`, `game-assets/` if Unity).
+
+---
+
+## Game variant (Unity)
+Replace these sections:
+- **§2 Design system** → art style + UI atlas inventory; palette from sprites.
+- **§3 Screen-by-screen** → **scene/prefab-by-scene** spec (from `unity-digest.md`):
+  each scene's objects, UI canvas, transitions; matching screenshot.
+- **§5 API contract** → **netcode**: backend (Photon/PlayFab/Mirror/custom),
+  message types, sync model (from the IL2CPP/Mono type model).
+- **§7 Asset inventory** → `$WORK/game-assets/` manifest (sprites, atlases,
+  audio, shaders, scenes, prefabs) + the AssetRipper project path.

plugins/clone-app/skills/clone-app/references/design-capture-guide.md

@@ -0,0 +1,37 @@
+# Design Capture Guide
+
+Goal: recover enough of the target's visual design to clone it **pixel-perfect**.
+Two sources, always combined:
+
+1. **APK resources** (`extract-design.py` on the decompile root) →
+   `design-tokens.json` + `design-digest.md`. Real colors, dimens, theme,
+   fonts, layout inventory, launcher icon.
+2. **Play Store screenshots** (`scrape-play-store.py` → `screenshot_urls`,
+   downloaded to `$WORK/screenshots/`). The visual ground truth for layout,
+   composition, and anything not in res.
+
+## Framework-aware reading (confidence)
+
+| Framework | What's in Android res | Confidence | Fallback |
+|---|---|---|---|
+| Native (XML views) | colors, dimens, themes, **layouts** | high | — |
+| Jetpack Compose | colors/dimens often in res; **no layouts** (UI in Kotlin) | med | grep sources for `Color(0x…)`, `.dp`, `.sp`; screenshots |
+| Flutter | almost nothing (Dart owns design) | low | screenshots primary; note low confidence |
+| React Native | almost nothing (JS owns styles) | low | screenshots primary |
+| Unity | n/a — use `unity-re-guide.md` | low | game assets + screenshots |
+
+`extract-design.py` stamps each token group with `confidence`. When `med`/`low`,
+the build spec relies more on screenshots and says so.
+
+## What to record in `design-tokens.json`
+
+colors · dimens (spacing + `sp` text sizes) · typography (font files, text
+sizes) · shapes (corner/radius dimens) · theme (name, parent, dark flag, items)
+· icon path · layout inventory (count + file names). The caller fills `package`.
+
+## Turning tokens into a spec
+
+Map each token group into the build spec's "Design system" section: palette
+(named colors → roles), type scale (text sizes + fonts), spacing scale (dimens),
+corner radii, light/dark. Pair every screen in the spec with its closest
+`screenshots/NN.png`.

plugins/clone-app/skills/clone-app/references/re-digest-contract.md

@@ -83,3 +83,22 @@ If the fingerprint reports Flutter / React Native / Cordova / Xamarin, set
 available (manifest, strings, hardcoded URLs, SDK list), and leave payloads
 empty where they cannot be recovered. Downstream phases widen the
 uncertainty band accordingly.
+
+## Design & Unity outputs (clone-app additions)
+
+Beyond the three RE files, the Phase 2 subagent ALSO writes:
+
+- `$WORK/design-tokens.json` + `$WORK/design-digest.md` — from
+  `extract-design.py` on the decompile root (standard apps). Schema and
+  confidence rules: see `design-capture-guide.md`.
+- For Unity builds (`detect-unity.sh` → `il2cpp`/`mono`): `$WORK/unity-digest.md`
+  (C# type model + netcode) and `$WORK/game-assets/` + `manifest.json` (via
+  `il2cpp-dump.sh`/`ilspycmd` + `unity-assets.sh`). See `unity-re-guide.md`.
+
+The subagent returns the short `design-summary` (and `unity-summary` when Unity)
+plus these paths — never raw resources, sources, or assets.
+
+### RE Method addition
+| Value | Meaning |
+|---|---|
+| `limited: unity-no-tools` | Unity build but Il2CppInspectorRedux/AssetRipper absent — partial digest, assets/types may be empty. |

plugins/clone-app/skills/clone-app/references/report-template.md

@@ -26,6 +26,16 @@
 - Integrations: {list}
 - Backend required: {yes/no + why}
 
+## 4a. Design System (Detected)
+- Palette: {key colors} · Type: {fonts + scale} · Theme: {light/dark}
+- Confidence: {high/med/low} (source: APK res + {n} Play screenshots)
+- Full tokens: `$WORK/design-tokens.json`; screenshots: `$WORK/screenshots/`
+
+## 4b. Game Assets (if Unity)
+- Build type: {il2cpp/mono} · Type model: `$WORK/unity-digest.md`
+- Extracted assets: `$WORK/game-assets/` ({n} sprites, {n} scenes, …)
+- Omit this section entirely for non-Unity apps.
+
 ## 5. Effort Estimate (AI-Assisted)
 {effort table from effort-estimation-guide}
 **Total: {min}–{max} AI Sprints** (1 sprint ≈ one focused Claude Code session).

plugins/clone-app/skills/clone-app/references/unity-re-guide.md

@@ -0,0 +1,37 @@
+# Unity Reverse-Engineering Guide
+
+Unity ships game logic as native IL2CPP or as managed Mono assemblies. jadx is
+blind to IL2CPP — detect the build first with `detect-unity.sh`.
+
+## IL2CPP (`detect-unity.sh` → `il2cpp`)
+
+Inputs: `lib/<abi>/libil2cpp.so` + `assets/bin/Data/Managed/Metadata/global-metadata.dat`.
+Run `il2cpp-dump.sh <so> <metadata> <out>` (wraps **Il2CppInspectorRedux**,
+https://github.com/LukeFZ/Il2CppInspectorRedux, needs .NET).
+
+**Recoverable:** class / method / field / enum signatures, type hierarchy,
+serialized fields, network/RPC type shapes → data model + feature inventory.
+**Not recoverable:** C# method *bodies* (compiled to native ARM in the .so).
+
+## Mono (`detect-unity.sh` → `mono`)
+
+Inputs: `assets/bin/Data/Managed/*.dll` (real .NET assemblies). Decompile to
+near-source C# with `ilspycmd` (ILSpy CLI): `ilspycmd Assembly-CSharp.dll -o <out>`.
+Best case — full logic recovered.
+
+## Assets (both branches)
+
+`unity-assets.sh <apk> <out>` wraps **AssetRipper**
+(https://github.com/AssetRipper/AssetRipper). Extracts textures, sprites, UI
+atlases, fonts, audio, shaders, **scenes, prefabs** → the game's design system.
+
+## Graceful degradation
+
+If a tool is absent, its wrapper exits 3 with install guidance. The subagent
+then writes a partial `unity-digest.md` and sets `RE Method: limited: unity-no-tools`.
+
+## Legal
+
+Extracted game art is copyrighted. Outside authorized use (own game, lawful
+research), treat extracted assets as **reference only** and recreate in the same
+style — do not ship them.

plugins/clone-app/tests/test-references-content.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+R="$HERE/../skills/clone-app/references"
+fail=0
+has() { # file substring
+  if grep -qF "$2" "$1" 2>/dev/null; then echo "PASS: $(basename "$1") has '$2'"
+  else echo "FAIL: $(basename "$1") missing '$2'"; fail=1; fi
+}
+
+has "$R/design-capture-guide.md" "design-tokens.json"
+has "$R/design-capture-guide.md" "confidence"
+has "$R/design-capture-guide.md" "screenshots"
+has "$R/unity-re-guide.md" "Il2CppInspectorRedux"
+has "$R/unity-re-guide.md" "AssetRipper"
+has "$R/unity-re-guide.md" "ilspycmd"
+has "$R/clone-build-spec-template.md" "Screen-by-screen"
+has "$R/clone-build-spec-template.md" "Acceptance criteria"
+has "$R/clone-build-spec-template.md" "Game variant"
+has "$R/re-digest-contract.md" "design-tokens.json"
+has "$R/re-digest-contract.md" "unity-digest.md"
+has "$R/report-template.md" "Design System"
+has "$R/report-template.md" "Game Assets"
+
+exit $fail