F-MCP Intent Router — Universal Entry Gate

Neden Var?

F-MCP Bridge'in 20+ SKILL'i var. Her biri farklı bir iş yapar (ekran oluşturma, denetim, kütüphane inşası, vb.) ve her biri farklı input'lar ister. Claude kullanıcı "figma'da ekran yap" dediğinde:

1. Hangi SKILL lazım? (generate-figma-screen mi generate-figma-library mi?)
2. Hangi bilgiler eksik? (device? DS? benchmark? içerik bölümleri?)
3. Kullanıcı ne onay verdi?

Bu SKILL bu üç soruyu upstream çözer. Claude intent'i netleştirmeden hiçbir figma_execute, figma_create_frame, figma_clone_screen_to_device çalıştırmaz. "Hızlı ve doğru" kuralı: yanlış varsayım yapmaktansa 1 soru sormak her zaman daha hızlıdır.

Protokol (9 Adım — v1.9.1+)

Kullanıcı F-MCP ile ilgili herhangi bir talep yaptığında Claude bu 9 adımı SIRAYLA uygular. Hiçbir adım atlanmaz.

🚨 Adım 0 — DS GATE + BLANK FILE CHECK (v1.9.7+ MUTLAK İLK KAPI)

Herhangi bir intent analysis veya figma_ tool çağrısından ÖNCE:*

1. figma_get_status çağır — plugin bağlı mı, response'ta _bootstrap varsa direktifleri OKU (v1.9.7)
2. .claude/design-systems/active-ds.md dosyasını oku
3. Status: alanını kontrol et:
   • ✅ Aktif → DS net, Blank File Sub-Check'e geç (madde 5)
   • ❌ Henüz seçilmedi VEYA dosya yok → kullanıcıya DS sorusu sor (madde 4)
4. DS Sorusu (klasik): "Aktif bir design system belirlenmemiş. Hangi DS ile ilerlemek istersiniz? (örn. Material / Apple HIG / Tailwind UI / kendi library'niz)"

5. BLANK FILE SUB-CHECK (v1.9.7, ZORUNLU): figma_get_design_system_summary çağır.

   • components === 0 && componentSets === 0 && variableCollections.length === 0 ise BOŞ DOSYA tespit edildi.
   • _nextStep: "BLANK_FILE_DIALOG_REQUIRED" response'ta görünüyorsa, kullanıcıya 4 seçenek sun (AskUserQuestion tek call, 4 option):

     Q: "Bu dosyada henüz Design System yok. Nasıl ilerleyelim?"
     (a) Team library import — "Hangi library? Örn. Material 3, iOS HIG, Tailwind UI, veya kendi library'niz"
     (b) Mini DS kur otomatik — figma_create_mini_ds tool'u çağrılır (12 color + 8 sizing + 3 text style + Button/Input/Card)
     (c) Referans DS kopyala — "Material 3 template / iOS HIG template"
     (d) DS'siz ilerle — linter tolerant mode, hardcoded değerler kabul (explicit acceptance)

   • Seçim yapılmadan figma_execute createFrame YASAK. Claude ham createFrame denerse plugin _DESIGN_SYSTEM_VIOLATIONS_BLOCKING flag'i döndürür, retry zorunlu olur.
   • Kullanıcı "(b)" derse Claude figma_create_mini_ds({ primaryColor, fontFamily, name }) tek tool çağrısı yapar, sonra ekran üretimine geçer.
   • Kullanıcı "(a)" derse Claude figma_get_library_variables(libraryName) ile listeleme yapar, seçenek sunar.

   ⚠️ v1.9.9+ (G26c — Token Setup Öneri): DS seçili VE component cache boşsa VE FIGMA_REST_TOKEN env yoksa Claude kullanıcıya tek özet soruda 3 yol önerir:

   "Component discovery hızlandırma yolları: (1) Hızlı: Figma Assets panel'den 1 Button + 1 NavigationTopBar sürükle Page X'e, ben oradan mainComponent.key alırım (Hybrid Quick-Start) (2) Otonom: FIGMA_REST_TOKEN setup et (/setup-rest-token komutu), tüm component'leri REST ile çekerim (Rule 24.1) (3) Bekle: figma_search_components ile instance scan yapayım (~30-60sn, Rule 24.2)"

   Kullanıcı seçer → ilgili path: (1) G26b Hybrid Quick-Start, (2) /setup-rest-token + Rule 24.1, (3) G19 Step 3.1 cache populate.

6. Seçim sonrası active-ds.md'yi güncelle (Status: ✅ Aktif, Primary Library: <isim>), sonra Adım 1'e geç.
7. Multi-Library Parse (v1.9.8+): active-ds.md'de "Secondary Libraries" bölümü varsa parse et:
   • Tabloda 1+ satır varsa, her library için ~/.claude/data/fcm-ds/<file-key>/ dizinini listele (cache mevcut mu kontrol).
   • Eksik cache varsa kullanıcıya bildir: "Secondary library <X> için cache yok — /ds-sync <X> veya /add-library ile populate edin."
   • User-local ~/.claude/data/fcm-ds/active.md v2 multi-library schema'sı (Primary + Secondary liste) destekleniyor — eski single-key format da geriye uyumlu.

Neden bu kadar katı:

• DS belirsizken figma_search_assets, figma_get_file_data, figma_get_library_variables çağırmak = kullanıcının istemediği library'leri enumere etmek = token israfı + UX bozulması
• Test geçmişinde gözlenen hata: benchmark Figma dosyasının 24+ library component'i enumere edildi, sonra "hangi DS?" soruldu. Bu sıra YASAK.

Bu adımda çağrılabilen tek Figma tool'u:

• ✅ figma_get_status() — plugin bağlantı kontrolü, DS bağımsız
• Başka HİÇBİR figma_ YASAK.* figma_get_file_data, figma_search_assets, figma_search_components, figma_get_library_variables, figma_get_variables, figma_get_styles — hepsi YASAK ta ki Adım 0 geçilene kadar.

Adım 1 — Intent Analysis

Kullanıcı talebini oku. Anahtar kelimeleri tara:

Not (v1.8.3+): inspiration-intake bir ön-işleme skill'idir. Kullanıcı bir Figma benchmark linki, internet görsel linki veya sohbete yüklenmiş görsel ile gelirse önce bu skill çalıştırılır (structural_intent JSON üretir, DEĞER çıkarmaz), sonra çıktısı generate-figma-screen'in reference_benchmark parametresine beslenir. v1.8.2 build-from-scratch kuralı ile tam uyumludur — clone değil, inspiration.

Mode tespiti:

• Figma URL pattern (figma.com/file/...?node-id=) → inspiration-intake (source_type: figma_url)
• Dribbble/Behance/genel HTTP URL → inspiration-intake (source_type: image_url, WebFetch fallback'li)
• Kullanıcı mesajında görsel attachment → inspiration-intake (source_type: image_uploaded)

Adım 2 — State Files Check

Claude her seferinde üç state dosyasını okur:

1. .claude/design-systems/active-ds.md
   → Aktif DS belirtilmiş mi? (örn "❖ Ana-DS")
   
2. .claude/design-systems/last-intent.md
   → Son tamamlanan intent nedir? (device, ds, skill, inputs)
   
3. .claude/design-systems/intent-history.md
   → Son 5 intent nedir? (LRU)

Bu dosyalar Claude'un "öncekiyle aynı mı?" sorusu sormasını sağlar.

⚠️ v1.9.9+ Tool Budget Disiplini (G23 — Defensive Exploration Yasağı):

• ✅ 3 state dosyasını TEK Read Multiple Files çağrısında aç. Ayrı ayrı Read Text File çağrıları YASAK.
• ✅ Cache dizinlerini (.claude/design-systems/, ~/.claude/data/fcm-ds/) tek List Directory ile gör. Sequential alt-dizin traversal (A → A/B → A/B/C) YASAK — tek recursive list + Read Multiple Files ile gerekli dosyalar.

Red flag patterns (BLOCKING — Adım 6 özetine geç, discovery'yi durdur):

• Aynı dizin 2+ kez list edilirse → defensive exploration → budget exhaustion riski
• Aynı dosya 2+ kez read edilirse → state yeterince bilgi veriyor, yeterli
• figma_get_* + figma_search_* toplam 8+ çağrı (discovery-counter WARN threshold) → uretime gec

Claude bu pattern'lerden birini tespit ederse, eksik input varsa Adım 6 özet + onay'a geç; yoksa Adım 7 execute'a geç. Daha fazla keşif YASAK.

Adım 3b — Approach Karar Mantığı (v1.8.2+)

Target skill generate-figma-screen ise, yaklaşım ayrımı yap. Kullanıcının cümlesinde şu keyword'leri ara ve approach input'unu doldur:

⭐ ÖNEMLİ: Eğer kullanıcı "3 alternatif" veya "varyasyon" derse, approach = build-from-scratch DEFAULT'tur. figma_clone_screen_to_device tool'u ASLA önerilmez. Clone tool'u kopyalama yaparken benchmark'ın mevcut yanlışlıklarını (hardcoded rectangle, missing token binding, non-responsive layout) kopyalar. Bu kullanıcının istediği gerçek varyasyon yaratmaz.

Eğer approach = build-from-scratch ise, Claude'un akış haritası:

figma_search_assets ile Ana-DS bileşenlerini bul
  ↓
figma_get_library_variables ile DS token key'lerini topla
  ↓
figma_execute ile bölüm bölüm inşa et:
  - figma.createFrame() + layoutMode + padding (variable binding)
  - importComponentByKeyAsync + createInstance (DS instance'lar)
  - setBoundVariableForPaint (fills token bind)
  - setBoundVariable (padding/itemSpacing/cornerRadius token bind)
  - importStyleByKeyAsync + setTextStyleIdAsync (text style bind)
  - appendChild sonrası layoutSizingHorizontal/Vertical = FILL
  ↓
figma_validate_screen ile skor kontrolü (≥80)

Özet + Onay ekranında göster:

📋 Yaklaşım: build-from-scratch ⭐
 Bu kullanıcının "alternatif tasarım" isteğine uygun doğru yol.
 Clone tool kullanılmayacak. Her alternatif sıfırdan Ana-DS bileşenleriyle inşa edilecek.
 Benchmark (139:xxx) sadece ilham kaynağı — kopyalanmayacak.

⚠️ v1.9.9+ Approach Otomatik Parse (G25):

Eğer reference_benchmark input dolu ise (görsel upload, Figma URL veya node ID), approach otomatik belirlenir — kullanıcıya "A 1:1 mı B referans mı?" SORMA:

Tablodan seç, Adım 6 özetine direkt yaz (örn. "Yaklaşım: build-from-scratch + reference override").

Override: Kullanıcı explicit "birebir kopyala" / "klonla" / "aynısı olsun" derse clone-to-device'a override. Explicit "referans al" / "ilham" / "değiştir" derse build-from-scratch + reference override.

Adım 3 — Decide Target Skill

Adım 1'deki keyword eşleşmesi + Adım 2'deki state bilgisi → tek bir SKILL seç.

Karar mantığı:

IF user request EXACTLY matches one keyword pattern
   → Select that skill (single match, no question)
   
ELSE IF user request matches 2+ patterns (ambiguous)
   → Ask user: "Şunlardan hangisini yapayım?"
   → Use AskUserQuestion with matched skills as options
   
ELSE IF user request is generic ("figma'da bir şey yap")
   → Ask user: "Tam olarak ne yapmak istiyorsun?"
   → Offer top 5 common skills as options
   
ELSE (no match)
   → Ask user to clarify intent in natural language

⚠️ v1.9.9+ Hybrid Quick-Start (G26b):

Target skill generate-figma-screen veya apply-figma-design-system ise VE user prompt'ta şu pattern'lerden biri varsa component discovery hızlandırılır:

• "seed component var" / "manuel yerleştirdim" / "X'i zaten ekledim" / "button/appbar sürükledim"

Bu durumda:

• ❌ G19 Step 3.1 Cache Populate ATLA (full scan gereksiz)
• ✅ PRIMARY (v3.3+): figma_enumerate_published_components(libraryFileKey, filter) ← registry'deki file key ile REST'ten canlı liste (dosya açıksa figma_enumerate_library_components daha hızlı). Tek call'da componentKey listesi.
• ✅ FALLBACK (registry boş / REST token yok): figma_search_assets(currentPageOnly=false) → mevcut instance'lardan mainComponent.key topla
• Discovery mini-mode: 1-3 call

Component discovery öncelik sırası (Rule 24 köprüsü):

1. Rule 24.0 Live Enumerate (figma_enumerate_published_components / figma_enumerate_library_components — v3.3+ ana yol) — G26c
2. Hybrid Quick-Start (seed varsa — 2-3 tool call) — G26b
3. Rule 24.1 REST API (FIGMA_REST_TOKEN setup ise — 1-2 call)
4. Rule 24.2 Cache (G19 Step 3.1 auto-populate — 3-5 call)
5. Rule 24.3 Primitives fallback (G17 ADVISORY — BLOCKING değil)

Adım 4 — Read Target Skill Metadata

Seçilen SKILL'in frontmatter'ını oku. required_inputs bloğunu parse et:

required_inputs:
  - name: device
    type: enum
    options: ["iPhone 17", "iPhone 16 Pro Max", ...]
    question: "Hangi device boyutunda olsun?"
    required: true
    default_source: ".claude/design-systems/last-intent.md#device"
  - name: design_system
    type: from_state
    source: ".claude/design-systems/active-ds.md#Library Name"
    required: true
  - name: reference_benchmark
    type: node_id_or_none
    question: "Referans benchmark node var mı?"
    required: false
    affects: ["screen_type", "sections"]  # verilirse bunlar atlanır
  - name: screen_type
    type: enum
    ...
    skip_if: "reference_benchmark != none"

Input türleri:

• enum — Kullanıcı seçenekten seçer
• from_state — State dosyasından oku, yoksa fallback_question sor
• node_id_or_none — Figma node ID veya "yok"
• string — Serbest metin
• string_list — Virgülle ayrılmış liste
• boolean — Yes/No

Özellikler:

• required: true/false — Zorunlu mu?
• default_source — State'ten default çekilir
• default — Sabit default değer
• skip_if — Koşullu atlamak (başka input'un değerine bağlı)
• affects — Bu input verilirse atlanacak diğer input'ları belirtir

Adım 5 — Gather Missing Inputs (Smart Skipping)

Claude her required_inputs girdisini şu mantıkla işler:

FOR each input in required_inputs:
  IF input has default_source AND state file value exists:
    → USE state value, don't ask
  
  IF input has default:
    → USE default, don't ask
  
  IF user request already mentions this input (parse from prompt):
    → USE parsed value, don't ask
  
  IF another input has affects: [this_input_name] AND that input was set:
    → SKIP this input (will be derived from affecting input)
  
  IF input has skip_if AND condition evaluates true:
    → SKIP this input
  
  ELSE:
    → ADD to missing list

Missing list'teki tüm soruları TEK AskUserQuestion çağrısında toplayıp sor. Max 4 soru/çağrı (AskUserQuestion limiti). 5+ soru gerekiyorsa 2 ayrı çağrı yap, ama ÖNCE kritik 4'ü sor, sonra kalanları.

v1.9.5 Elicitation Kuralı (SERT)

• Maks 1 AskUserQuestion çağrısı tüm oturum boyunca. Tekrar soru sormak yasak — state'ten veya context'ten çıkar.
• "devam et" / "tamam" / "ok" / "yap" sonrası soru YASAK. Kullanıcı onay verdi → üretime geç.
• User prompt'u anlamlıysa (spesifik ekran adı, boyut, DS veriliyorsa) hiç sorma, direkt planla ve göster.
• "Sen seç" cevabı alırsan: mantıklı default kullan (iPhone 17, mobile, single variant, active DS).
• Sorulan her soru ≤30 kelime — uzun elicitation yasak.
• Soruyu sormanın context maliyeti ≥ yanıtın değeri mi? Değilse sorma.

v1.9.9+ User Memory Uyum Kuralı (SERT — G21)

Kullanıcının MEMORY.md'sinde "verify assumptions" / "doğrula" / "sorma önce" / "assumption yapma" gibi bir feedback memory varsa:

• ❌ YANLIŞ: Her input için ayrı AskUserQuestion → 4 ayrı soru ile memory'ye uymaya çalışma. Bu tool-use israfıdır, Claude Desktop'ta session başına tool limit'e erken çarpar.
• ✅ DOĞRU: Tek özet soru (Adım 6 formatı) bu memory'yi TAM karşılar. "Verify assumption" gereksinimi tek özet + onay ile sağlanır. Kullanıcı özeti görüp [✅ Evet / ✏️ Değiştir / ❌ İptal] seçtiğinde "assumption verify" edilmiş sayılır.

Priority resolution: User memory kuralı ne diyor değil, ne gerektiriyor üzerinden yorumlanır. "Verify" gereksinimi tek özet onayla karşılanır; birden fazla AskUserQuestion çağrısı memory'ye fazladan uymak değil, verim kaybıdır.

Örnek (doğru davranış):

User memory: "Do not assume anything, verify with me first." User prompt: "Ana-DS ile iOS ödeme sayfası" (device/mode belirsiz)

❌ YANLIŞ: 4 ayrı soru (Q1 device, Q2 mode, Q3 approach, Q4 ölçek) ✅ DOĞRU: Tek Adım 6 özet: "Anladım — Ana-DS + iOS payment. Netleştirmem gereken: device (iPhone 17 default), mode (Light default), approach (build-from-scratch + reference override), ölçek (tek scroll). Onaylıyor musun? [✅ Bunlarla başla / ✏️ Değiştir / ❌ İptal]"

v1.9.6 Negative Intent Detection (KRITIK)

Kullanıcı şu paternlerle negatif/dışlayıcı talimat verebilir — bunları ZORUNLU parse et:

Örnek:

Kullanıcı: "Ana-DS Alt 3'e bakma, sıfırdan yeni bir Anasayfa tasarla"

PARSE:
  - exclude_references: ["Ana-DS Alt 3", "12:400"]  (Ana-DS Alt 3 frame ID'si de dahil)
  - start_fresh: true
  - target_screen: "Anasayfa"
  - DS: active-ds.md'den çek

SONUÇ:
  - Ana-DS Alt 3 sayfası referans alınmaz
  - Mevcut "Ana-DS Alt 3 — Anasayfa" frame'i açılmaz, screenshot alınmaz
  - ideation sayfası (ilham) kullanılabilir ama Ana-DS Alt 3 bölümü atlanır

Anti-pattern: Kullanıcı "Ana-DS Alt 3 atla" dedikten sonra onu screenshot alıp referans göstermek. v1.9.6'da bu explicit yasak — pre-flight'ta exclude_references kontrolü yapılır.

State persist: exclude_references last-intent.md'ye yazılır; aynı oturum boyunca geçerli.

Örnek — generate-figma-screen:

Kullanıcı: "Ana-DS ile ekran yap"

State okuma:
  - active-ds.md → "❖ Ana-DS" ✓ (design_system sorulmaz)
  - last-intent.md → yok

Missing inputs:
  1. device (zorunlu)
  2. reference_benchmark (opsiyonel ama soruyu sor)
  3. screen_type (zorunlu, reference'a bağlı)
  4. sections (zorunlu, reference'a bağlı)
  5. variants (opsiyonel, default "single")

AskUserQuestion (tek çağrı, 4 soru):
Q1: Hangi device? (iPhone 17 / 16 Pro Max / Android / iPad / Custom)
Q2: Referans benchmark var mı? (Evet node ID / Hayır template kullan)
Q3: Ekran tipi? (dashboard / list / detail / form / login)
Q4: Ana bölümler? (kısa liste yaz)

Adım 6 — Summary + Explicit Confirmation Gate

Tüm input'lar toplandıktan sonra Claude AYRI bir AskUserQuestion çağrısıyla onay ister:

"Anladım, şunu yapacağım:

 🎯 Skill: generate-figma-screen
 📱 Device: iPhone 17 (402×874)
 🎨 DS: ❖ Ana-DS
 📋 Reference: 12:345 (Vadesiz TL Hesabı)
 🧩 Yaklaşım: clone-to-device with Ana-DS token binding
 📊 Çıktı: 1 ekran 'Vadesiz TL - iPhone 17'
 ⏱️ Tahmini süre: 20 saniye

 Onaylıyor musun?"

Seçenekler:
 [✅ Evet, başla]
 [✏️ Değiştir (hangi alan?)]
 [❌ İptal]

Bu adım ATLANMAZ. Fast path dahil HER durumda onay sorusu sorulur. İstisna: sadece "önceki ile aynı" cevabı gelen repeat path, tek adım onay.

⚠️ v1.9.9+ Kural (G22 — Single-Question Consolidation):

Eksik input'lar varsa özet + eksik input'lar AYNI AskUserQuestion call'ında sunulur. Birden fazla AskUserQuestion çağrısı YASAK (G21 ile uyumlu). Örn:

"Anladım: Ana-DS + iOS payment + build-from-scratch + reference override.

Netleştirmem gereken: (a) Device: iPhone 17 (default, Ana-DS tablosundan) / 16 Pro / 16 / 13-14 (b) Mode: Light (default) / Light+Dark

Onaylıyor musun? [✅ Default'larla başla / ✏️ Değiştir (a veya b) / ❌ İptal]"

Kullanıcı "Değiştir" derse sadece o seçim için tek follow-up AskUserQuestion — yine tek call. Default'larla onay → Adım 7 execute.

Adım 7 — Execute Target Skill

Onay alındıktan sonra:

1. Seçilen SKILL'in SKILL.md dosyasını yükle (Skill tool ile)
2. Kullanıcıdan topladığın input'ları context'te tut
3. SKILL'in kendi Step 1-N akışını çalıştır

ÖNEMLİ: Target SKILL zaten Step 0 (DS context check), Step 1-N (iş), Step N+1 (self-audit via figma_validate_screen) yapacak. Intent router'ın işi sadece input gathering ve onay — execution target SKILL'e bırakılır.

Adım 8 — Persist Intent

SKILL tamamlandıktan sonra (başarılı veya başarısız):

1. .claude/design-systems/last-intent.md güncelle:

# Last Intent
**Updated:** 2026-04-14 14:23

## Selected Skill
generate-figma-screen

## Inputs
- device: iPhone 17
- design_system: ❖ Ana-DS
- reference_benchmark: 12:345
- (other inputs)

## Result
- output_node: 12:500
- validation_score: 95/100
- duration: 18s
- status: ✅ Success

## User Confirmation
✅ Onaylandı 14:23

2. .claude/design-systems/intent-history.md başına yeni entry ekle (LRU 5, eskisi silinir).

Fast Paths (Akıllı Kısayollar)

Fast Path 1 — Detaylı Talep

Kullanıcı talebi zaten tüm input'ları içeriyorsa (örn. "12:345'yi iPhone 17'ye Ana-DS ile klonla"), Adım 5 atlanır. Direkt Adım 6 (onay) → Adım 7 (execute).

Örnek:

Kullanıcı: "12:345'yi iPhone 17'ye Ana-DS ile klonla"

Parse:
  - skill: generate-figma-screen (klonla keyword)
  - device: iPhone 17 (explicit)
  - ds: Ana-DS (explicit + active-ds.md confirm)
  - reference: 12:345 (explicit)
  - variants: single (default)

→ Direkt Adım 6: onay sor
→ Kullanıcı "Evet" → Adım 7: execute

Fast Path 2 — Repeat

Kullanıcı "bir tane daha yap" / "aynısını yap" derse, last-intent.md'yi oku ve tek bir soruyla onay al:

"Öncekiyle aynı ayarlarla mı devam edeyim?
 
 • Skill: generate-figma-screen
 • Device: iPhone 17
 • DS: ❖ Ana-DS
 • Yaklaşım: clone-to-device

 [✅ Aynı]
 [✏️ Değiştir]
 [❌ İptal]"

Fast Path 3 — Partial Reuse

Kullanıcı "aynı ama Android'de" derse, last-intent.md'nin çoğunu reuse et, sadece değişen alanları sor:

State'ten reuse: ds, reference, type, sections, variants
Kullanıcıdan sor: device = Android (hangisi? - Compact/Medium)

Ambiguity Handling

Durum 1 — Belirsiz talep

Kullanıcı: "figma'da bir şey yap"

Router: Tek SKILL eşleşmedi.

AskUserQuestion:
"Ne yapmak istediğini netleştirebilir misin?
 (a) Yeni ekran oluştur
 (b) Mevcut ekranı DS'ye uydur (reconcile)
 (c) Dosyayı denetle / rapor çıkar
 (d) Figma → kod üret
 (e) Başka — açıklayarak yaz"

Durum 2 — Çoklu eşleşme

Kullanıcı: "Ana-DS ile bir şey yap"

Router: 4 SKILL match (create, apply, audit, library).

AskUserQuestion:
"Ana-DS ile ne yapmak istiyorsun?
 (a) Yeni ekran oluştur (generate-figma-screen)
 (b) Mevcut ekrana Ana-DS uygula (apply-figma-design-system)
 (c) Ana-DS uyumu denet (audit-figma-design-system)
 (d) Ana-DS library'ye component ekle (generate-figma-library)"

Durum 3 — Yanlış SKILL seçme riski

Kullanıcı "token oluştur" derse:

• Yanlış: generate-figma-screen (token yok o)
• Doğru: generate-figma-library (DS kütüphane inşası, içinde token creation var)
• Alternatif: design-token-pipeline (external token sync)

Router sorar:

"Token işi için:
 (a) Figma'da yeni variable/token oluştur (library)
 (b) Kod tarafındaki token'ları Figma'ya sync et (pipeline)
 (c) Figma token'larını CSS/Swift/Kotlin'a export et (pipeline)"

Tool Failure Recovery Protocol (v1.8.2+)

Tool çağrısı başarısız olursa (timeout, error, unexpected result), şu protokolü izle. ASLA körü körüne retry yapma — çöp birikir.

Retry Kuralları

1. İlk hata (timeout/error): 1 kez retry et, farklı parametre ile:
   • figma_clone_screen_to_device timeout → küçük source node dene veya farklı targetDevice
   • figma_execute timeout → kod parçalarına böl, timeout param artır (max 30000)
   • figma_validate_screen timeout → minScore düşür veya daha küçük alt-node'a uygula
2. İkinci hata (aynı tool): DUR. Kullanıcıya git, strateji iste.
3. ASLA aynı tool + aynı param ile 3 kez çağırma.

Orphan Cleanup (ZORUNLU)

Clone/create tool'ları timeout aldıysa dosyada yarım iş kalmış olabilir. Her başarısız write-tool denemesi sonrası Claude cleanup protokolünü çalıştırır:

1. figma_get_file_data(depth=1, verbosity="summary") ile hedef sayfayı tara
2. Son 5 dakikada oluşmuş, beklenmedik isimde veya duplicate node'ları tespit et
3. Her şüpheli node için figma_get_design_context ile detayına bak (content sağlamı mı?)
4. Kullanıcıya listele:

   ⚠️ Timeout sonrası şu orphan node'ları buldum:
    1. 12:600 "Hesaplarım — Hero Card — iPhone 17" (yarım, child count: 4)
    2. 12:601 "Hesaplarım — Hero Card — iPhone 17" (yarım, child count: 8)
   
   Silmemi ister misin?
   [✅ Sil] [👁️ Önce screenshot göster] [❌ Kalsın]

5. Onay sonrası figma_execute ile node.remove() uygula

Failure Escalation Template

2+ retry sonrası kullanıcıya şu formatla git:

⚠️ Alternatif N ({name}) oluşturulamadı.

**Denenen:**
- figma_clone_screen_to_device (2 timeout)
- figma_execute manual fallback (failed)

**Orphan node'lar (dosyada kaldı):** [list of IDs]

**Seçenekler:**
[A] Orphan'ları sil ve farklı kaynak node ile yeniden dene
[B] Orphan'ları sil ve bu alternatifi atla, Turn N+1'e geç
[C] Dur, test iptal — orphan'ları manuel sileyim

Benchmark Selection Validation (v1.8.2+)

Kullanıcı benchmark node ID verdiğinde, Claude HEMEN klonlamaya geçme. Önce benchmark'ı DOĞRULA:

Adım 1: Node Tipini Kontrol Et

figma_get_design_context(nodeId=<user_input>) çağır ve node.type'ı kontrol et:

Eğer tip PAGE ise → Altındaki child'ları listele, kullanıcıya sor

Verdiğin node bir sayfa (PAGE). Altında şu adaylar var:

 1. Vadesiz TL — Ana-DS v10 (Hero Card)       — 4 child (temiz, hızlı clone)
 2. Vadesiz TL — Ana-DS v11 (Segmented)       — 5 child (temiz, hızlı clone)
 3. Vadesiz TL — Ana-DS v12 (Dark Header)     — 3 child (temiz, hızlı clone)
 4. Hesaplarım                              — 14 child (kaba draft, yavaş)

Hangisi asıl benchmark? Önerim: 1/2/3 (temiz v-numaralı alternatifler).

Eğer tip FRAME ise → childCount kontrol et

• ≤ 5 child: Kullan, hızlı
• 5-15 child: Kullan ama kullanıcıyı bilgilendir: "Benchmark orta büyüklükte, clone ~30s sürebilir"
• 15-25 child: Uyar:

  ⚠️ Benchmark {N} child içeriyor. Clone 60+ saniye sürebilir.
  
  Önerim:
  [A] Yine de kullan (sabırlı ol)
  [B] Parent'ın siblings'ini tara, daha küçük bir alternatif öner
  [C] Farklı bir benchmark seç

• 25+ child: DUR. Otomatik parent'ın siblings'ini tara, daha küçük alternatifler öner. Büyük benchmark'ı onaysız kullanma.

Eğer tip başka ise (INSTANCE, COMPONENT, vs.) → Hata

"Benchmark FRAME olmalı. {type} tipinde node benchmark olarak kullanılamaz."

Adım 2: Siblings Tara (PAGE/FRAME için)

Parent'ta sibling node'lar varsa, ✦, v10, v11, alternative, variant gibi keyword'lerle filtrele ve kullanıcıya alternatif öner:

Verdiğin benchmark: Hesaplarım (14 child)
Aynı parent'ta daha küçük ve temiz alternatifler var:
 - v10 Hero Card (4 child)
 - v11 Segmented (5 child)
Bunlardan birini kullanmak ister misin?

Adım 3: Responsive/Auto-Layout Ön-Kontrol

Benchmark'ı klonlamadan önce onun zaten responsive olup olmadığını kontrol et:

// Claude figma_execute ile çalıştırır:
var n = await figma.getNodeByIdAsync(benchmarkId);
return {
  layoutMode: n.layoutMode,
  primaryAxisSizingMode: n.primaryAxisSizingMode,
  counterAxisSizingMode: n.counterAxisSizingMode,
  hasAutoLayout: n.layoutMode !== 'NONE',
};

Eğer layoutMode === 'NONE' ise uyar:

⚠️ Bu benchmark'ın auto-layout'u yok (layoutMode=NONE).
   Clone yaparsan yeni ekran da responsive olmayacak.
   
   Önerilen: clone yerine Step 5 "Build from Scratch" akışı kullan.

Anti-Patterns (Claude'un Yapmaması Gerekenler)

❌ YANLIŞ: Kullanıcı "ekran yap" deyince direkt figma_create_frame çağırmak. ✅ DOĞRU: Önce Adım 1-6 uygula, onay al, sonra target SKILL'i çalıştır.

❌ YANLIŞ: 4 ayrı AskUserQuestion ile tek tek sormak. ✅ DOĞRU: Mümkün olan en az sayıda AskUserQuestion çağrısı (tek çağrıda 4 soru).

❌ YANLIŞ: "Default iPhone 13 kullanayım" diye kendi kendine varsayım yapmak. ✅ DOĞRU: Device bilgisi yoksa sor. Varsayım yapma.

❌ YANLIŞ: Onay aşamasını atlamak ("zaten açık") diye execute'a geçmek. ✅ DOĞRU: Her zaman Adım 6'yı uygula. Fast path bile onay sorusu sorar.

❌ YANLIŞ: last-intent.md'yi görmezden gelip her seferinde baştan sormak. ✅ DOĞRU: Aynı session'da ikinci talep → repeat path.

❌ YANLIŞ: Bir SKILL'i yükleyip sonra metadata'sını okumamak. ✅ DOĞRU: Target SKILL'in required_inputs'ını ALWAYS parse et.

Referanslar

• Her F-MCP SKILL'in required_inputs metadata'sı — bu router'ın kullandığı shape
• .claude/design-systems/active-ds.md — DS context (v1.8.0+)
• .claude/design-systems/last-intent.md — son tamamlanan intent
• .claude/design-systems/intent-history.md — son 5 intent LRU
• src/core/instructions.ts — FMCP_INSTRUCTIONS "INTENT ROUTER ENTRY" bölümü (v1.8.1+)

Evolution Triggers

• Yeni F-MCP SKILL eklendiğinde: Adım 1 keyword tablosuna ekle
• SKILL'e yeni input eklendiğinde: Adım 4'ün parse mantığı metadata'yı otomatik yakalar, router'ı güncellemeye gerek yok
• Kullanıcı geri bildirim verirse ("çok soru soruyorsun"): Fast path'lerin aktivasyon eşiklerini düşür