the-frame-ai 0.10.8 → 0.11.0

package/README.de.md

@@ -109,6 +109,30 @@ Führe `/frame:research <Thema>` aus — Claude erkundet die Codebasis, externe
 /frame:ship
 ```
 
+### UI-Verifizierung: Sicherstellen dass die Oberfläche funktioniert
+
+```
+/frame:build
+# → Claude implementiert die Aufgabe, sagt "fertig"
+
+/frame:verify-ui
+# → öffnet Browser über Playwright MCP, macht Screenshot
+# → vergleicht mit der Aufgabenbeschreibung
+# → PASS: Oberfläche entspricht den Erwartungen
+# → FAIL: beschreibt genau was nicht stimmt und wo nachzuschauen ist
+
+# Wenn etwas nicht stimmt:
+/frame:fast "fix: Button wird auf Mobile nicht angezeigt"
+/frame:verify-ui
+# → erneute Prüfung nach dem Fix
+```
+
+Der Befehl **prüft** nur — er behebt nicht automatisch. Wenn er ein Problem findet, beschreibt er es präzise: welches Element, welches Verhalten, was erwartet wurde.
+
+**Automatische Prüfung**: in `/frame:build`, `/frame:fast`, `/frame:wave` und `/frame:debug` — wenn die Aufgabe UI-Dateien berührt (`.tsx`, `.vue`, `.css`, `component`, `page`) — wird die Browser-Prüfung automatisch nach den Quality Gates ausgeführt.
+
+**Erfordert Playwright MCP** — wird automatisch bei `npx the-frame init` oder `npx the-frame update` hinzugefügt, wenn die Frage zum Frontend-Projekt mit "y" beantwortet wird.
+
 ### Sicherheit: Audit vor dem Launch
 
 ```
@@ -163,27 +187,36 @@ Führe `/frame:research <Thema>` aus — Claude erkundet die Codebasis, externe
 ```
 /frame:daily
 
-/frame:performance
-# → Baseline ermitteln: Bundle-Größe, Ladezeit, Lighthouse-Score
-#   Zahlen merken — am Ende für den Vergleich benötigt
-
-/frame:research "dashboard performance"
-# → Claude analysiert Dashboard-Code: schwere Komponenten,
-#   redundante Anfragen, was gecacht oder lazy-geladen werden kann
+/frame:perf-audit
+# → erkennt Stack (Next.js + PostgreSQL + Redis usw.)
+# → sucht aktuelle bekannte Probleme für genau diesen Stack
+# → Tiefenscan: N+1-Abfragen, Memory Leaks, blockierende Operationen,
+#   fehlende Cache-Header, Re-Render-Ursachen, Bundle-Größe
+# → Bericht gespeichert in .planning/reports/performance/PERF_REPORT.md
+#   mit Critical/High/Medium/Low-Prioritäten und Aufwandsschätzungen
+
+# Beispiel-Ausgabe:
+# Critical: 2 | High: 4 | Medium: 3 | Low: 1
+# [PERF-1] N+1-Abfrage in /api/users — 47 extra DB-Abfragen pro Request (S)
+# [PERF-2] setInterval ohne Cleanup in Dashboard — Memory Leak (XS)
+
+/frame:perf-fix
+# → liest PERF_REPORT.md, beginnt mit Critical
+# → zeigt für jedes Problem:
+#   --- BEFORE ---
+#   const users = await db.findMany()
+#   --- AFTER ---
+#   const users = await db.findMany({ select: { id, name, email } })
+# → fragt: Apply this fix? [y/n/skip]
+# → wendet an, führt Typecheck + Tests aus, macht Rollback bei Fehler
 
-/frame:plan "dashboard optimization"
-# → Aufgabenliste mit Impact-Schätzungen:
-#   1. schwere Charts lazy laden
-#   2. API-Anfragen cachen
-#   3. doppelte Anfragen beim Mount entfernen
-
-/frame:build
-# → sequenziell, jede Aufgabe mit einem Test
-
-/frame:performance
-# → mit Baseline vergleichen: echte Verbesserung sehen
+# Gezielte Fixes:
+/frame:perf-fix PERF-1      # ein Problem beheben
+/frame:perf-fix high        # alle High beheben
+/frame:perf-fix all         # Critical + High beheben
 
-/frame:ship
+/frame:perf-audit
+# → erneut ausführen um Verbesserungen zu bestätigen
 ```
 
 ## Was drin ist
@@ -191,8 +224,8 @@ Führe `/frame:research <Thema>` aus — Claude erkundet die Codebasis, externe
 FRAME bietet:
 
 - **6-Phasen-Workflow**: Recherche → Plan → Build → Review → Ship → Reflect
-- **35 Befehle**: von schnellen Aufgaben bis zum vollständigen Feature-Entwicklungszyklus
-- **6 KI-Agenten**: Researcher, Planner, Builder, Reviewer, Devil's Advocate, Security
+- **37 Befehle**: von schnellen Aufgaben bis zum vollständigen Feature-Entwicklungszyklus
+- **7 KI-Agenten**: Researcher, Planner, Builder, Reviewer, Devil's Advocate, Security, Performance Auditor
 - **Safety-Hooks**: blockieren destruktive Operationen, erzwingen Quality-Gates
 - **Git-Sicherheit**: Checkpoints, Rollback, Worktrees, Pause/Resume
 - **Sicherheitsaudit**: OWASP Top 10, Secret-Erkennung, Infrastruktur-Checks, KI/LLM-Risiken
@@ -276,6 +309,8 @@ Diese 7 Befehle decken 90% der Solo-Dev-Arbeit ab:
 | `/frame:review` | Vor dem Deployment — automatisierte Prüfungen + Checkliste |
 | `/frame:security` | Tiefer Sicherheitsaudit: Secrets, OWASP, Infrastruktur, KI/LLM-Risiken |
 | `/frame:security-fix` | Befunde aus dem letzten Sicherheitsbericht beheben (CRITICAL zuerst, dann HIGH) |
+| `/frame:perf-audit` | Tiefer Performance-Audit: erkennt Stack, recherchiert aktuelle Probleme, schreibt PERF_REPORT.md |
+| `/frame:perf-fix` | Probleme aus PERF_REPORT.md beheben — zeigt Before/After, fragt Bestätigung pro Fix |
 | `/frame:health` | Vollständiger Projekt-Gesundheitscheck |
 | `/frame:check-deps` | Sicherheitsaudit + veraltete Pakete |
 | `/frame:performance` | Bundle-Größe und Lighthouse-Audit |

package/README.es.md

@@ -109,6 +109,30 @@ Ejecuta `/frame:research <tema>` — Claude explora la base de código, fuentes
 /frame:ship
 ```
 
+### Verificación de UI: confirmar que la interfaz funciona
+
+```
+/frame:build
+# → Claude implementa la tarea, dice "listo"
+
+/frame:verify-ui
+# → abre el navegador a través de Playwright MCP, toma una captura de pantalla
+# → compara con la descripción de la tarea
+# → PASS: la interfaz coincide con las expectativas
+# → FAIL: describe exactamente qué está mal y dónde buscar
+
+# Si algo está mal:
+/frame:fast "fix: el botón no se muestra en móvil"
+/frame:verify-ui
+# → nueva verificación después del fix
+```
+
+El comando solo **verifica** — no corrige automáticamente. Si encuentra un problema, lo describe con precisión: qué elemento, qué comportamiento, qué se esperaba.
+
+**Verificación automática**: en `/frame:build`, `/frame:fast`, `/frame:wave` y `/frame:debug` — si la tarea toca archivos de UI (`.tsx`, `.vue`, `.css`, `component`, `page`) — la verificación del navegador se ejecuta automáticamente después de los quality gates.
+
+**Requiere Playwright MCP** — se añade automáticamente en `npx the-frame init` o `npx the-frame update` si respondes "y" a la pregunta sobre proyecto frontend.
+
 ### Seguridad: auditoría antes del lanzamiento
 
 ```
@@ -163,27 +187,36 @@ Ejecuta `/frame:research <tema>` — Claude explora la base de código, fuentes
 ```
 /frame:daily
 
-/frame:performance
-# → obtener línea base: tamaño del bundle, tiempo de carga, puntuación Lighthouse
-#   recordar los números — los necesitarás para comparar al final
-
-/frame:research "dashboard performance"
-# → Claude analiza el código del dashboard: componentes pesados,
-#   solicitudes redundantes, qué se puede cachear o cargar de forma diferida
+/frame:perf-audit
+# → detecta el stack (Next.js + PostgreSQL + Redis, etc.)
+# → busca problemas conocidos actuales para ese stack exacto
+# → escaneo profundo: consultas N+1, fugas de memoria, operaciones bloqueantes,
+#   cabeceras de caché faltantes, causas de re-renders, tamaño del bundle
+# → informe guardado en .planning/reports/performance/PERF_REPORT.md
+#   con prioridades Critical/High/Medium/Low y estimaciones de esfuerzo
+
+# Ejemplo de salida:
+# Critical: 2 | High: 4 | Medium: 3 | Low: 1
+# [PERF-1] Consulta N+1 en /api/users — 47 consultas DB extra por request (S)
+# [PERF-2] setInterval sin cleanup en Dashboard — fuga de memoria (XS)
+
+/frame:perf-fix
+# → lee PERF_REPORT.md, empieza con Critical
+# → para cada problema muestra:
+#   --- BEFORE ---
+#   const users = await db.findMany()
+#   --- AFTER ---
+#   const users = await db.findMany({ select: { id, name, email } })
+# → pregunta: Apply this fix? [y/n/skip]
+# → aplica, ejecuta typecheck + tests, revierte si falla
 
-/frame:plan "dashboard optimization"
-# → lista de tareas con estimaciones de impacto:
-#   1. carga diferida de gráficos pesados
-#   2. cachear solicitudes de API
-#   3. eliminar solicitudes duplicadas al montar
-
-/frame:build
-# → secuencial, cada tarea con una prueba
-
-/frame:performance
-# → comparar con la línea base: ver la mejora real
+# Correcciones específicas:
+/frame:perf-fix PERF-1      # corregir un problema
+/frame:perf-fix high        # corregir todos los High
+/frame:perf-fix all         # corregir Critical + High
 
-/frame:ship
+/frame:perf-audit
+# → volver a ejecutar para confirmar mejoras
 ```
 
 ## Qué incluye
@@ -191,8 +224,8 @@ Ejecuta `/frame:research <tema>` — Claude explora la base de código, fuentes
 FRAME proporciona:
 
 - **Flujo de trabajo de 6 fases**: Investigar → Planificar → Construir → Revisar → Publicar → Reflexionar
-- **35 comandos**: desde tareas rápidas hasta el ciclo completo de desarrollo de funcionalidades
-- **6 agentes de IA**: Investigador, Planificador, Constructor, Revisor, Abogado del Diablo, Seguridad
+- **37 comandos**: desde tareas rápidas hasta el ciclo completo de desarrollo de funcionalidades
+- **7 agentes de IA**: Investigador, Planificador, Constructor, Revisor, Abogado del Diablo, Seguridad, Auditor de Rendimiento
 - **Safety Hooks**: bloquean operaciones destructivas, aplican quality gates
 - **Git Safety**: checkpoints, rollback, worktrees, pausa/reanudación
 - **Auditoría de seguridad**: OWASP Top 10, detección de secretos, verificaciones de infraestructura, riesgos de IA/LLM
@@ -276,6 +309,8 @@ Estos 7 comandos cubren el 90% del trabajo de desarrollo en solitario:
 | `/frame:review` | Antes de desplegar — verificaciones automatizadas + lista de comprobación |
 | `/frame:security` | Auditoría de seguridad profunda: secretos, OWASP, infraestructura, riesgos IA/LLM |
 | `/frame:security-fix` | Corregir hallazgos del último informe de seguridad (CRITICAL primero, luego HIGH) |
+| `/frame:perf-audit` | Auditoría de rendimiento profunda: detecta stack, investiga problemas actuales, escribe PERF_REPORT.md |
+| `/frame:perf-fix` | Corregir problemas de PERF_REPORT.md — muestra antes/después, pide confirmación por fix |
 | `/frame:health` | Verificación completa del estado del proyecto |
 | `/frame:check-deps` | Auditoría de seguridad + paquetes desactualizados |
 | `/frame:performance` | Auditoría de tamaño de bundle y Lighthouse |

package/README.hi.md

@@ -109,6 +109,30 @@ FRAME — AI-सहायता प्राप्त एकल विकास
 /frame:ship
 ```
 
+### UI सत्यापन: इंटरफ़ेस काम करता है यह सुनिश्चित करें
+
+```
+/frame:build
+# → Claude कार्य लागू करता है, "तैयार" कहता है
+
+/frame:verify-ui
+# → Playwright MCP के माध्यम से ब्राउज़र खोलता है, स्क्रीनशॉट लेता है
+# → कार्य विवरण से तुलना करता है
+# → PASS: इंटरफ़ेस अपेक्षाओं से मेल खाता है
+# → FAIL: बिल्कुल क्या गलत है और कहाँ देखना है यह बताता है
+
+# अगर कुछ गलत है:
+/frame:fast "fix: मोबाइल पर बटन नहीं दिख रहा"
+/frame:verify-ui
+# → फिक्स के बाद पुनः जांच
+```
+
+कमांड केवल **सत्यापित** करता है — स्वचालित रूप से ठीक नहीं करता। अगर कोई समस्या मिलती है — सटीक रूप से बताता है: कौन सा तत्व, कौन सा व्यवहार, क्या अपेक्षित था।
+
+**स्वचालित जांच**: `/frame:build`, `/frame:fast`, `/frame:wave` और `/frame:debug` में — अगर कार्य UI फ़ाइलों (`.tsx`, `.vue`, `.css`, `component`, `page`) को छूता है — quality gates के बाद ब्राउज़र जांच स्वचालित रूप से चलती है।
+
+**Playwright MCP आवश्यक है** — `npx the-frame init` या `npx the-frame update` पर frontend project प्रश्न का "y" उत्तर देने पर स्वचालित रूप से जोड़ा जाता है।
+
 ### सुरक्षा: लॉन्च से पहले ऑडिट
 
 ```
@@ -163,27 +187,36 @@ FRAME — AI-सहायता प्राप्त एकल विकास
 ```
 /frame:daily
 
-/frame:performance
-# → बेसलाइन प्राप्त करें: bundle आकार, लोड समय, Lighthouse स्कोर
-#   संख्याएं याद रखें — अंत में तुलना के लिए चाहिए होंगी
-
-/frame:research "dashboard performance"
-# → Claude डैशबोर्ड कोड का विश्लेषण करता है: भारी कंपोनेंट,
-#   अनावश्यक अनुरोध, क्या कैश या lazy-load किया जा सकता है
-
-/frame:plan "dashboard optimization"
-# → प्रभाव अनुमानों के साथ कार्य सूची:
-#   1. भारी चार्ट को lazy load करें
-#   2. API अनुरोधों को कैश करें
-#   3. माउंट पर डुप्लिकेट अनुरोध हटाएं
-
-/frame:build
-# → क्रमिक, प्रत्येक कार्य एक परीक्षण के साथ
-
-/frame:performance
-# → बेसलाइन से तुलना करें: वास्तविक सुधार देखें
-
-/frame:ship
+/frame:perf-audit
+# → स्टैक डिटेक्ट करता है (Next.js + PostgreSQL + Redis आदि)
+# → उस स्टैक के लिए वर्तमान ज्ञात समस्याएं खोजता है
+# → गहरा स्कैन: N+1 क्वेरी, मेमोरी लीक, ब्लॉकिंग ऑपरेशन,
+#   कैश हेडर की कमी, re-render के कारण, bundle साइज
+# → रिपोर्ट .planning/reports/performance/PERF_REPORT.md में सेव
+#   Critical/High/Medium/Low प्राथमिकताओं और effort अनुमान के साथ
+
+# उदाहरण आउटपुट:
+# Critical: 2 | High: 4 | Medium: 3 | Low: 1
+# [PERF-1] /api/users में N+1 क्वेरी — प्रति request 47 अतिरिक्त DB क्वेरी (S)
+# [PERF-2] Dashboard में setInterval बिना cleanup — मेमोरी लीक (XS)
+
+/frame:perf-fix
+# → PERF_REPORT.md पढ़ता है, Critical से शुरू करता है
+# → प्रत्येक समस्या के लिए दिखाता है:
+#   --- BEFORE ---
+#   const users = await db.findMany()
+#   --- AFTER ---
+#   const users = await db.findMany({ select: { id, name, email } })
+# → पूछता है: Apply this fix? [y/n/skip]
+# → लागू करता है, typecheck + tests चलाता है, विफल होने पर revert करता है
+
+# विशिष्ट fixes:
+/frame:perf-fix PERF-1      # एक समस्या ठीक करें
+/frame:perf-fix high        # सभी High ठीक करें
+/frame:perf-fix all         # Critical + High ठीक करें
+
+/frame:perf-audit
+# → सुधार की पुष्टि के लिए फिर से चलाएं
 ```
 
 ## अंदर क्या है
@@ -191,8 +224,8 @@ FRAME — AI-सहायता प्राप्त एकल विकास
 FRAME प्रदान करता है:
 
 - **6-चरण वर्कफ़्लो**: अनुसंधान → योजना → निर्माण → समीक्षा → शिप → प्रतिबिंब
-- **35 कमांड**: त्वरित कार्यों से लेकर पूर्ण सुविधा विकास चक्र तक
-- **6 AI एजेंट**: शोधकर्ता, योजनाकार, निर्माता, समीक्षक, शैतान का वकील, सुरक्षा
+- **37 कमांड**: त्वरित कार्यों से लेकर पूर्ण सुविधा विकास चक्र तक
+- **7 AI एजेंट**: शोधकर्ता, योजनाकार, निर्माता, समीक्षक, शैतान का वकील, सुरक्षा, प्रदर्शन ऑडिटर
 - **सेफ्टी हुक्स**: विनाशकारी ऑपरेशन ब्लॉक करते हैं, गुणवत्ता गेट लागू करते हैं
 - **Git सुरक्षा**: चेकपॉइंट, रोलबैक, वर्कट्री, पॉज/रिज्यूम
 - **Security Auditing**: OWASP Top 10, secret detection, infrastructure checks, AI/LLM risks
@@ -276,6 +309,8 @@ npx the-frame-ai init
 | `/frame:review` | डिप्लॉय करने से पहले — स्वचालित जांच + चेकलिस्ट |
 | `/frame:security` | गहरा सुरक्षा ऑडिट: secrets, OWASP, infrastructure, AI/LLM risks |
 | `/frame:security-fix` | नवीनतम रिपोर्ट से findings ठीक करें (पहले CRITICAL, फिर HIGH) |
+| `/frame:perf-audit` | गहरा performance audit: स्टैक डिटेक्ट, वर्तमान समस्याएं खोजें, PERF_REPORT.md लिखें |
+| `/frame:perf-fix` | PERF_REPORT.md की समस्याएं ठीक करें — before/after दिखाएं, प्रत्येक fix पर पुष्टि |
 | `/frame:health` | पूर्ण प्रोजेक्ट स्वास्थ्य जांच |
 | `/frame:check-deps` | सुरक्षा ऑडिट + पुराने पैकेज |
 | `/frame:performance` | Bundle आकार और Lighthouse ऑडिट |

package/README.ja.md

@@ -109,6 +109,30 @@ Claude Codeで一人でプロダクトを作っていて、チームのように
 /frame:ship
 ```
 
+### UI検証：インターフェースが動作することを確認する
+
+```
+/frame:build
+# → Claudeがタスクを実装し、「完了」と言う
+
+/frame:verify-ui
+# → Playwright MCPを通じてブラウザを開き、スクリーンショットを撮る
+# → タスクの説明と比較する
+# → PASS：インターフェースが期待通り
+# → FAIL：何が問題でどこを見ればいいか正確に説明
+
+# 何か問題がある場合：
+/frame:fast "fix: モバイルでボタンが表示されない"
+/frame:verify-ui
+# → 修正後に再確認
+```
+
+このコマンドは**確認のみ** — 自動修正はしません。問題が見つかった場合、正確に説明します：どの要素、どの動作、何が期待されていたか。
+
+**自動チェック**：`/frame:build`、`/frame:fast`、`/frame:wave`、`/frame:debug` で — タスクがUIファイル（`.tsx`、`.vue`、`.css`、`component`、`page`）に触れる場合 — ブラウザチェックがquality gatesの後に自動的に実行されます。
+
+**Playwright MCPが必要** — `npx the-frame init` または `npx the-frame update` 時にフロントエンドプロジェクトの質問に"y"と答えると自動的に追加されます。
+
 ### セキュリティ：リリース前の監査
 
 ```
@@ -163,27 +187,36 @@ Claude Codeで一人でプロダクトを作っていて、チームのように
 ```
 /frame:daily
 
-/frame:performance
-# → ベースラインを取得：バンドルサイズ、読み込み時間、Lighthouseスコア
-#   数値を記録 — 最後の比較に必要
-
-/frame:research "dashboard performance"
-# → Claudeがダッシュボードコードを分析：重いコンポーネント、
-#   冗長なリクエスト、キャッシュまたは遅延読み込みできるもの
-
-/frame:plan "dashboard optimization"
-# → 影響見積もり付きのタスクリスト：
-#   1. 重いチャートを遅延読み込み
-#   2. APIリクエストをキャッシュ
-#   3. マウント時の重複リクエストを削除
-
-/frame:build
-# → 順次実行、各タスクにテスト付き
-
-/frame:performance
-# → ベースラインと比較：実際の改善を確認
-
-/frame:ship
+/frame:perf-audit
+# → スタックを検出（Next.js + PostgreSQL + Redis など）
+# → そのスタック固有の現在の既知問題を調査
+# → 深層スキャン：N+1クエリ、メモリリーク、ブロッキング操作、
+#   キャッシュヘッダーの欠如、再レンダリングの原因、バンドルサイズ
+# → レポートを .planning/reports/performance/PERF_REPORT.md に保存
+#   Critical/High/Medium/Low の優先度と工数見積もり付き
+
+# 出力例：
+# Critical: 2 | High: 4 | Medium: 3 | Low: 1
+# [PERF-1] /api/users の N+1クエリ — リクエストごとに47回の余分なDBクエリ (S)
+# [PERF-2] Dashboard の setInterval にクリーンアップなし — メモリリーク (XS)
+
+/frame:perf-fix
+# → PERF_REPORT.md を読み、Critical から開始
+# → 各問題について表示：
+#   --- BEFORE ---
+#   const users = await db.findMany()
+#   --- AFTER ---
+#   const users = await db.findMany({ select: { id, name, email } })
+# → 確認：Apply this fix? [y/n/skip]
+# → 適用、typecheck + テスト実行、失敗時はリバート
+
+# 特定の修正：
+/frame:perf-fix PERF-1      # 1つの問題を修正
+/frame:perf-fix high        # すべての High を修正
+/frame:perf-fix all         # Critical + High を修正
+
+/frame:perf-audit
+# → 改善を確認するために再実行
 ```
 
 ## 内容
@@ -191,8 +224,8 @@ Claude Codeで一人でプロダクトを作っていて、チームのように
 FRAMEが提供するもの：
 
 - **6フェーズワークフロー**：調査 → 計画 → 構築 → レビュー → リリース → 振り返り
-- **35コマンド**：クイックタスクから完全な機能開発サイクルまで
-- **6つのAIエージェント**：リサーチャー、プランナー、ビルダー、レビュアー、悪魔の代弁者、セキュリティ
+- **37コマンド**：クイックタスクから完全な機能開発サイクルまで
+- **7つのAIエージェント**：リサーチャー、プランナー、ビルダー、レビュアー、悪魔の代弁者、セキュリティ、パフォーマンス監査
 - **セーフティフック**：破壊的操作をブロック、品質ゲートを強制
 - **Git安全機能**：チェックポイント、ロールバック、ワークツリー、一時停止/再開
 - **セキュリティ監査**：OWASP Top 10、シークレット検出、インフラチェック、AI/LLMリスク
@@ -276,6 +309,8 @@ npx the-frame-ai init
 | `/frame:review` | デプロイ前 — 自動チェック + チェックリスト |
 | `/frame:security` | 深度セキュリティ監査：シークレット、OWASP、インフラ、AI/LLMリスク |
 | `/frame:security-fix` | 最新セキュリティレポートの発見を修正（CRITICAL 優先、次に HIGH） |
+| `/frame:perf-audit` | 深層パフォーマンス監査：スタック検出、現在の問題を調査、PERF_REPORT.md を作成 |
+| `/frame:perf-fix` | PERF_REPORT.md の問題を修正 — Before/After を表示、修正ごとに確認 |
 | `/frame:health` | プロジェクト全体のヘルスチェック |
 | `/frame:check-deps` | セキュリティ監査 + 古いパッケージ |
 | `/frame:performance` | バンドルサイズとLighthouse監査 |

package/README.md

@@ -109,33 +109,66 @@ Run `/frame:research <topic>` — Claude explores the codebase, external sources
 /frame:ship
 ```
 
-### Improvement: speed up dashboard loading
+### Performance: find and fix bottlenecks
 
 ```
 /frame:daily
 
-/frame:performance
-# → get baseline: bundle size, load time, Lighthouse score
-#   remember the numbers — you'll need them for comparison at the end
-
-/frame:research "dashboard performance"
-# → Claude analyzes dashboard code: heavy components,
-#   redundant requests, what can be cached or lazy-loaded
+/frame:perf-audit
+# → detects stack (Next.js + PostgreSQL + Redis, etc.)
+# → searches for current known issues for that exact stack
+# → deep scan: N+1 queries, memory leaks, blocking ops,
+#   missing cache headers, re-render causes, bundle size
+# → report saved to .planning/reports/performance/PERF_REPORT.md
+#   with Critical/High/Medium/Low priorities and effort estimates
+
+# Example report output:
+# Critical: 2 | High: 4 | Medium: 3 | Low: 1
+# [PERF-1] N+1 query in /api/users — 47 extra DB queries per request (S)
+# [PERF-2] setInterval without cleanup in Dashboard — memory leak (XS)
+
+/frame:perf-fix
+# → reads PERF_REPORT.md, starts with Critical issues
+# → for each issue shows:
+#   --- BEFORE ---
+#   const users = await db.findMany()
+#   --- AFTER ---
+#   const users = await db.findMany({ select: { id, name, email } })
+# → asks: Apply this fix? [y/n/skip]
+# → applies, runs typecheck + tests, reverts if broken
+
+# Fix specific issue or priority:
+/frame:perf-fix PERF-1      # fix one issue
+/frame:perf-fix high        # fix all High priority
+/frame:perf-fix all         # fix Critical + High
+
+/frame:perf-audit
+# → re-run to confirm improvements
+```
 
-/frame:plan "dashboard optimization"
-# → task list with impact estimates:
-#   1. lazy load heavy charts
-#   2. cache API requests
-#   3. remove duplicate requests on mount
+### UI verification: confirm the interface works
 
+```
 /frame:build
-# → sequential, each task with a test
+# → Claude implements the task, says "done"
+
+/frame:verify-ui
+# → opens browser via Playwright MCP, takes a screenshot
+# → compares with the task description
+# → PASS: interface matches expectations
+# → FAIL: describes exactly what's wrong and where to look
+
+# If something is wrong:
+/frame:fast "fix: button not showing on mobile"
+/frame:verify-ui
+# → re-check after the fix
+```
 
-/frame:performance
-# → compare with baseline: see the real improvement
+The command only **verifies** — it doesn't auto-fix. If it finds a problem, it describes it precisely: which element, what behavior, what was expected.
 
-/frame:ship
-```
+**Automatic check**: in `/frame:build`, `/frame:fast`, `/frame:wave`, and `/frame:debug` — if the task touches UI files (`.tsx`, `.vue`, `.css`, `component`, `page`) — browser check runs automatically after quality gates.
+
+**Requires Playwright MCP** — added automatically on `npx the-frame init` or `npx the-frame update` if you answer "y" to the frontend project question.
 
 ### Security: audit before launch
 
@@ -193,8 +226,8 @@ Run `/frame:research <topic>` — Claude explores the codebase, external sources
 FRAME provides:
 
 - **6-phase workflow**: Research → Plan → Build → Review → Ship → Reflect
-- **35 commands**: from quick tasks to full feature development cycle
-- **6 AI agents**: Researcher, Planner, Builder, Reviewer, Devil's Advocate, Security
+- **37 commands**: from quick tasks to full feature development cycle
+- **7 AI agents**: Researcher, Planner, Builder, Reviewer, Devil's Advocate, Security, Performance Auditor
 - **Safety Hooks**: block destructive operations, enforce quality gates
 - **Git Safety**: checkpoints, rollback, worktrees, pause/resume
 - **Security Auditing**: OWASP Top 10, secret detection, infrastructure checks, AI/LLM risks
@@ -278,6 +311,8 @@ These 7 commands cover 90% of solo dev work:
 | `/frame:review` | Before deploying — automated checks + checklist |
 | `/frame:security` | Deep security audit: secrets, OWASP, infra, AI/LLM risks |
 | `/frame:security-fix` | Fix findings from the latest security report (CRITICAL first, then HIGH) |
+| `/frame:perf-audit` | Deep performance audit: detects stack, researches current issues, writes PERF_REPORT.md |
+| `/frame:perf-fix` | Fix issues from PERF_REPORT.md — shows before/after, asks confirmation per fix |
 | `/frame:health` | Full project health check |
 | `/frame:check-deps` | Dependency vulnerabilities + outdated packages |
 | `/frame:performance` | Bundle size and Lighthouse audit |