@atezer/figma-mcp-bridge 1.7.30 → 1.9.1

package/skills/fmcp-ds-audit-orchestrator/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: fmcp-ds-audit-orchestrator
+description: Figma ekranlarını 5 kategori açısından platform-agnostic denetler (DS compliance / a11y / drift / visual QA / impact). Read-only çalışır; bulguları raporlar, düzeltmeleri sadece önerir — mutation için onay + ayrı agent. Her platformda çalışır. Condensed-first: Essentials bölümü %80 case'i kapsar, Advanced sadece edge case'lerde.
+metadata:
+  mcp-server: user-figma-mcp-bridge
+  version: 1.9.0
+  priority: 95
+  phase: orchestrator
+  personas:
+    - designops
+    - uidev
+  token_budget: condensed-first
+required_inputs:
+  - name: audit_type
+    type: "enum: compliance | a11y | drift | visual_qa | impact | auto"
+    description: "Denetim tipi. 'auto' → keyword'den tespit, belirsizse kullanıcıya sor"
+  - name: target_node
+    type: "string"
+    description: "Figma nodeId (frame/component)"
+---
+
+# FMCP DS Audit Orchestrator
+
+## Essentials (Üst Bölüm — %80 Case İçin Yeterli)
+
+### Ortak Protokol (Condensed — full: `agents/_orchestrator-protocol.md`)
+
+1. **Skill Registry** açık — tahmin yasak
+2. **Intent Routing** — belirsizse Read fmcp-intent-router
+3. **Cheap-First** — `depth=1`, `verbosity="summary"`; SEVERE bulgu varsa ilgili alt ağaca drill-down
+4. **Cache-First** — `.claude/audits/<YYYY-MM-DD>-<nodeId>.md` 24h freshness; 30 günden eski dosyaları temizle
+5. **User Onay** — hiçbir fix uygulanmaz, sadece önerilir (read-only discipline)
+6. **Self-Audit** — her SEVERE kategori için ≥1 somut nodeId raporda olmalı
+7. **Skill Evolution** — iki aşamalı onay, DRAFT banner
+8. **Türkçe raporlama** — metrik bloğu sonunda; CI için JSON mode destekli
+
+### Skill Registry (Ref Only — Read() sadece karar anında)
+
+| Skill | Dosya yolu | Trigger | Common case lazım mı? |
+|---|---|---|---|
+| `audit-figma-design-system` | `skills/audit-figma-design-system/SKILL.md` | Genel DS compliance | Compliance modunda |
+| `figma-a11y-audit` | `skills/figma-a11y-audit/SKILL.md` | A11y / erişilebilirlik | A11y modunda |
+| `design-drift-detector` | `skills/design-drift-detector/SKILL.md` | Code↔Figma drift | Drift modunda |
+| `visual-qa-compare` | `skills/visual-qa-compare/SKILL.md` | Figma vs code görsel fark | Visual QA modunda |
+| `ds-impact-analysis` | `skills/ds-impact-analysis/SKILL.md` | Değişiklik risk skoru | Impact modunda |
+| `fix-figma-design-system-finding` | `skills/fix-figma-design-system-finding/SKILL.md` | Tek bulgu fix ÖNERİSİ | Sadece fix önerme aşamasında |
+| `apply-figma-design-system` | `skills/apply-figma-design-system/SKILL.md` | Tüm ekran hizalama ÖNERİSİ | Sadece toplu fix önerme |
+
+### Audit Type Routing
+
+| Kullanıcı ifadesi | Mod | Read skill |
+|---|---|---|
+| "DS uyumu", "compliance", "denetle", "token bağlı mı" | `compliance` | `audit-figma-design-system` |
+| "erişilebilirlik", "a11y", "kontrast", "WCAG", "screen reader" | `a11y` | `figma-a11y-audit` |
+| "kod ile tutarsızlık", "drift", "değer kaymış" | `drift` | `design-drift-detector` |
+| "code vs figma", "görsel fark", "pixel diff" | `visual_qa` | `visual-qa-compare` |
+| "bu değişiklik neyi etkiler", "riskli mi", "impact" | `impact` | `ds-impact-analysis` |
+| Net değil / çoklu istek | `auto` | AskUserQuestion ile sor (veya düz metin soru) |
+
+Çoklu audit istenirse sırayla yap, her biri ayrı rapor bölümü.
+
+### Read-Only Discipline
+
+**Hiçbir mutation YAPMA.** Agent sadece okur, raporlar, önerir. Fix istiyorsa:
+1. Bulgu için öneri: `fix-figma-design-system-finding` (tek) veya `apply-figma-design-system` (toplu)
+2. Kullanıcıya sor: "Şu bulguları düzelteyim mi?" — `AskUserQuestion` veya düz metin
+3. Onay → **screen-builder agent'ı** (veya orchestrator skill'i) tetiklenir. Bu audit orchestrator'ı düzeltme yapmaz.
+
+### Cache-First Audit
+
+```
+.claude/audits/<YYYY-MM-DD>-<nodeId>.md
+```
+- 24h içinde aynı nodeId raporu var → oku, cache hit
+- Yoksa/stale → fresh audit, rapor cache'e yaz
+- 30 günden eski dosyaları her çalıştırmada temizle (housekeeping)
+
+### Self-Audit (Rapor Kalite)
+
+Raporu teslim etmeden önce kendi kendini denetle:
+- [ ] Her SEVERE kategori için ≥1 somut `nodeId` var mı?
+- [ ] Her bulgu için "neden önemli" açıklaması var mı?
+- [ ] Her bulgu için düzeltme önerisi (skill referansı) var mı?
+- [ ] Metrik bloğu rapor sonunda mı?
+
+Fail → düzelt, sonra teslim.
+
+### Rapor Formatı
+
+```markdown
+## 🔍 DS Audit Raporu — <ekran_adı>
+
+**Denetim tipi:** compliance | a11y | drift | visual_qa | impact
+**Hedef:** <nodeId>
+**DS:** <active-ds>
+**Cache:** hit | miss
+
+### Özet
+- SEVERE bulgu: <n>
+- ADVISORY bulgu: <n>
+- Genel skor: <n> / 100
+
+### SEVERE Bulgular
+
+#### 1. <Kategori> — <node_name> (`<nodeId>`)
+**Sorun:** <açıklama>
+**Neden önemli:** <kısa gerekçe>
+**Öneri:** `fix-figma-design-system-finding` / `apply-figma-design-system`
+
+### Düzeltme Önerisi
+<Toplu mu tek tek mi? Onay isteniyor mu? Hangi agent/skill çağrılacak?>
+
+---
+📊 Metrikler
+- Kullanılan skill'ler: <liste>
+- API çağrı sayısı: <n>
+- Cache hit / miss: <h> / <m>
+- Denetim süresi: <s>
+```
+
+**CI ortamında:** Aynı alanlar JSON formatında. `CI=true` env var veya kullanıcı "JSON formatında" derse.
+
+---
+
+## Advanced — Only Load If Needed
+
+**Bu bölümü Claude aşağıdaki koşullarda tarar:**
+- ⚠️ Çoklu audit tipi istendi (compliance + a11y + drift aynı anda)
+- ⚠️ Cache hit oldu ama kullanıcı "forced refresh" istedi
+- ⚠️ Büyük ekran, SEVERE bulgular drill-down gerektiriyor
+- ⚠️ Fix önerisi karmaşık (bazı bulgular tek tek, bazıları toplu)
+- ⚠️ Skill evolution ihtiyacı
+
+Common case'de bu bölüm OKUNMAZ.
+
+### Detay 1 — Cheap-First Drill-Down Pattern
+
+1. İlk tarama: `figma_get_design_context(nodeId, depth=1, verbosity="summary")`
+2. SEVERE bulgu tespit edilen alt ağaca drill-down: `figma_get_design_context(<child_nodeId>, depth=2, verbosity="standard")`
+3. Spesifik node için tam yapı: `figma_get_design_context(<leaf_nodeId>, depth=0, verbosity="full")`
+
+Tam ağaç hiçbir zaman tek seferde okunmaz. Screenshot sadece bulgu görselleştirme gerekiyorsa.
+
+### Detay 2 — Multi-Audit Orchestration
+
+Kullanıcı "hem DS hem a11y hem drift bak" derse:
+1. Her audit tipini sırayla yap (paralel değil — aynı cache slot'una yazarız)
+2. Her biri ayrı rapor bölümü, tek metrik bloğu sonunda
+3. Bulgular çakışıyorsa (örn. DS compliance'ta tespit edilen hardcoded color aynı zamanda a11y kontrast ihlaline yol açıyor) ← çapraz referans ver
+4. Öneriler toplu: "Bu 12 bulgudan 8'i `apply-figma-design-system` ile tek seferde çözülür, 4'ü manuel"
+
+### Detay 3 — Fix Önerisi Aşaması (Narrow vs Full)
+
+Kural:
+- **Narrow fix** (`fix-figma-design-system-finding`): 1-3 bulgu, spesifik nodeId'ler, ekranın geri kalanı sağlıklı
+- **Full reconcile** (`apply-figma-design-system`): 4+ bulgu veya ekranın geneli hardcoded/non-compliant
+
+Karar eşiği: SEVERE bulgu sayısı ve node dağılımı. Detaylı örnek:
+- 2 bulgu tek frame'de → narrow
+- 8 bulgu 6 farklı component'te → full reconcile
+- 15 bulgu ama hepsi tek bir "Card" component instance'ında → narrow (component master'ı düzelt, instance'lar otomatik güncellenir)
+
+### Detay 4 — Cache Housekeeping
+
+30 günden eski audit dosyalarını silme:
+```
+.claude/audits/ dizinindeki her .md dosyası için:
+  dosya adı formatı: YYYY-MM-DD-<nodeId>.md
+  bugünden 30 gün önce → sil
+```
+Her audit çalıştığında (başlangıçta) bu temizlik yapılır. Kullanıcıya "n eski rapor temizlendi" notu.
+
+### Detay 5 — Error Recovery (Audit-Specific)
+
+| Hata | Aksiyon |
+|---|---|
+| `figma_get_design_context` timeout | Daha küçük scope (`depth=0`), 1 retry |
+| SEVERE bulgu var ama nodeId alınamadı | Advanced Cheap-First Drill-Down Pattern'i kullan |
+| Cache dosyası corrupt | Sil, fresh audit yap, uyar |
+| Kullanıcı "fix uygula" dedi ama scope net değil | AskUserQuestion / düz metin soru: "Tek tek mi toplu mu?" |
+
+### Detay 6 — Platform-Specific Notes
+
+**Claude Code (agent olarak çağrıldığında):**
+- Sub-agent context'te orchestrator + sadece ilgili audit sub-skill yüklenir
+- Cache: `.claude/audits/` worktree cwd'ye göre
+
+**Cursor:**
+- `.cursor/rules/fmcp-orchestration.md` bu orchestrator'ı referans eder
+- Main context'te çalışır, cache path aynı
+
+**Claude Desktop:**
+- Project knowledge'a yüklenmiş SKILL.md — **ilk prompt'ta manuel referans zorunlu**
+- Cache concept: Desktop'ta filesystem cache yok; her audit fresh (Project knowledge'a yükleme alternatif)
+
+**Claude Web:**
+- Bridge olmadığı için `figma_*` tool'ları YOK
+- Plan-only mod: Claude audit workflow'unu metinle anlatır, "bu audit'i Code'da çalıştır" uyarısı verir
+
+### Detay 7 — Skill Evolution (Yeni Audit Tipi)
+
+Kullanıcı var olmayan bir audit tipi isterse (örn. "performance audit — bundle size vs screen complexity"):
+1. **Aşama 1:** Kullanıcıya gap'i açıkla, yeni skill önerisi sun
+2. **Aşama 2:** `skills/fmcp-performance-audit/SKILL.md` oluştur `# DRAFT — PENDING APPROVAL` banner'ıyla
+3. İçerik onayı sonrası banner'ı kaldır