vibes-plug 2.5.0 → 2.14.1

package/skills/vector-db-rag-expert/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: vector-db-rag-expert
-description: "Expert guide for high-performance Vector Databases, RAG architectures, pgvector HNSW indexing, hybrid search (Dense + BM25), and semantic chunking / Panduan ahli Vector DB, arsitektur RAG, pgvector HNSW, dan hybrid search."
+description: "Expert guide for high-performance Vector Databases, Deep RAG architectures, pgvector 0.8+ HNSW, Reciprocal Rank Fusion (RRF), Cross-Encoder Re-ranking, and Late Chunking / Panduan ahli Vector DB, arsitektur Deep RAG, pgvector HNSW, RRF, dan Re-ranking."
 author: "Roedy Rustam"
 ---
 
-# Vector DB & Deep RAG Expert
+# Vector DB & Deep RAG Expert (2026 Edition)
 
 [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
 
@@ -14,39 +14,195 @@ author: "Roedy Rustam"
 ## English
 
 ### Purpose & Overview
-Production-grade guidelines for Vector Databases (pgvector, Qdrant, Pinecone, Milvus), RAG indexing strategies, HNSW vector search, hybrid retrieval (dense vector embeddings + BM25 sparse keyword ranking), semantic document chunking, and RAG evaluation frameworks.
+Production-grade architectural guide for Vector Databases (PostgreSQL `pgvector 0.8+`, Qdrant, LanceDB, Pinecone), Deep RAG indexing strategies, HNSW iterative search, **Reciprocal Rank Fusion (RRF)** hybrid retrieval, **Cross-Encoder Re-ranking** (Cohere Rerank v3, FlashRank, BGE-Reranker-v2), and **Late Chunking** to eliminate context fragmentation.
 
 ### Key Capabilities
-- **pgvector & Hybrid Search**: PostgreSQL `pgvector` HNSW indexing, cosine/L2 distance metric tuning, and BM25 hybrid re-ranking.
-- **RAG Architecture**: Parent-Document retrieval, Hypothetical Document Embeddings (HyDE), and contextual compression.
-- **RAG Evaluation**: Automated retrieval quality scoring using Ragas and TruLens.
+1. **pgvector 0.8+ & HNSW Indexing**: High-dimensional vector storage, cosine/inner-product/L2 distance metric tuning, and iterative HNSW index scans with metadata filtering.
+2. **Reciprocal Rank Fusion (RRF)**: Combining sparse keyword BM25 ranks with dense semantic vector ranks using $RRF(d) = \sum \frac{1}{k + rank(d)}$, far outperforming naive linear score weighting.
+3. **Cross-Encoder Re-ranking**: Two-stage retrieval pipeline: retrieve Top-50 candidates via fast hybrid search, then re-rank down to Top-5 using a cross-encoder model to maximize NDCG@10.
+4. **Late Chunking & Contextual Retrieval**: Embed long-context documents in full before pooling token embeddings into individual chunks, preserving document-level semantics across boundaries.
+5. **RAG Evaluation**: Continuous retrieval precision and hallucination scoring using automated eval harnesses (Ragas, TruLens, DeepEval).
 
+---
+
+### Production Implementation Recipes
+
+#### Recipe 1: Reciprocal Rank Fusion (RRF) Hybrid Search with Drizzle ORM
 ```typescript
 import { sql } from 'drizzle-orm';
+import { db } from '@/lib/db';
+
+export interface SearchResult {
+  id: string;
+  content: string;
+  score: number;
+}
+
+/**
+ * Executes Reciprocal Rank Fusion (RRF) combining BM25 keyword search and pgvector HNSW
+ * k = 60 is the industry standard constant
+ */
+export async function reciprocalRankFusionSearch(
+  queryVector: number[],
+  queryText: string,
+  limit = 10,
+  k = 60
+): Promise<SearchResult[]> {
+  const formattedVector = JSON.stringify(queryVector);
 
-// Hybrid Search: Vector Cosine Similarity + Full Text Search
-export async function hybridSearch(queryVector: number[], queryText: string, limit = 10) {
-  const result = await db.execute(sql`
-    SELECT id, title, content,
-           (1 - (embedding <=> ${JSON.stringify(queryVector)}::vector)) * 0.7 +
-           ts_rank(fts, websearch_to_tsquery('english', ${queryText})) * 0.3 AS score
-    FROM documents
-    ORDER BY score DESC
+  const results = await db.execute(sql`
+    WITH vector_matches AS (
+      SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> ${formattedVector}::vector) AS rank
+      FROM documents
+      WHERE status = 'published'
+      ORDER BY embedding <=> ${formattedVector}::vector
+      LIMIT 50
+    ),
+    text_matches AS (
+      SELECT id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(fts, websearch_to_tsquery('english', ${queryText})) DESC) AS rank
+      FROM documents
+      WHERE fts @@ websearch_to_tsquery('english', ${queryText})
+      LIMIT 50
+    )
+    SELECT
+      d.id,
+      d.content,
+      COALESCE(1.0 / (${k} + v.rank), 0.0) +
+      COALESCE(1.0 / (${k} + t.rank), 0.0) AS rrf_score
+    FROM documents d
+    LEFT JOIN vector_matches v ON d.id = v.id
+    LEFT JOIN text_matches t ON d.id = t.id
+    WHERE v.id IS NOT NULL OR t.id IS NOT NULL
+    ORDER BY rrf_score DESC
     LIMIT ${limit};
   `);
-  return result;
+
+  return results.rows as unknown as SearchResult[];
 }
 ```
 
+#### Recipe 2: Two-Stage Re-Ranking Pipeline with FlashRank (Node.js / TypeScript)
+```typescript
+import { FlashRankRegistry } from 'flashrank';
+
+const ranker = new FlashRankRegistry();
+
+export async function rerankCandidates(query: string, candidates: { id: string; text: string }[], topN = 5) {
+  const passages = candidates.map(c => ({ id: c.id, text: c.text }));
+  
+  // Ultra-fast client/server cross-encoder re-ranking
+  const reranked = await ranker.rerank({
+    query,
+    passages,
+    model: 'ms-marco-TinyBERT-L-2-v2', // Lightweight, 2ms latency
+  });
+
+  return reranked.slice(0, topN);
+}
+```
+
+---
+
+### Implementation Checklist
+- [ ] Create `HNSW` index in PostgreSQL: `CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);`
+- [ ] Configure `hnsw.ef_search = 100` for high-recall queries during production traffic.
+- [ ] Implement Reciprocal Rank Fusion (RRF) with constant `k = 60` instead of arbitrary linear weighting.
+- [ ] Add a Cross-Encoder Re-ranker step before injecting retrieved chunks into the LLM system prompt.
+- [ ] Apply Late Chunking or Contextual Chunking to retain parent document continuity.
+
+## Orchestration & Integration
+- Integrates with: `ai-llm-integration-expert`, `database-orm-expert`, `ai-cost-token-optimizer`, `app-analyzer-optimizer`.
+
 ---
 
 <a name="bahasa-indonesia"></a>
 ## Bahasa Indonesia
 
 ### Deskripsi
-Panduan tingkat produksi untuk Vector Database (pgvector, Qdrant, Pinecone, Milvus), arsitektur RAG, indeks pgvector HNSW, hybrid search (dense + BM25 sparse re-ranking), semantic chunking, dan evaluasi RAG.
+Panduan arsitektur tingkat produksi untuk Vector Database (PostgreSQL `pgvector 0.8+`, Qdrant, LanceDB, Pinecone), arsitektur Deep RAG modern, pencarian HNSW iteratif, **Reciprocal Rank Fusion (RRF)** hybrid retrieval, **Cross-Encoder Re-ranking** (Cohere Rerank v3, FlashRank, BGE-Reranker-v2), dan **Late Chunking** untuk mencegah fragmentasi konteks.
 
 ### Fitur Utama
-- **pgvector & Hybrid Search**: PostgreSQL `pgvector` HNSW indexing, tuning jarak cosine/L2, dan re-ranking BM25.
-- **Arsitektur RAG**: Retrieval Parent-Document, HyDE (Hypothetical Document Embeddings), dan kompresi kontekstual.
-- **Evaluasi RAG**: Scoring kualitas retrieval otomatis menggunakan Ragas dan TruLens.
+1. **pgvector 0.8+ & Indeks HNSW**: Penyimpanan vektor dimensi tinggi, tuning metrik jarak (cosine/inner-product/L2), dan pemindaian HNSW iteratif dengan filter metadata.
+2. **Reciprocal Rank Fusion (RRF)**: Menggabungkan peringkat kata kunci BM25 dengan peringkat semantik vektor menggunakan rumus $RRF(d) = \sum \frac{1}{k + rank(d)}$, jauh lebih akurat daripada pembobotan linear biasa.
+3. **Cross-Encoder Re-ranking**: Pipeline retrieval 2 tahap: ambil 50 kandidat teratas melalui pencarian hybrid, lalu urutkan ulang menjadi 5 dokumen paling relevan menggunakan model cross-encoder.
+4. **Late Chunking**: Melakukan embedding dokumen secara utuh dalam transformer sebelum memecahnya menjadi chunk-chunk terpisah, mempertahankan makna global dokumen.
+5. **Evaluasi RAG**: Pengukuran presisi retrieval dan deteksi halusinasi secara otomatis (Ragas, TruLens, DeepEval).
+
+---
+
+### Resep Implementasi Produksi
+
+#### Resep 1: Pencarian Hybrid RRF dengan Drizzle ORM
+```typescript
+import { sql } from 'drizzle-orm';
+import { db } from '@/lib/db';
+
+export async function cariDokumenRRF(
+  queryVector: number[],
+  queryText: string,
+  limit = 10,
+  k = 60
+) {
+  const vectorStr = JSON.stringify(queryVector);
+
+  const hasil = await db.execute(sql`
+    WITH vector_matches AS (
+      SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> ${vectorStr}::vector) AS rank
+      FROM documents
+      WHERE status = 'published'
+      ORDER BY embedding <=> ${vectorStr}::vector
+      LIMIT 50
+    ),
+    text_matches AS (
+      SELECT id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(fts, websearch_to_tsquery('english', ${queryText})) DESC) AS rank
+      FROM documents
+      WHERE fts @@ websearch_to_tsquery('english', ${queryText})
+      LIMIT 50
+    )
+    SELECT
+      d.id,
+      d.content,
+      COALESCE(1.0 / (${k} + v.rank), 0.0) +
+      COALESCE(1.0 / (${k} + t.rank), 0.0) AS skor_rrf
+    FROM documents d
+    LEFT JOIN vector_matches v ON d.id = v.id
+    LEFT JOIN text_matches t ON d.id = t.id
+    WHERE v.id IS NOT NULL OR t.id IS NOT NULL
+    ORDER BY skor_rrf DESC
+    LIMIT ${limit};
+  `);
+
+  return hasil.rows;
+}
+```
+
+#### Resep 2: Pipeline Re-Ranking dengan FlashRank (Node.js / TypeScript)
+```typescript
+import { FlashRankRegistry } from 'flashrank';
+
+const ranker = new FlashRankRegistry();
+
+export async function susunUlangKandidat(kueri: string, kandidat: { id: string; text: string }[], topN = 5) {
+  const passages = kandidat.map(c => ({ id: c.id, text: c.text }));
+  
+  const hasilRerank = await ranker.rerank({
+    query: kueri,
+    passages,
+    model: 'ms-marco-TinyBERT-L-2-v2',
+  });
+
+  return hasilRerank.slice(0, topN);
+}
+```
+
+---
+
+### Checklist Implementasi
+- [ ] Buat indeks `HNSW` di PostgreSQL: `CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);`
+- [ ] Konfigurasikan `hnsw.ef_search = 100` untuk kueri dengan recall tinggi di lingkungan produksi.
+- [ ] Terapkan Reciprocal Rank Fusion (RRF) dengan konstanta `k = 60` alih-alih pembobotan linear manual.
+- [ ] Tambahkan langkah Cross-Encoder Re-ranker sebelum menyuntikkan konteks ke prompt LLM.
+- [ ] Terapkan Late Chunking agar konteks dokumen utuh tidak hilang saat dipotong.
+
+## Integrasi Orkestrasi
+- Terintegrasi dengan: `ai-llm-integration-expert`, `database-orm-expert`, `ai-cost-token-optimizer`, `app-analyzer-optimizer`.

package/skills/vercel-ai-sdk-expert/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: vercel-ai-sdk-expert
+description: "Expert guide for Vercel AI SDK (Core, UI, RSC), streaming structured data, multi-provider model switching, tool calling loops, and React 19/Next.js 15 AI engineering / Panduan ahli Vercel AI SDK, streaming data terstruktur, dan integrasi AI pada React 19/Next.js 15."
+author: vibes-plug-swarm
+---
+
+# Vercel AI SDK Expert (Core, UI & Fullstack AI Engineering)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+Connects and orchestrates with domain skills like `senior-frontend`, `nextjs-app-router-expert`, `ai-llm-integration-expert`, `ui-components-expert`, and `multi-agent-orchestration` to deliver reactive, streaming AI interfaces.
+
+### Description
+Production-grade guide for building AI applications using the **Vercel AI SDK (Core & UI)**. Covers unified model provider abstraction (`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/google`), streaming text and structured objects (`streamText`, `streamObject`), dynamic multi-step tool execution loops with `maxSteps`, client-side React 19 hooks (`useChat`, `useCompletion`), streaming data attachments (`createDataStreamResponse`), and generative UI rendering.
+
+**Swarm Synergy:** Within the **Frontend & UI Swarm**, this skill serves as the AI UI Presentation Lead. It translates complex backend multi-agent outputs and streaming tokens into accessible, beautiful web components in Phase 4 & Phase 5.
+
+### Trigger Conditions
+- Integrating conversational chat, streaming completions, or generative UI in React 19 / Next.js 15.
+- Implementing structured data extraction using `generateObject` or `streamObject` with Zod schemas.
+- Building autonomous multi-step tool-calling loops on Next.js Route Handlers or Server Actions.
+- Switching seamlessly across frontier providers (Claude 3.7 Sonnet, Gemini 3.8 Flash, OpenAI o3/GPT-4.5, Ollama).
+- Building streaming data channels with custom metadata, tool status indicators, and citations.
+
+### Vercel AI SDK Architecture (Core vs UI)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       CLIENT LAYER                          │
+│  useChat / useCompletion / Generative UI React Components    │
+│  • Optimistic updates  • Stream reader  • Tool invocation   │
+└──────────────────────────────▲──────────────────────────────┘
+                               │ HTTP SSE / Data Stream Protocol
+┌──────────────────────────────▼──────────────────────────────┐
+│                    SERVER ROUTE / ACTION                    │
+│  streamText({                                               │
+│    model: anthropic('claude-3-7-sonnet-20250219'),          │
+│    tools: { weatherTool, dbQueryTool },                     │
+│    maxSteps: 5,                                             │
+│  }).toDataStreamResponse()                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Implementation Guidelines
+
+#### 1. Next.js 15 Route Handler with Multi-Step Tool Calling Loop
+Use `streamText` with `maxSteps` to enable the model to autonomously call tools, review results, and continue reasoning:
+```typescript
+// app/api/chat/route.ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText, tool } from 'ai';
+import { z } from 'zod';
+
+export const maxDuration = 60; // Allow long-running agentic reasoning
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: anthropic('claude-3-7-sonnet-20250219'),
+    messages,
+    maxSteps: 5, // Enables iterative tool calling loop
+    tools: {
+      calculateMetrics: tool({
+        description: 'Computes analytical metrics from raw time series data',
+        parameters: z.object({
+          datasetId: z.string(),
+          metricType: z.enum(['p95_latency', 'error_rate', 'throughput']),
+        }),
+        execute: async ({ datasetId, metricType }) => {
+          const data = await fetchDatasetMetrics(datasetId, metricType);
+          return { datasetId, metricType, value: data.result };
+        },
+      }),
+    },
+    system: 'You are an elite software performance auditor. Always back up your conclusions with data tool outputs.',
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+#### 2. Streaming Type-Safe Structured Objects (`streamObject`)
+Stream structured JSON objects directly into the UI while generating:
+```typescript
+import { google } from '@ai-sdk/google';
+import { streamObject } from 'ai';
+import { z } from 'zod';
+
+export async function POST(req: Request) {
+  const { codeDiff } = await req.json();
+
+  const result = streamObject({
+    model: google('gemini-2.5-flash'),
+    schema: z.object({
+      securityVulnerabilities: z.array(z.object({
+        severity: z.enum(['low', 'medium', 'high', 'critical']),
+        cwe: z.string(),
+        explanation: z.string(),
+        suggestedFix: z.string(),
+      })),
+      overallRiskScore: z.number().min(0).max(100),
+      passesReview: z.boolean(),
+    }),
+    prompt: `Audit the following git diff for security regressions:\n${codeDiff}`,
+  });
+
+  return result.toTextStreamResponse();
+}
+```
+
+#### 3. Client Hook Integration (`useChat` with Tool Invocations)
+Render real-time streaming tokens, loading skeletons, and interactive tool call results:
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export function AgenticChat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    maxSteps: 5,
+  });
+
+  return (
+    <div className="flex flex-col h-[600px] w-full max-w-2xl mx-auto border rounded-xl p-4 bg-background">
+      <div className="flex-1 overflow-y-auto space-y-4 pr-2">
+        {messages.map((m) => (
+          <div key={m.id} className={`flex ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}>
+            <div className={`p-3 rounded-lg max-w-[80%] ${m.role === 'user' ? 'bg-primary text-primary-foreground' : 'bg-muted'}`}>
+              <div className="whitespace-pre-wrap">{m.content}</div>
+              {m.toolInvocations?.map((toolInvocation) => (
+                <div key={toolInvocation.toolCallId} className="mt-2 text-xs p-2 bg-black/10 rounded">
+                  <span className="font-semibold">Tool [{toolInvocation.toolName}]:</span>{' '}
+                  {'result' in toolInvocation ? JSON.stringify(toolInvocation.result) : 'Executing...'}
+                </div>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+      <form onSubmit={handleSubmit} className="flex gap-2 pt-3 border-t">
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Ask the agent..."
+          className="flex-1 px-3 py-2 border rounded-md"
+        />
+        <button type="submit" disabled={isLoading} className="px-4 py-2 bg-primary text-primary-foreground rounded-md">
+          Send
+        </button>
+      </form>
+    </div>
+  );
+}
+```
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `senior-frontend`, `nextjs-app-router-expert`, `ai-llm-integration-expert`, `ui-components-expert`, dan `multi-agent-orchestration` untuk menghadirkan antarmuka AI yang reaktif dan berlatensi rendah.
+
+### Deskripsi
+Panduan produksi untuk membangun aplikasi AI menggunakan **Vercel AI SDK (Core & UI)**. Mencakup abstraksi penyedia model terpadu (`@ai-sdk/anthropic`, `@ai-sdk/openai`, `@ai-sdk/google`), streaming teks dan objek terstruktur (`streamText`, `streamObject`), siklus eksekusi tool multi-langkah otonom dengan `maxSteps`, hook klien React 19 (`useChat`, `useCompletion`), streaming respons saluran data (`createDataStreamResponse`), dan rendering Generative UI.
+
+**Sinergi Swarm:** Di dalam **Frontend & UI Swarm**, skill ini berperan sebagai Pemimpin Presentasi UI AI. Skill ini bertugas mentransformasikan keluaran multi-agen backend dan token streaming menjadi komponen web yang interaktif, aksesibel, dan elegan pada Fase 4 & Fase 5.
+
+### Kondisi Pemicu
+- Mengintegrasikan chat percakapan, streaming respons, atau generative UI di React 19 / Next.js 15.
+- Menerapkan ekstraksi data terstruktur dengan validasi skema Zod via `generateObject` atau `streamObject`.
+- Membangun loop pemanggilan tool (*tool-calling loops*) multi-langkah di Route Handler atau Server Actions.
+- Beralih fleksibel antar penyedia model frontier (Claude 3.7 Sonnet, Gemini 3.8 Flash, OpenAI o3/GPT-4.5, Ollama).
+- Mengelola status eksekusi tool, indikator loading, dan rendering komponen UI secara dinamis saat streaming berlangsung.

package/skills/visual-qa-vision-agent/SKILL.md

@@ -1,65 +1,71 @@
----
-name: visual-qa-vision-agent
-description: "Equips the AI agent with visual QA capabilities using Playwright/Puppeteer and the agent's innate Vision capabilities to self-correct UI layout, CSS alignment, and visual regressions."
+---
+name: visual-qa-vision-agent
+description: "Equips the AI agent with visual QA capabilities using Playwright/Puppeteer and the agent's innate Vision capabilities to self-correct UI layout, CSS alignment, and visual regressions."
 author: "Roedy Rustam"
----
-
-# Visual QA & Vision Agent
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-This skill transforms the agent from a blind code generator into a visual designer. Instead of hoping the CSS looks correct, the agent is instructed to write a script that takes a screenshot of the newly created component, analyzes the screenshot using its own Vision AI capabilities, and iteratively tweaks the CSS until it matches the design intent perfectly.
-
-### Trigger Conditions
-Activate this skill when the user says:
-- "Fix the CSS, the button is misaligned."
-- "Make it look exactly like this mockup."
-- "Ensure the UI is responsive on mobile screens."
-
-### Core Concepts
-
-#### 1. The Visual QA Loop
-1. **Code:** The agent writes the HTML/CSS/React component.
-2. **Serve:** The agent starts a local dev server in the background.
-3. **Capture:** The agent runs a quick Playwright/Puppeteer script to take screenshots at various viewports (Mobile, Tablet, Desktop).
-4. **Analyze:** The agent receives the screenshot (via the `view_file` tool on the image) and analyzes the visual hierarchy, contrast, and alignment.
-5. **Correct:** The agent fixes margin, padding, or flexbox issues based on what it *saw*, not just what the code says.
-
-#### 2. Agent Constraints (Mandatory Visual Verification)
-- **NO BLIND CSS GUESSING**: You are strictly prohibited from finalizing a frontend component without verifying it visually first. You MUST use a `browser_subagent` to capture a screenshot of your work.
-- **Pixel-Perfect Validation**: Compare the screenshot against the initial design spec or generic UI/UX best practices. Iterate on the CSS until the visual output is flawless.
-- Always check contrast ratios visually if design tokens are overridden.
-
----
-
-### Integration with Other Skills (MANDATORY)
-- `browser-automation-expert` — Provides the Playwright code needed to capture the screenshots.
-- `tailwind-expert` — Provides the CSS utility classes used to fix the alignment issues discovered by Vision.
-- `ui-components-expert` — Defines the correct visual standards (spacing, sizing) the agent should look for.
-
-### Referenced By Orchestrators (MANDATORY)
-- `brainstorming` — Add to "UI/UX & Design Systems".
-- `zero-to-prod-orchestrator` — Phase 5 (Frontend / UI Validation).
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Skill ini memanfaatkan kemampuan *Vision* (penglihatan) bawaan AI untuk melakukan *Quality Assurance* (QA) visual. Agen tidak lagi sekadar menebak CSS secara buta, melainkan mengambil *screenshot* dari halaman yang dibuatnya, melihat hasilnya, dan mengkoreksi *margin/padding* secara mandiri.
-
-### Kondisi Pemicu
-- Saat pengguna meminta untuk merapikan UI yang berantakan.
-- Saat melakukan *cloning* desain dari gambar *mockup*.
-
-### Panduan Singkat
-- **Gunakan Mata Anda (Wajib Verifikasi Visual):** Anda dilarang keras memfinalisasi atau menyelesaikan tugas frontend tanpa melihat hasilnya terlebih dahulu. Anda WAJIB mengambil *screenshot*, melihatnya menggunakan tool `view_file`, dan memverifikasi layout secara visual (*pixel-perfect*).
-- **Siklus Visual:** Tulis Kode ➔ Ambil Screenshot ➔ Analisis dengan *Vision* ➔ Perbaiki Tailwind/CSS ➔ Selesai.
-- **Jangan Menebak:** Terkadang `justify-center` tidak berfungsi karena ada pembungkus (*wrapper*) absolut. Jangan menebak-nebak di dalam kode; lihat hasil akhirnya secara visual!
+---
+
+# Visual QA & Vision Agent
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `project-context-mapper` to ensure cohesive execution.
+
+### Description
+This skill transforms the agent from a blind code generator into a visual designer. Instead of hoping the CSS looks correct, the agent is instructed to write a script that takes a screenshot of the newly created component, analyzes the screenshot using its own Vision AI capabilities, and iteratively tweaks the CSS until it matches the design intent perfectly.
+
+### Trigger Conditions
+Activate this skill when the user says:
+- "Fix the CSS, the button is misaligned."
+- "Make it look exactly like this mockup."
+- "Ensure the UI is responsive on mobile screens."
+
+### Core Concepts
+
+#### 1. The Visual QA Loop
+1. **Code:** The agent writes the HTML/CSS/React component.
+2. **Serve:** The agent starts a local dev server in the background.
+3. **Capture:** The agent runs a quick Playwright/Puppeteer script to take screenshots at various viewports (Mobile, Tablet, Desktop).
+4. **Analyze:** The agent receives the screenshot (via the `view_file` tool on the image) and analyzes the visual hierarchy, contrast, and alignment.
+5. **Correct:** The agent fixes margin, padding, or flexbox issues based on what it *saw*, not just what the code says.
+
+#### 2. Agent Constraints (Mandatory Visual Verification)
+- **NO BLIND CSS GUESSING**: You are strictly prohibited from finalizing a frontend component without verifying it visually first. You MUST use a `browser_subagent` to capture a screenshot of your work.
+- **Pixel-Perfect Validation**: Compare the screenshot against the initial design spec or generic UI/UX best practices. Iterate on the CSS until the visual output is flawless.
+- Always check contrast ratios visually if design tokens are overridden.
+
+---
+
+### Integration with Other Skills (MANDATORY)
+- `browser-automation-expert` — Provides the Playwright code needed to capture the screenshots.
+- `tailwind-expert` — Provides the CSS utility classes used to fix the alignment issues discovered by Vision.
+- `ui-components-expert` — Defines the correct visual standards (spacing, sizing) the agent should look for.
+
+### Referenced By Orchestrators (MANDATORY)
+- `brainstorming` — Add to "UI/UX & Design Systems".
+- `zero-to-prod-orchestrator` — Phase 5 (Frontend / UI Validation).
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+
+### Deskripsi
+Skill ini memanfaatkan kemampuan *Vision* (penglihatan) bawaan AI untuk melakukan *Quality Assurance* (QA) visual. Agen tidak lagi sekadar menebak CSS secara buta, melainkan mengambil *screenshot* dari halaman yang dibuatnya, melihat hasilnya, dan mengkoreksi *margin/padding* secara mandiri.
+
+### Kondisi Pemicu
+- Saat pengguna meminta untuk merapikan UI yang berantakan.
+- Saat melakukan *cloning* desain dari gambar *mockup*.
+
+### Panduan Singkat
+- **Gunakan Mata Anda (Wajib Verifikasi Visual):** Anda dilarang keras memfinalisasi atau menyelesaikan tugas frontend tanpa melihat hasilnya terlebih dahulu. Anda WAJIB mengambil *screenshot*, melihatnya menggunakan tool `view_file`, dan memverifikasi layout secara visual (*pixel-perfect*).
+- **Siklus Visual:** Tulis Kode ➔ Ambil Screenshot ➔ Analisis dengan *Vision* ➔ Perbaiki Tailwind/CSS ➔ Selesai.
+- **Jangan Menebak:** Terkadang `justify-center` tidak berfungsi karena ada pembungkus (*wrapper*) absolut. Jangan menebak-nebak di dalam kode; lihat hasil akhirnya secara visual!