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)

Audit Type Routing

Ç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ı

## 🔍 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)

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