vibes-plug 1.0.0 → 2.11.0

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

@@ -0,0 +1,208 @@
+---
+name: vector-db-rag-expert
+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 (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Purpose & Overview
+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
+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);
+
+  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 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 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
+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/vibe-code-gardener/SKILL.md

@@ -1,173 +1,181 @@
----
-name: vibe-code-gardener
-description: "Purger of AI slop, code bloat, context drift, and architectural decay in vibe-coded projects / Pembersih AI slop, kode membengkak, konteks drift, dan pembusukan arsitektur pada proyek vibe coding."
+---
+name: vibe-code-gardener
+description: "Purger of AI slop, code bloat, context drift, and architectural decay in vibe-coded projects / Pembersih AI slop, kode membengkak, konteks drift, dan pembusukan arsitektur pada proyek vibe coding."
 author: "Roedy Rustam"
----
-
-# Vibe Code Gardener (2026 Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Detects and purges AI-generated code quality issues — AI slop, code bloat, context drift, duplicated logic, dead code, misaligned patterns, and architectural decay in projects that have been heavily vibe-coded.
-
-### Trigger Conditions
-- Codebase has grown out of control after many AI-assisted coding sessions.
-- Duplication, inconsistent patterns, or unexplained abstractions detected.
-- Features are getting harder to add or understand.
-- Tests are brittle or missing entirely.
-- The codebase has "AI smell" — overly verbose comments, unnecessary defensive code, duplicate utilities.
-
-### AI Slop Detection Heuristics (2026)
-
-These are the most common AI-generated code quality issues to look for:
-
-#### 1. The "Just In Case" Over-Engineering
-AI models often add features or abstractions "for extensibility" that are never needed:
-```typescript
-// 🔴 AI SLOP: Factory pattern for something that will never change
-const createUserRepository = (type: 'postgres' | 'mysql' | 'sqlite') => {
-  if (type === 'postgres') return new PostgresUserRepo();
-  // ...never switches in practice
-};
-
-// ✅ CLEAN: Just use the implementation
-const userRepo = new PostgresUserRepo();
-```
-
-#### 2. The "Belt and Suspenders" Duplicate Guards
-AI adds null checks and validations at every layer unnecessarily:
-```typescript
-// 🔴 AI SLOP: Triple-validated (already validated by Zod + DB schema + here)
-if (!user || !user.id || user.id === undefined || user.id === null || typeof user.id !== 'string') { ... }
-
-// ✅ CLEAN: Trust your types
-if (!user.id) { ... }
-```
-
-#### 3. The "Graveyard of Dead Utilities"
-AI-generated helper files with functions that are defined but never used:
-- Search for exported functions with 0 usages: `grep -r "export function" --include="*.ts" | while read...`
-- Remove entire files of dead utilities.
-
-#### 4. Context Drift — Style Inconsistency
-Different sessions produce different coding styles in the same codebase:
-- Some files use `async/await`, others use `.then()` chains.
-- Some use `const` arrow functions, others use `function` declarations.
-- Mixed naming: `userId`, `user_id`, `UserID` in the same project.
-- **Fix**: Run a style unification pass with Prettier + ESLint rules.
-
-#### 5. Comment Pollution
-AI loves to narrate obvious code:
-```typescript
-// 🔴 AI SLOP: Stating the obvious
-// Get the user from the database
-const user = await db.user.findUnique({ where: { id } });
-// Return the user
-return user;
-
-// ✅ CLEAN: No comment needed — code is self-explanatory
-const user = await db.user.findUnique({ where: { id } });
-return user;
-```
-
-#### 6. The Bloated Component
-AI tends to put too much in one component across sessions:
-- Component renders conditionally across 5+ different states.
-- Component has 10+ props.
-- Component imports from 20+ different modules.
-- **Fix**: Apply Single Responsibility — split into sub-components.
-
-#### 7. Dependency Creep
-Each AI session may install new packages for tasks already solvable with existing deps:
-```bash
-# Audit dependencies — find packages doing the same thing
-npx depcheck  # Unused dependencies
-npx bundle-phobia-cli # Bundle size of each dep
-```
-
-### Gardening Protocol
-
-#### Phase 1: Discovery (Read Only)
-1. Map the full file tree.
-2. Identify largest files (likely bloated).
-3. Find duplicated logic with semantic search.
-4. Find unused exports and dead code.
-5. Identify inconsistent patterns across files.
-
-#### Phase 2: Triage
-Categorize issues:
-- **Critical**: Bugs, security holes, data loss risks.
-- **High**: Duplicate business logic that will diverge.
-- **Medium**: Code smells that slow development.
-- **Low**: Style inconsistencies, over-verbose comments.
-
-#### Phase 3: Systematic Refactoring
-Work file by file, smallest changes first:
-1. Remove dead code and unused imports.
-2. Extract duplicated logic into shared utilities.
-3. Simplify over-engineered abstractions.
-4. Standardize naming conventions.
-5. Add missing tests for business-critical paths.
-
-#### Phase 4: Prevention
-- Add ESLint rules to catch common AI slop patterns.
-- Add `depcheck` to CI to catch unused dependencies.
-- Add architecture tests (e.g., `arch-unit`) to enforce layer boundaries.
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Mendeteksi dan membersihkan masalah kualitas kode yang dihasilkan AI — AI slop, kode yang membengkak, context drift, logika yang terduplikasi, kode mati, pola yang tidak konsisten, dan pembusukan arsitektur pada proyek yang banyak menggunakan vibe coding.
-
-### Kondisi Pemicu
-- Codebase telah tumbuh tidak terkendali setelah banyak sesi coding berbantuan AI.
-- Duplikasi, pola tidak konsisten, atau abstraksi yang tidak dapat dijelaskan terdeteksi.
-- Fitur semakin sulit ditambahkan atau dipahami.
-- Test rapuh atau tidak ada sama sekali.
-- Codebase memiliki "AI smell" — komentar yang terlalu verbose, kode defensif yang tidak perlu, utilitas yang diduplikasi.
-
-### Heuristik Deteksi AI Slop (2026)
-
-#### 1. Over-Engineering "Untuk Jaga-Jaga"
-Model AI sering menambahkan fitur atau abstraksi "untuk ekstensibilitas" yang tidak pernah dibutuhkan. Hapus factory pattern, strategy pattern, atau abstraksi lain yang tidak memiliki lebih dari satu implementasi.
-
-#### 2. "Belt and Suspenders" — Validasi Ganda Berlebihan
-AI menambahkan null check dan validasi di setiap layer yang sebenarnya sudah divalidasi oleh Zod, TypeScript, atau skema DB. Percayai tipe Anda.
-
-#### 3. "Kuburan Utilitas Mati"
-File helper yang dihasilkan AI dengan fungsi yang tidak pernah digunakan. Cari dan hapus ekspor dengan 0 penggunaan.
-
-#### 4. Context Drift — Inkonsistensi Gaya
-Sesi yang berbeda menghasilkan gaya koding yang berbeda: sebagian menggunakan `async/await`, yang lain menggunakan `.then()`; penamaan campuran `userId`, `user_id`, `UserID`. Perbaiki dengan satu pass Prettier + aturan ESLint.
-
-#### 5. Polusi Komentar
-AI suka mengomentari kode yang sudah jelas sendiri. Hapus komentar yang hanya mengulang apa yang sudah tertulis dalam kode.
-
-#### 6. Komponen yang Membengkak
-Komponen dengan terlalu banyak kondisi rendering, prop, atau impor. Terapkan Single Responsibility — pecah menjadi sub-komponen.
-
-#### 7. Creep Dependensi
-Setiap sesi AI mungkin menginstal paket baru untuk tugas yang sudah bisa diselesaikan dengan dependensi yang ada. Audit dengan `depcheck` dan `bundle-phobia-cli`.
-
-### Protokol Berkebun
-
-#### Fase 1: Penemuan (Hanya Baca)
-Peta pohon file lengkap, identifikasi file terbesar, temukan logika yang terduplikasi, temukan ekspor yang tidak digunakan.
-
-#### Fase 2: Triase
-Kategorikan masalah: Kritis, Tinggi, Sedang, Rendah.
-
-#### Fase 3: Refactoring Sistematis
-Kerja file per file, perubahan terkecil dulu: hapus kode mati, ekstrak logika duplikat, sederhanakan abstraksi berlebih, standarisasi penamaan, tambahkan test yang hilang.
-
-#### Fase 4: Pencegahan
-Tambahkan aturan ESLint, `depcheck` di CI, dan architecture test untuk menjaga codebase tetap bersih.
+---
+
+# Vibe Code Gardener (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Detects and purges AI-generated code quality issues — AI slop, code bloat, context drift, duplicated logic, dead code, misaligned patterns, and architectural decay in projects that have been heavily vibe-coded.
+
+### Trigger Conditions
+- Codebase has grown out of control after many AI-assisted coding sessions.
+- Duplication, inconsistent patterns, or unexplained abstractions detected.
+- Features are getting harder to add or understand.
+- Tests are brittle or missing entirely.
+- The codebase has "AI smell" — overly verbose comments, unnecessary defensive code, duplicate utilities.
+
+### AI Slop Detection Heuristics (2026)
+
+These are the most common AI-generated code quality issues to look for:
+
+#### 1. The "Just In Case" Over-Engineering
+AI models often add features or abstractions "for extensibility" that are never needed:
+```typescript
+// 🔴 AI SLOP: Factory pattern for something that will never change
+const createUserRepository = (type: 'postgres' | 'mysql' | 'sqlite') => {
+  if (type === 'postgres') return new PostgresUserRepo();
+  // ...never switches in practice
+};
+
+// ✅ CLEAN: Just use the implementation
+const userRepo = new PostgresUserRepo();
+```
+
+#### 2. The "Belt and Suspenders" Duplicate Guards
+AI adds null checks and validations at every layer unnecessarily:
+```typescript
+// 🔴 AI SLOP: Triple-validated (already validated by Zod + DB schema + here)
+if (!user || !user.id || user.id === undefined || user.id === null || typeof user.id !== 'string') { ... }
+
+// ✅ CLEAN: Trust your types
+if (!user.id) { ... }
+```
+
+#### 3. The "Graveyard of Dead Utilities"
+AI-generated helper files with functions that are defined but never used:
+- Search for exported functions with 0 usages: `grep -r "export function" --include="*.ts" | while read...`
+- Remove entire files of dead utilities.
+
+#### 4. Context Drift — Style Inconsistency
+Different sessions produce different coding styles in the same codebase:
+- Some files use `async/await`, others use `.then()` chains.
+- Some use `const` arrow functions, others use `function` declarations.
+- Mixed naming: `userId`, `user_id`, `UserID` in the same project.
+- **Fix**: Run a style unification pass with Prettier + ESLint rules.
+
+#### 5. Comment Pollution
+AI loves to narrate obvious code:
+```typescript
+// 🔴 AI SLOP: Stating the obvious
+// Get the user from the database
+const user = await db.user.findUnique({ where: { id } });
+// Return the user
+return user;
+
+// ✅ CLEAN: No comment needed — code is self-explanatory
+const user = await db.user.findUnique({ where: { id } });
+return user;
+```
+
+#### 6. The Bloated Component
+AI tends to put too much in one component across sessions:
+- Component renders conditionally across 5+ different states.
+- Component has 10+ props.
+- Component imports from 20+ different modules.
+- **Fix**: Apply Single Responsibility — split into sub-components.
+
+#### 7. Dependency Creep
+Each AI session may install new packages for tasks already solvable with existing deps:
+```bash
+# Audit dependencies — find packages doing the same thing
+npx depcheck  # Unused dependencies
+npx bundle-phobia-cli # Bundle size of each dep
+```
+
+### Gardening Protocol
+
+#### Phase 1: Discovery (Read Only)
+1. Map the full file tree.
+2. Identify largest files (likely bloated).
+3. Find duplicated logic with semantic search.
+4. Find unused exports and dead code.
+5. Identify inconsistent patterns across files.
+
+#### Phase 2: Triage
+Categorize issues:
+- **Critical**: Bugs, security holes, data loss risks.
+- **High**: Duplicate business logic that will diverge.
+- **Medium**: Code smells that slow development.
+- **Low**: Style inconsistencies, over-verbose comments.
+
+#### Phase 3: Systematic Refactoring
+Work file by file, smallest changes first:
+1. Remove dead code and unused imports.
+2. Extract duplicated logic into shared utilities.
+3. Simplify over-engineered abstractions.
+4. Standardize naming conventions.
+5. Add missing tests for business-critical paths.
+
+#### Phase 4: Prevention
+- Add ESLint rules to catch common AI slop patterns.
+- Add `depcheck` to CI to catch unused dependencies.
+- Add architecture tests (e.g., `arch-unit`) to enforce layer boundaries.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Mendeteksi dan membersihkan masalah kualitas kode yang dihasilkan AI — AI slop, kode yang membengkak, context drift, logika yang terduplikasi, kode mati, pola yang tidak konsisten, dan pembusukan arsitektur pada proyek yang banyak menggunakan vibe coding.
+
+### Kondisi Pemicu
+- Codebase telah tumbuh tidak terkendali setelah banyak sesi coding berbantuan AI.
+- Duplikasi, pola tidak konsisten, atau abstraksi yang tidak dapat dijelaskan terdeteksi.
+- Fitur semakin sulit ditambahkan atau dipahami.
+- Test rapuh atau tidak ada sama sekali.
+- Codebase memiliki "AI smell" — komentar yang terlalu verbose, kode defensif yang tidak perlu, utilitas yang diduplikasi.
+
+### Heuristik Deteksi AI Slop (2026)
+
+#### 1. Over-Engineering "Untuk Jaga-Jaga"
+Model AI sering menambahkan fitur atau abstraksi "untuk ekstensibilitas" yang tidak pernah dibutuhkan. Hapus factory pattern, strategy pattern, atau abstraksi lain yang tidak memiliki lebih dari satu implementasi.
+
+#### 2. "Belt and Suspenders" — Validasi Ganda Berlebihan
+AI menambahkan null check dan validasi di setiap layer yang sebenarnya sudah divalidasi oleh Zod, TypeScript, atau skema DB. Percayai tipe Anda.
+
+#### 3. "Kuburan Utilitas Mati"
+File helper yang dihasilkan AI dengan fungsi yang tidak pernah digunakan. Cari dan hapus ekspor dengan 0 penggunaan.
+
+#### 4. Context Drift — Inkonsistensi Gaya
+Sesi yang berbeda menghasilkan gaya koding yang berbeda: sebagian menggunakan `async/await`, yang lain menggunakan `.then()`; penamaan campuran `userId`, `user_id`, `UserID`. Perbaiki dengan satu pass Prettier + aturan ESLint.
+
+#### 5. Polusi Komentar
+AI suka mengomentari kode yang sudah jelas sendiri. Hapus komentar yang hanya mengulang apa yang sudah tertulis dalam kode.
+
+#### 6. Komponen yang Membengkak
+Komponen dengan terlalu banyak kondisi rendering, prop, atau impor. Terapkan Single Responsibility — pecah menjadi sub-komponen.
+
+#### 7. Creep Dependensi
+Setiap sesi AI mungkin menginstal paket baru untuk tugas yang sudah bisa diselesaikan dengan dependensi yang ada. Audit dengan `depcheck` dan `bundle-phobia-cli`.
+
+### Protokol Berkebun
+
+#### Fase 1: Penemuan (Hanya Baca)
+Peta pohon file lengkap, identifikasi file terbesar, temukan logika yang terduplikasi, temukan ekspor yang tidak digunakan.
+
+#### Fase 2: Triase
+Kategorikan masalah: Kritis, Tinggi, Sedang, Rendah.
+
+#### Fase 3: Refactoring Sistematis
+Kerja file per file, perubahan terkecil dulu: hapus kode mati, ekstrak logika duplikat, sederhanakan abstraksi berlebih, standarisasi penamaan, tambahkan test yang hilang.
+
+#### Fase 4: Pencegahan
+Tambahkan aturan ESLint, `depcheck` di CI, dan architecture test untuk menjaga codebase tetap bersih.
+
+---
+
+## Orchestration & Integration
+- Integrates with `zero-to-prod-orchestrator`, `brainstorming`, `coderabbit`, and `dependency-upgrade-migrator`.
+
+## Integrasi Orkestrasi
+- Terintegrasi dengan `zero-to-prod-orchestrator`, `brainstorming`, `coderabbit`, dan `dependency-upgrade-migrator`.

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

@@ -0,0 +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."
+author: "Roedy Rustam"
+---
+
+# 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!