@relipa/ai-flow-kit 0.1.5 → 0.1.6

package/bin/aiflow.js

@@ -20,6 +20,7 @@ const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
 const scaffoldPlaywrightCommand = require('../scripts/scaffold-playwright');
+const docsBranchCommand = require('../scripts/docs-branch');
 const semver = require('semver');
 const { execSync: execSyncChild, spawnSync } = require('child_process');
 
@@ -390,6 +391,39 @@ memCmd
     .description('Clear all memories')
     .action(() => { memoryCommand('clear'); });
 
+// ── docs (branch + Merge Request workflow for AK-Docs/Shared-Docs) ─────
+// See docs/internal/Docs-Management-Flow.md — PM reviews & merges `main`;
+// every other role updates docs on feature/<functionId>/<taskId> from main.
+const docsCmd = program.command('docs').description('Branch & Merge Request workflow for AK-Docs/Shared-Docs (see Docs-Management-Flow.md)');
+
+docsCmd
+    .command('branch <functionId> <taskId>')
+    .description('Pull latest main, then create (or checkout) feature/<functionId>/<taskId>')
+    .option('-r, --repo <name>', 'AK-Docs | Shared-Docs', 'AK-Docs')
+    .option('-b, --base <branch>', 'base branch to branch from', 'main')
+    .option('-y, --yes', 'skip the interactive confirm — only pass this after the user has approved the plan in chat')
+    .action((functionId, taskId, options) => {
+        docsBranchCommand.createBranch({
+            functionId, taskId,
+            repo: options.repo, base: options.base, yes: options.yes,
+        });
+    });
+
+docsCmd
+    .command('submit')
+    .description('Commit + push the current docs branch and open a Merge Request against main')
+    .requiredOption('-t, --title <title>', 'commit message / MR title')
+    .option('-d, --description <text>', 'MR description', '')
+    .option('-r, --repo <name>', 'AK-Docs | Shared-Docs', 'AK-Docs')
+    .option('-b, --base <branch>', 'target branch', 'main')
+    .option('-y, --yes', 'skip the interactive confirm — only pass this after the user has approved the plan in chat')
+    .action((options) => {
+        docsBranchCommand.submitDocs({
+            title: options.title, description: options.description,
+            repo: options.repo, base: options.base, yes: options.yes,
+        });
+    });
+
 // ── guide ─────────────────────────────────────────────────────
 program
     .command('guide')

package/custom/rules/ml-conventions.md

@@ -7,14 +7,16 @@
 
 ## ML Plan Output Paths
 
+ML tickets share the **same** `AK-Docs/04.Coding/` folders as the standard Dev workflow (see `project-conventions.md`) — no separate ML section:
+
 | Output | Path | Note |
 |--------|------|------|
-| ML problem doc | `plan/[ticket-id]/ml-problem.md` | Gate 1 output |
-| Experiment plan | `plan/[ticket-id]/experiment-plan.md` | Gate 2 output — **NOT** `docs/superpowers/plans/` |
-| Evaluation report | `plan/[ticket-id]/eval-report.md` | Gate 4 output |
+| ML problem doc | `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Gate 1 output |
+| Experiment plan | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` | Gate 2 output — **NOT** `docs/superpowers/plans/`, **NOT** `plan/` |
+| Evaluation report + model card | `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | Gate 4 output — include the model card draft in the same file, under its own section |
 
-> The `[ticket-id]` comes from `.aiflow/context/current.json`.
-> If no ticket context exists, use a descriptive slug: `plan/<feature-name>/ml-problem.md`.
+> `[functionId]` và `[ticketId]` được xác định theo đúng quy tắc "functionId & ticketId" trong `project-conventions.md` — **BẮT BUỘC xác định ở Gate 1 trước khi ghi file đầu tiên.**
+> `plan/[ticket-id]/...` (đường dẫn cũ) đã **DEPRECATED** — không được ghi output mới vào `plan/`. Chỉ code/notebook/model artifact thật (Gate 3 training) mới nằm ngoài `AK-Docs`, theo mục "Data & Model Versioning" bên dưới.
 
 ---
 
@@ -74,9 +76,10 @@ These rules are non-negotiable and override any convenience shortcut:
 
 Before saving any ML plan, experiment plan, or eval report, verify:
 
-- [ ] Output path follows the table above — NOT the skill's default path
-- [ ] `[ticket-id]` is read from `.aiflow/context/current.json`
-- [ ] Directory `plan/[ticket-id]/` exists or will be created
+- [ ] Output path follows the table above — NOT the skill's default path, NOT the legacy `plan/` folder
+- [ ] `functionId` đã được xác định/xác nhận ở Gate 1 (xem `project-conventions.md`)
+- [ ] `[ticketId]` is read from `.aiflow/context/current.json`
+- [ ] Directory `AK-Docs/04.Coding/<section>/[functionId]/` exists or will be created
 - [ ] Announced path in the handoff message matches the actual saved path
 
 ---

package/custom/rules/project-conventions.md

@@ -7,7 +7,11 @@
 
 ## DEV Workflow Output Paths (`AK-Docs/04.Coding/`)
 
-Áp dụng cho taskType: `feature` · `bug-fix` · `refactor` · `investigation` · `documentation`.
+Áp dụng cho taskType: `feature` · `bug-fix` · `refactor` · `investigation` · `documentation` · `gen-doc` · các taskType ML (xem `ml-conventions.md`).
+
+> `gen-doc` (2-gate, ad-hoc document generation) và các ticket ML đều dùng **chung** bộ thư mục `AK-Docs/04.Coding/` bên dưới — không có section riêng. Chỉ khác số Gate được dùng (gen-doc chỉ dùng Gate 1–2, ML dùng đủ Gate 1–5).
+
+### Standard tasks (feature, bug-fix, refactor, investigation, documentation, gen-doc, ML)
 
 | Output | Path | Note |
 |--------|------|------|
@@ -30,7 +34,19 @@
 
 ### Legacy
 
-- ❌ Đường dẫn cũ `plan/[ticket-id]/requirement.md`, `plan/[ticket-id]/plan.md`, `plan/[ticket-id]/summary.md` đã **DEPRECATED** — không được ghi output mới vào `plan/`.
+- ❌ Đường dẫn cũ `plan/[ticket-id]/requirement.md`, `plan/[ticket-id]/plan.md`, `plan/[ticket-id]/summary.md`, `plan/[ticket-id]/output.md`, `plan/[ticket-id]/task-summary.md`, `plan/[ticket-id]/ml-problem.md`, `plan/[ticket-id]/experiment-plan.md`, `plan/[ticket-id]/eval-report.md` đã **DEPRECATED** cho MỌI taskType (kể cả `gen-doc` và ML) — không được ghi output mới vào `plan/`. Chỉ code/artifact thật sự thuộc source repo (hoặc cache thiết kế Figma — xem `read-study-requirement` skill) mới ở ngoài `AK-Docs`.
+
+### gen-doc tasks (2-gate flow — NO `plan.md`, dùng chung thư mục Coding)
+
+| Output | Path | Note |
+|--------|------|------|
+| Requirement doc | `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Gate 1 output — document outline |
+| Document output | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` | Gate 2 output — the generated document (or custom path/format — e.g. Excel — noted in the requirement doc; still record the path used in this file) |
+| Task summary | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md` | Auto-generated after Gate 2 |
+
+> For gen-doc tasks: **do NOT create `plan.md`**. Gate 2 generates the output document directly.
+> If the requirement specifies an Excel output or a custom path, generate it at that path, but still write a short pointer + summary into the Gate 2 output doc above so the tracker/AK-Docs history stays complete.
+> `functionId` vẫn **BẮT BUỘC xác định ở Gate 1** theo đúng quy tắc "functionId & ticketId" ở trên — với gen-doc không suy ra được từ input thì hỏi trực tiếp người yêu cầu (ví dụ dùng ticketId rút gọn hoặc mã chủ đề báo cáo, ví dụ `AD-HOC` nếu task không gắn với chức năng cụ thể nào).
 
 ---
 

package/custom/skills/design-experiment/SKILL.md

@@ -71,7 +71,7 @@ An open-ended experiment loop with no stopping rule is out of scope for a gated
 
 ### 7. Output the experiment plan
 
-Write all of the above to `plan/[ticket-id]/experiment-plan.md`. The document must be self-contained: a developer who did not attend the framing discussion should be able to reproduce the full experiment sequence from the plan alone.
+Write all of the above to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path). The document must be self-contained: a developer who did not attend the framing discussion should be able to reproduce the full experiment sequence from the plan alone.
 
 ---
 
@@ -85,4 +85,4 @@ Write all of the above to `plan/[ticket-id]/experiment-plan.md`. The document mu
 - [ ] Experiment tracking configured (params, metrics, seed, data version, git commit)
 - [ ] Run-naming convention agreed and follows `ml-conventions.md`
 - [ ] Stopping and decision rule stated (metric, threshold, experiment budget)
-- [ ] Full plan written to `plan/[ticket-id]/experiment-plan.md`
+- [ ] Full plan written to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path)

package/custom/skills/evaluate-model/SKILL.md

@@ -74,7 +74,7 @@ Re-run the final eval using only the logged seed, the pinned config, and the reg
 
 ### 8. Write the eval report and model card
 
-Output `plan/[ticket-id]/eval-report.md` containing: the metric table (baseline, threshold, achieved), error analysis findings, overfitting gap, leakage check results, and robustness notes.
+Output `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path) containing: the metric table (baseline, threshold, achieved), error analysis findings, overfitting gap, leakage check results, and robustness notes.
 
 Draft a model card covering: intended use, training data description, evaluation metrics and their context, known limitations, and owner/contact.
 
@@ -89,5 +89,5 @@ Draft a model card covering: intended use, training data description, evaluation
 - [ ] All three leakage types re-checked and documented (target, contamination, temporal)
 - [ ] Robustness assessed under noise, edge cases, and sensitive slices
 - [ ] Result reproduced from logged seed and config — numbers match
-- [ ] `plan/[ticket-id]/eval-report.md` written
+- [ ] `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path) written
 - [ ] Model card drafted (intended use, data, metrics, limitations, owner)

package/custom/skills/explore-data/SKILL.md

@@ -84,4 +84,4 @@ Write the EDA results into the `ml-problem.md` file created by `frame-ml-problem
 - [ ] **Temporal leakage** checked and documented (chronological integrity verified if applicable)
 - [ ] Data-quality issues listed (units, label noise, sampling bias, drift)
 - [ ] Required cleaning steps noted
-- [ ] All findings written into `plan/[ticket-id]/ml-problem.md` data report section
+- [ ] All findings written into `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` data report section (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path)

package/custom/skills/figma-to-component/SKILL.md

@@ -14,6 +14,22 @@ keywords: figma, design, component, ui, generate, react, nextjs, nextjs-app-rout
 
 ---
 
+## Gate mode (called from Gate 3 of the gate workflow)
+
+When invoked by Gate 3 and `plan/[ticket-id]/design/nodes.json` exists:
+
+- **Skip Step 0, Step 1, Step 2, Step 2.5** — the design was already read and images already
+  exported during Gate 1. Do NOT call Figma MCP again.
+- Load the cached design from `plan/[ticket-id]/design/nodes.json` and the image mapping from
+  `plan/[ticket-id]/design/design-context.md` (section "Image Map").
+- **Copy images** from `plan/[ticket-id]/design/images/` to `public/assets/figma/` before
+  generating components, so the `src` paths in the generated code resolve.
+- Continue from **Step 3** (detect CSS tooling) onward.
+
+When invoked standalone (no `design/nodes.json`): run the full Process from Step 0.
+
+---
+
 ## Step 0: Verify Figma MCP is available
 
 Before doing anything, confirm the Figma MCP server is connected in this session:
@@ -53,6 +69,19 @@ Use Figma MCP tools to fetch design information:
 Note: `get_figma_data` returns layout, fills, strokes, typography, and component
 definitions in a single response. No separate style or component fetch is needed.
 
+**Tier 1 call budget (MANDATORY).** Since 2025-11-17 Figma rate-limits by endpoint tier:
+`get_figma_data` (file/nodes) and image *renders* share the same **Tier 1** bucket —
+only **10-20 calls/min** on a Dev/Full seat, and **~6 calls/MONTH** on a View/Collab seat.
+Every exploratory call burns the same budget as an image export, so:
+
+- **ALWAYS pass `nodeId`** — never fetch the whole file.
+- Start with the lowest `depth` that can answer the question; do NOT probe depth 1→2→3.
+- Max **2 `get_figma_data` calls per design**. If the tree is truncated, make ONE targeted
+  follow-up on the specific child nodeId — not a re-read of the parent.
+- Keep total Tier 1 calls (metadata + renders) **≤ 8 per minute**; space calls 5-10s apart.
+- **Check the cache BEFORE any MCP call** — Gate mode reads `plan/[ticket-id]/design/nodes.json`;
+  standalone: if a `plan/*/design/nodes.json` exists for the same fileKey+nodeId, reuse it.
+
 Analyze the output to extract:
 - **Layout**: flexbox direction, gap, padding, alignment
 - **Sizing**: width/height (fixed vs fill vs hug)
@@ -73,33 +102,148 @@ After receiving node data from Step 2, scan the entire node tree to detect image
 - Node is a frame/group containing many complex layers (icon, illustration, banner) that cannot be recreated with CSS → needs image export
 - Node has `type === "VECTOR"` or `type === "BOOLEAN_OPERATION"` → always export as SVG/PNG
 
-**Export images via MCP:**
-
-For each detected image node, call MCP tool `download_figma_images`:
-
-```
-download_figma_images({
-  fileKey: "<fileKey>",
-  nodes: [
-    { nodeId: "<nodeId>", fileName: "<layerName-nodeId>.png" }
-  ],
-  localPath: "public/assets/figma/"
-})
+**Naming convention (single source of truth):**
+
+Every exported/provided image is keyed to its node through a manifest so matching never
+relies on guessing layer names (which repeat in real designs):
+
+- **File name** — the manifest below is authoritative, so any stable name works. Two accepted forms:
+  - `<imageRef>.png` — the full 40-char imageRef hash (e.g. `a1f7af10c49119532fa5e95ccceef6adcac9e86c.png`).
+    This is what `download_figma_images` and manual API exports produce by default — **keep it,
+    no renaming needed**. Collision-proof. Recommended for manual/bulk download.
+  - `<layer-slug>-<imageRef first 8 chars>.png` — human-readable variant (e.g. `top-phase1-554b0901.png`).
+    Use when you want readable asset names; you must rename after download.
+  - Vector / rendered nodes have no imageRef → `<layer-slug>-<nodeId>.png` (or `<nodeId>.png`).
+  - Pick ONE form per project and keep the manifest consistent with the files on disk.
+- **Manifest file — one PER DESIGN, not one global file.** Maps **nodeId → file**; several
+  nodeIds may map to the same file (reused image). This is authoritative. Location:
+  - **Gate mode (a ticket):** `plan/[ticket-id]/design/figma-manifest.json` (next to
+    `design-context.md` / `nodes.json`).
+  - **Standalone (no ticket):** `public/assets/figma/figma-manifest.<fileKey>.json`.
+  - Do NOT share one `figma-manifest.json` across multiple tickets: a `nodeId` is only unique
+    within one Figma file, so a global manifest mixes designs and maps the wrong image. The
+    **images** stay shared in `public/assets/figma/` (dedup by `imageRef` keeps them unique);
+    only the per-design manifest is scoped.
+
+```json
+// plan/PROJ-42/design/figma-manifest.json
+{
+  "11362:27220": "top-phase1-554b0901.png",
+  "11362:27219": "livebg-1b-red-fc490ecb.png",
+  "I11362:27226;3523:5331;1668:8479": "light-6c5e42a8.png"
+}
 ```
 
-- `localPath` defaults to `public/assets/figma/` (relative to the project root)
-- `fileName` follows the pattern: `<layer name in lowercase, spaces replaced with ->-<nodeId>.png`
-  - Example: layer "Banner Top" with nodeId "123-456" → `banner-top-123-456.png`
-- If MCP does not support `download_figma_images`, get the image URL via `get_figma_data`, then notify DEV to download manually and place in `public/assets/figma/`
+**Mode: DEV-provided images (manual download).** When the DEV exports images themselves
+and drops them in `public/assets/figma/`:
+
+1. The DEV names each file per the pattern above (use the download list this skill prints —
+   see Step 2.5 output — which gives the exact filename for each node).
+2. Ensure the design's manifest (per-design path above) maps each relevant nodeId to its file.
+   If the manifest is missing, build it by matching `<layer-slug>` (+ `imageRef`/`nodeId`) to
+   the files on disk.
+3. **Match order for every image node:** (a) manifest entry → (b) a file on disk matching the
+   convention → (c) only if neither, download via MCP. Never re-download what is already there.
+4. If a node has no manifest entry and no matching file → list it for the DEV (do NOT fake it).
+
+**0. Reference render (always, first):** render the target frame itself to
+`public/assets/figma/_reference-<nodeId>.png` via `download_figma_images` (pass the
+frame's own `nodeId`). This is the visual ground truth — keep it open and compare the
+generated UI against it before finishing. Never reproduce a layout from node data alone.
+
+**Export images — the anti-429 strategy (standard, follow exactly):**
+
+> **What triggers 429 is the number of Figma API CALLS, not the number of images.**
+> Downloading the image *bytes* from the returned AWS S3 URLs does NOT count against the
+> Figma rate limit. So: make as FEW Figma calls as possible (ideally 2 total), each
+> requesting MANY images, then pull all the bytes from S3. Never loop one-call-per-image.
+>
+> Rate limits are **tiered per seat** (since 2025-11-17): the render endpoint is Tier 1
+> (10-20/min on Dev/Full seats, ~6/MONTH on View/Collab seats) and shares its bucket with
+> `get_figma_data`. The fills map is Tier 2 (cheaper) — always prefer it.
+
+Figma exposes images through two endpoints — use both, each in a single batched call:
+
+| Source | Endpoint / MCP | Cost |
+|--------|----------------|------|
+| **Image fills** (raster fills, `fills[].type==="IMAGE"`) | `GET /v1/files/:key/images` → returns ALL `imageRef → S3 url` in **one** call | **Tier 2** — cheap, rarely 429 |
+| **Render-only** (VECTOR/BOOLEAN, or image-fill refs missing from the fills map) | `GET /v1/images/:key?ids=<id1,id2,…all…>` → **one** call for ALL ids at once | **Tier 1** — shared bucket with `get_figma_data`; one batched call is fine |
+
+Steps:
+
+1. **Collect & dedupe by `imageRef`.** The same `imageRef` on many nodes = the SAME picture —
+   resolve it once. (Typically cuts 140 nodes → a few dozen unique images.) Name files by ref
+   so reuse and re-runs are stable: image fill → `<imageRef>.png` (or `<layer-slug>-<ref8>.png`
+   for readability); render-only node → `<layer-slug>-<nodeId>.png`.
+2. **Skip what already exists** in `public/assets/figma/` — reuse it, don't re-download. Only
+   fetch the missing set. Re-runs become incremental and nearly free.
+3. **One call for fills:** hit the fills map once → map of `imageRef → S3 url`. Download the
+   missing ones' bytes from S3.
+4. **One call for the rest:** VECTOR/render nodes are gathered into a **single** render call:
+   `…/images/:key?ids=` with ALL their nodeIds comma-joined. Download the returned S3 URLs.
+   (Via MCP: one `download_figma_images` call with all the nodes in its `nodes` array — not one
+   call per node.)
+
+   **How one MCP call maps to REST** (verified against `figma-developer-mcp` v0.13.2 source —
+   `downloadImages()` makes at most 3 REST calls no matter how many nodes you pass):
+   - nodes with `imageRef`/`gifRef` → **1×** fills-map call (Tier 2; skipped if none)
+   - nodes with `nodeId` + `.png` filename → **1×** render call, all ids joined (Tier 1)
+   - nodes with `nodeId` + `.svg` filename → **1×** SEPARATE render call (Tier 1)
+   So: (a) pass EVERYTHING in one MCP call; (b) prefer ONE format for render-only nodes
+   (default `.png`) — mixing `.svg` + `.png` filenames doubles the Tier 1 render calls;
+   (c) the tool dedupes identical `imageRef`s within a call, but it does NOT skip files
+   already on disk and does NOT retry — skip-existing and 429 policy are YOUR job.
+
+4b. **Refs missing from the fills map are dropped SILENTLY.** If a node's `imageRef` isn't in
+   the fills map, the MCP returns no file for it — no error. After the call, diff the files on
+   disk against what you requested; re-request the missing ones in ONE follow-up call as render
+   nodes (`nodeId` only, no `imageRef`). Only nodes still missing after that go to the DEV.
+5. **On `429 Rate limit exceeded`:** read the `Retry-After` header first — it tells you which
+   limit you hit:
+   - **`Retry-After` ≤ 60s** → per-minute leaky bucket. Wait exactly that many seconds, then
+     retry **once**. If the retry also 429s, stop and report (below). Never retry more than once.
+   - **`Retry-After` > 60s (or absent), or `X-Figma-Rate-Limit-Type: low`** → seat/plan quota
+     (a View/Collab seat gets only ~6 Tier 1 calls per MONTH). Do NOT retry. **STOP and report
+     to the DEV:**
+     > ⚠️ Figma 429 while exporting images (got X/Y). retry-after ≈ <n>. This is the per-seat
+     > quota — a new token on the SAME account won't help. Options: use a token from a Dev/Full
+     > seat, switch to `aiflow init -a figma-desktop` (no REST quota), or export manually.
+     > Missing refs/nodeIds: …
+6. **A node may render to `null`** (deeply-nested instance Figma can't render standalone) — this
+   is NOT a rate-limit error. Report that one ref for manual export; don't fake it.
+7. **Prioritise** if large: backgrounds / hero / full-bleed first, then logos/icons, then art.
+
+- **Verify on disk:** list `public/assets/figma/` and confirm a file exists for every unique
+  `imageRef`/`nodeId`. Re-running is cheap (existing files skipped).
+
+**Large / art-heavy design (image nodes > 30):** tell the DEV up front
+(`This frame has N image assets; exporting may take several batched calls`). Do NOT skip
+the export to save time — the real images ARE the design. If the volume is impractical
+in one pass, export backgrounds + key assets, then list the remaining nodeIds for the DEV
+instead of approximating them.
+
+**FAIL LOUD — never approximate.** If `download_figma_images` is unavailable, or images
+fail to export (e.g. 429), **STOP**. Report which refs/nodes could not be exported and ask
+the DEV how to proceed. Do NOT substitute CSS gradients / solid colours for an image node
+and present the result as done — that is the #1 cause of "doesn't match the design".
+
+- Fallback when the MCP tool itself is missing: get image URLs via `get_figma_data`,
+  give the DEV the URL→filename list, and pause until the files are placed in
+  `public/assets/figma/`.
 
 **Record the result:**
 
-After export, save the mapping for use in Step 4:
+After export, persist the mapping to the per-design manifest (`plan/[ticket-id]/design/figma-manifest.json`
+in Gate mode, else `public/assets/figma/figma-manifest.<fileKey>.json`) and load it as
+`imageMap` for Step 4. Key by `nodeId`; **several nodeIds may point to the same file** when
+they share an `imageRef` (reused image — downloaded once). This manifest is the same one the
+DEV-provided-images mode reads, so manual and automatic exports converge on one source of truth:
 
 ```
 imageMap = {
-  "123-456": "public/assets/figma/banner-top-123-456.png",
-  "789-012": "public/assets/figma/icon-star-789-012.png"
+  "123-456": "public/assets/figma/banner-top-554b0901.png",
+  "777-888": "public/assets/figma/banner-top-554b0901.png",  // same imageRef → same file, NOT re-downloaded
+  "789-012": "public/assets/figma/icon-star-9731a243.png"
 }
 ```
 
@@ -127,6 +271,43 @@ Type:    12→text-xs · 14→text-sm · 16→text-base · 18→text-lg · 20→
          400→font-normal · 500→font-medium · 600→font-semibold · 700→font-bold
 ```
 
+### Step 3.7: Build faithfully from the node tree (MANDATORY — do not summarize)
+
+The #1 cause of "doesn't match the design" is generating a *re-interpretation* (a few labels +
+a hand-picked subset of images in a generic centered/flow layout) instead of reproducing the
+**actual node tree**. Follow these rules — they are not optional:
+
+1. **Reconstruct region by region from real child nodes.** Identify the design's regions from
+   the top-level containers (e.g. header frame, the form/panel frame, content sections, footer
+   frame). For EACH region, build its component from its OWN child nodes — every image, text,
+   and button that lives under that region node — placed in the same arrangement the node tree
+   has. Do NOT invent a structure or move elements between regions. "Header has its logo + nav +
+   buttons; the panel has its inputs + buttons; the footer has its logos + links" — keep each
+   asset in the region Figma puts it in.
+
+2. **Pick the background by PAINT ORDER, never by guessing.** Children are painted in array
+   order — a LATER sibling paints ON TOP of an earlier one. The visible full-bleed background is
+   the last opaque full-bleed layer, not the first one you find. Check sibling order + `opacity`
+   + `visible` before choosing which background image to render. (Classic bug: rendering an early
+   red layer when a later blue layer actually covers it.)
+
+3. **No-fabricate / no-omit.** The set of elements you render MUST equal the set of nodes in the
+   frame. Build a quick checklist from the node tree before coding:
+   - Every TEXT string in the frame appears in the UI (don't drop labels; don't translate).
+   - Every image node (from the manifest) is placed in its region (don't omit backgrounds, logos,
+     icons, decorative art).
+   - You add NOTHING that isn't in the frame (no buttons/sections from memory or another frame —
+     e.g. do not add an "Apple" button if only Google/Facebook exist in THIS node).
+   Diff your planned element list against the node tree; reconcile before generating code.
+
+4. **Match each region's container style to the node**, not to a default: background colour/image,
+   light vs dark, logo-as-image vs text, button shape (pill/outline/solid), spacing. Read the
+   node's `fills`, sizes and positions — don't assume a dark card or a text logo.
+
+For a fixed-size, absolutely-positioned design (game UI, marketing LP), prefer reproducing each
+region's internal arrangement closely (relative positions of its children) over forcing a generic
+responsive flow; add responsiveness on top without losing the composition.
+
 ### Step 4: Generate component
 
 **Framework detection** — check in this order:
@@ -334,8 +515,20 @@ const variantClasses = {
 
 ### Step 6: Verify and output
 
+**MANDATORY reference comparison (do this before claiming done — not optional):**
+Open `public/assets/figma/_reference-<nodeId>.png` (the rendered frame from Step 2.5) and the
+generated UI side by side, region by region. For each region (header / panel / sections / footer)
+confirm: same background, same logo (image vs text), same buttons, same text, images in the right
+place. **List every visible difference**, fix it, and re-compare. Do not finish while a region is
+visibly wrong. If you cannot view the reference, say so and ask the DEV to eyeball it — do not
+silently declare a match.
+
 After generation, verify:
 
+- [ ] **Reference compare done**: generated UI matches `_reference-<nodeId>.png` region by region; differences fixed
+- [ ] **No-fabricate**: nothing rendered that isn't in the node tree (no buttons/sections from memory/other frames)
+- [ ] **No-omit**: every TEXT string + every manifest image is present in the right region
+- [ ] **Background** is the correct paint-order layer (the one that actually covers the frame)
 - [ ] Layout matches Figma (flex direction, alignment, gap)
 - [ ] Colors mapping correct (project tokens, or arbitrary values if no match)
 - [ ] Typography correct (size, weight, line-height)
@@ -346,6 +539,8 @@ After generation, verify:
 - [ ] Props typed with TypeScript interface
 - [ ] Image nodes use `<img>` / `<Image>` (do not use CSS `background-image`)
 - [ ] Image files exist in `public/assets/figma/` before submitting code
+- [ ] Compared the rendered result against `_reference-<nodeId>.png` — they look alike
+- [ ] No image node was approximated with a CSS gradient/colour; any node that could not be exported is reported to the DEV, not faked
 
 ---
 
@@ -365,12 +560,17 @@ Always output in order:
 
 ## Rules
 
+- **Build from the node tree, region by region** — reproduce each region (header/panel/sections/footer) from its real child nodes; do NOT re-interpret into a generic centered/flow layout. (Step 3.7)
+- **Background by paint order** — the visible full-bleed background is the LAST opaque layer, not the first; check sibling order + opacity before choosing.
+- **No-fabricate / no-omit** — rendered elements must equal the node set: every text + every manifest image placed; nothing added from memory or another frame.
+- **Reference compare is mandatory** — compare the result against `_reference-<nodeId>.png` region by region and fix every difference before claiming done.
 - **Detect styling tooling first** — do not assume Tailwind; honour CSS Modules / styled-components / vanilla CSS when detected
 - **Prefer design tokens** — map Figma Styles/Variables to project tokens; only hardcode a value when no token matches
 - **Always use** the project's class-merge helper (`cn()` = clsx + twMerge for Tailwind)
 - **Responsive** — if Figma only has 1 breakpoint, default to mobile-first design
 - **Accessibility** — add `aria-label`, `role`, `alt` for interactive and image elements
-- **Image** — detect image fills in Figma node data, export via `download_figma_images` MCP, save to `public/assets/figma/`. Use `<Image>` (Next.js) or `<img>` (React/Vue) with `src` pointing to the exported file. Do NOT use CSS `background-image` for image nodes.
+- **Image** — detect image fills in Figma node data, export via `download_figma_images` MCP: **ONE call with ALL nodes** in its `nodes` array (split only if huge — ~50 ids/call, 5-10s apart). On 429 follow the Retry-After policy in Step 2.5 (≤60s → wait + retry once; larger → report to DEV and stop). Save to `public/assets/figma/`. Use `<Image>` (Next.js) or `<img>` (React/Vue) with `src` pointing to the exported file. Do NOT use CSS `background-image` for image nodes.
+- **Never fake an image** — if export fails or the MCP image tool is missing, STOP and report the failed nodeIds. Do NOT approximate a raster/art node with CSS gradients or solid colours and call it done. Always render the frame to `_reference-<nodeId>.png` first and compare against it.
 - **Icon** — if Figma uses SVG icons, extract SVG or map to lucide-react / heroicons
 
 ---
@@ -385,6 +585,8 @@ Always output in order:
 | `404` on node | Wrong `fileKey`/`nodeId` | Re-copy the frame URL; node-id uses `-` in URL but `:` in API |
 | Empty fills / no styles | Node is a component instance | Fetch the main component, or increase `depth` |
 | `download_figma_images` unsupported | Older MCP preset | Get image URL via `get_figma_data`, download manually to `public/assets/figma/` |
+| `429 Rate limit exceeded` on images | Too many Tier 1 CALLS (metadata probes + per-node loops), or token from a View/Collab seat (~6 calls/MONTH) | Batch ALL ids into one call (Step 2.5). Check `Retry-After`: ≤60s → wait + retry once; hours/days or `X-Figma-Rate-Limit-Type: low` → seat quota — use a Dev/Full-seat token or `figma-desktop` adapter; new token on same account won't help |
+| UI rendered but no images / wrong look | Export skipped or failed; layout faked with CSS | Render `_reference-<nodeId>.png`, export real image nodes (batched), replace CSS approximations with `<img>`/`<Image>` |
 
 ---
 

package/custom/skills/frame-ml-problem/SKILL.md

@@ -85,4 +85,4 @@ If any of the above cannot be answered from the ticket, ask exactly **one questi
 - [ ] Baseline defined (majority class, heuristic, or current production model)
 - [ ] Success threshold quantified (not "as high as possible")
 - [ ] Constraints listed (latency, memory, interpretability, data volume, compliance)
-- [ ] Findings written to `plan/[ticket-id]/ml-problem.md`
+- [ ] Findings written to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path)

package/custom/skills/generate-spec/SKILL.md

@@ -6,6 +6,8 @@ keywords: spec, plan, implementation, tdd, coding plan
 
 # Implementation Plan — Gate 2
 
+> ⚠️ **Only invoke for `feature`, `bug-fix`, `refactor`, `investigation`, and `documentation` tasks.** For `gen-doc` tasks, skip this skill entirely — Gate 2 goes directly to document generation, no `plan.md` needed.
+
 > **GATE 2: Runs after Gate 1 (requirement document) has been APPROVED by DEV.**
 >
 > Principle: AI uses the approved requirement document to create a detailed implementation plan with TDD steps. DEV confirms the plan before coding begins.
@@ -32,6 +34,20 @@ When updating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fas
 
 Read `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` — use the chosen approach, file list, and testing plan as input.
 
+### Step 1.5: Read Design Context (if present)
+
+If `plan/[ticket-id]/design/design-context.md` exists (UI ticket from Gate 1):
+
+1. Read `design-context.md` — do NOT call Figma MCP again; the design is already cached.
+2. Feed these into the TDD plan:
+   - **Component tree** → one build task per component (with its variants/states)
+   - **Design tokens table** → mapping notes per component (color/type/space → project token)
+   - **Image Map** → a task to copy images from `plan/[ticket-id]/design/images/`
+     to `public/assets/figma/` before the component task that consumes them
+3. Each UI task must carry an acceptance note: "matches design-context.md (layout, color, type, spacing)".
+
+If the file is absent → skip this step (non-UI ticket).
+
 ### Step 2: Create Implementation Plan
 
 **INVOKE:** `superpowers:writing-plans`
@@ -56,6 +72,9 @@ Create a detailed step-by-step plan based on the requirement document:
 ```
 ```
 
+> For UI tasks, reference the exact node/component from `design-context.md` in the Task column
+> (e.g. "Build UserCard — nodeId 78-910"). Add an image-copy task when the Image Map is non-empty.
+
 ### Step 3: GATE 2 — Present Plan & Start Coding
 
 ```markdown

package/custom/skills/read-study-requirement/SKILL.md

@@ -76,7 +76,9 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
 
 5. Display Gate 1 prompt and wait for `APPROVED`.
 
-> After APPROVED, proceed to Gate 2. The lean doc is intentional — Gate 2 plan will fill in the details.
+> After APPROVED, proceed to Gate 2.
+> - **`gen-doc` tasks:** Gate 2 generates the output document immediately (no `plan.md`, no TDD). Self-review + task-summary.md are created automatically.
+> - **All other tasks:** Gate 2 plan fills in the implementation details.
 
 ---
 
@@ -111,6 +113,63 @@ Do this investigation **before** asking any questions. Come prepared.
 
 ---
 
+### Step 1.5: Detect & Read Figma Design (UI tickets only)
+
+Run this only when the ticket touches UI. Skip entirely for non-UI tickets.
+
+1. **Detect a Figma URL** in this order:
+   - `current.json` → `description`
+   - `current.json` → `supplementaryContext[]` items
+   - Pattern: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
+2. **No URL but ticket looks like UI** (mentions screen, page, component, layout, "theo design"):
+   ask the DEV **once** to paste a Figma URL. If DEV skips → write "Design: TBD" in the
+   Design Analysis section and continue. Do NOT ask again.
+3. **URL found** → invoke `figma-to-component` Steps 0–2.5 (verify MCP, read design,
+   detect & export images). Then persist the shared artifact:
+   - Create `plan/[ticket-id]/design/`
+   - Save raw response to `plan/[ticket-id]/design/nodes.json` (cache for later gates)
+   - Save exported images to `plan/[ticket-id]/design/images/`
+   - Write `plan/[ticket-id]/design/figma-manifest.json` (nodeId → image file) — per-ticket,
+     NOT a shared global manifest
+   - Write `plan/[ticket-id]/design/design-context.md` using the template below
+4. **Figma MCP not connected** → tell DEV to run `aiflow init -a figma` (or `-a figma-desktop`),
+   mark Design Analysis as "⚠️ pending MCP", and continue with the non-UI parts of the requirement.
+   Do NOT abort the ticket.
+
+**`design-context.md` template:**
+
+```markdown
+# Design Context: [ticket-id]
+
+**Figma URL:** <url>   **fileKey:** xxx   **nodeId:** 123-456
+**Fetched:** [YYYY-MM-DD]   **Adapter:** figma (REST) | figma-desktop
+
+## 1. Layout Structure
+- Node tree: Frame > Header / Body > Card[] / Footer
+- Flex direction, gap, padding, alignment per region
+
+## 2. Design Tokens
+| Type | Figma value | Project token |
+|------|-------------|---------------|
+| Color | #3B82F6 | blue-500 / --color-primary |
+| Type  | 16/600    | text-base font-semibold |
+| Space | 16px      | p-4 / gap-4 |
+
+## 3. Components to build
+- [ ] UserCard (variants: default, hover) — nodeId 78-910
+- [ ] Header — nodeId 12-3
+
+## 4. Image Map
+| nodeId | layer | file |
+|--------|-------|------|
+| 123-456 | Banner Top | design/images/banner-top-123-456.png |
+
+## 5. Notes
+- Anything not mapped 1:1 (custom fonts, effects…)
+```
+
+---
+
 ### Step 2: Clarify Requirements via Q&A
 
 Ask clarifying questions directly — **one question at a time**, wait for the developer's response before asking the next.
@@ -227,6 +286,15 @@ Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 
 ---
 
+## Design Analysis (UI tickets only)
+
+- **Source:** [Figma URL or "TBD" or "⚠️ pending MCP"]
+- **Artifact:** `plan/[ticket-id]/design/design-context.md`
+- **Summary:** layout, key components to build, design tokens to map, images exported
+- **Impact on approach:** how the design shapes the proposed solution
+
+---
+
 ## 4. Impact Analysis
 
 **Impact Level:** 🟢 Low / 🟡 Medium / 🔴 High