vibes-plug 2.5.0 → 2.14.1

package/skills/pwa-offline-first-expert/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: pwa-offline-first-expert
+description: "Expert guide for Local-First & Offline-First architectures, CRDT conflict-free sync (RxDB, ElectricSQL, PowerSync), OPFS SQLite, Service Worker v3, and PWABuilder deployment / Panduan ahli arsitektur Offline-First & Local-First PWA."
+author: "Roedy Rustam"
+---
+
+# PWA & Offline-First Expert (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for building enterprise-grade **Local-First** and **Progressive Web Applications (PWA)**. Eliminates loading spinners by reading and writing to local databases (OPFS SQLite, RxDB, IndexedDB) first, replicating seamlessly in the background with zero conflict (CRDTs, ElectricSQL, PowerSync), and packaging to native stores via PWABuilder.
+
+### Trigger Conditions
+- Applications requiring full offline functionality (field operations, mobile dashboards, transit apps).
+- User experience demands 0ms local read/write latency without loading spinners.
+- Multi-device sync architecture with automatic conflict resolution.
+- Packaging web apps for distribution on Google Play Store, iOS Safari PWA, or Microsoft Store.
+
+---
+
+## 1. The Local-First Principles (2026 Standard)
+
+1. **No Spinners for Local Data**: UI reads and writes to local storage (OPFS / IndexedDB) synchronously. Latency is always 0ms.
+2. **Multi-Device Conflict-Free Replication**: Changes replicate in the background using CRDTs or central event logs (ElectricSQL / PowerSync).
+3. **Network is an Enhancement**: App is 100% functional on an airplane or subway without internet.
+4. **User Owns Their Data**: Data persists on client hardware first; cloud server is a backup/sync relay.
+
+---
+
+## 2. Production Recipe: Service Worker Caching (Workbox v7 / Native SW)
+
+```typescript
+// sw.ts - Production Service Worker with Stale-While-Revalidate
+/// <reference lib="webworker" />
+declare const self: ServiceWorkerGlobalScope;
+
+const CACHE_NAME = 'app-v2.11.0-cache';
+const STATIC_ASSETS = [
+  '/',
+  '/index.html',
+  '/manifest.json',
+  '/styles/global.css',
+  '/icons/icon-512x512.png',
+];
+
+// 1. Install & Pre-cache critical application shell
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
+  );
+  self.skipWaiting();
+});
+
+// 2. Activate & Clean stale caches
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(
+        keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k))
+      )
+    )
+  );
+  self.clients.claim();
+});
+
+// 3. Stale-While-Revalidate Strategy for Navigation & API GETs
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+
+  // Ignore POST/PUT/DELETE mutations (handled by offline sync queues)
+  if (request.method !== 'GET') return;
+
+  event.respondWith(
+    caches.open(CACHE_NAME).then(async (cache) => {
+      const cachedResponse = await cache.match(request);
+      
+      const fetchPromise = fetch(request)
+        .then((networkResponse) => {
+          if (networkResponse.status === 200) {
+            cache.put(request, networkResponse.clone());
+          }
+          return networkResponse;
+        })
+        .catch(() => cachedResponse || Response.error());
+
+      return cachedResponse || fetchPromise;
+    })
+  );
+});
+
+// 4. Background Sync for offline mutations
+self.addEventListener('sync', (event: any) => {
+  if (event.tag === 'sync-mutations') {
+    event.waitUntil(flushOfflineMutationQueue());
+  }
+});
+
+async function flushOfflineMutationQueue() {
+  // Read pending mutations from IndexedDB and POST to backend
+}
+```
+
+---
+
+## 3. Production Recipe: Local-First Database Sync with RxDB (TypeScript)
+
+```typescript
+// local-db.ts - Reactive Offline-First Database with Background Replication
+import { createRxDatabase, addRxPlugin } from 'rxdb';
+import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie';
+import { replicateGraphQL } from 'rxdb/plugins/replication-graphql';
+
+export interface TaskDocType {
+  id: string;
+  title: string;
+  isCompleted: boolean;
+  updatedAt: string;
+}
+
+const taskSchema = {
+  version: 0,
+  primaryKey: 'id',
+  type: 'object',
+  properties: {
+    id: { type: 'string', maxLength: 100 },
+    title: { type: 'string' },
+    isCompleted: { type: 'boolean' },
+    updatedAt: { type: 'string', format: 'date-time' },
+  },
+  required: ['id', 'title', 'isCompleted', 'updatedAt'],
+};
+
+export async function initLocalDB() {
+  const db = await createRxDatabase({
+    name: 'app_local_db',
+    storage: getRxStorageDexie(),
+  });
+
+  await db.addCollections({
+    tasks: { schema: taskSchema },
+  });
+
+  // Background Replication with Server (GraphQL / REST Sync)
+  replicateGraphQL({
+    collection: db.tasks,
+    url: 'https://api.myapp.com/graphql',
+    pull: {
+      queryBuilder: (doc) => ({
+        query: `query { syncTasks(since: "${doc ? doc.updatedAt : 0}") { id title isCompleted updatedAt } }`,
+        variables: {},
+      }),
+      modifier: (doc) => doc,
+    },
+    push: {
+      queryBuilder: (doc) => ({
+        query: `mutation { pushTask(task: ${JSON.stringify(doc)}) { id } }`,
+        variables: {},
+      }),
+      batchSize: 10,
+    },
+    live: true,
+    retryTime: 1000 * 5, // Auto-retry on network reconnection
+  });
+
+  return db;
+}
+```
+
+---
+
+## 4. App Store Distribution: PWABuilder Standard
+
+To distribute your web application on **Google Play Store** (TWA - Trusted Web Activity) and **Microsoft Windows Store**:
+1. Ensure Web App Manifest has:
+   - `display: "standalone"`
+   - `id: "/?source=pwa"`
+   - `icons`: At least 192x192 and 512x512 maskable PNGs.
+   - `shortcuts` for rapid action launching.
+2. Generate signed Android APK/AAB or Windows MSIX packages using:
+   ```bash
+   npx @pwabuilder/cli https://myapp.com
+   ```
+
+---
+
+## Orchestration & Integration
+
+- **`senior-frontend`**: For UI integration with offline state bars and optimistic mutation hooks.
+- **`state-management-expert`**: For connecting RxDB / local stores with Zustand or TanStack Store.
+- **`database-orm-expert`**: For designing compatible backend schemas with ElectricSQL / Postgres.
+- **`mobile-push-notification-expert`**: For Web Push Notification subscription handling.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk membangun aplikasi web **Local-First** dan **Progressive Web Applications (PWA)** kelas enterprise. Menghilangkan ketergantungan loading spinner dengan membaca dan menulis langsung ke database lokal (OPFS SQLite, RxDB, IndexedDB) terlebih dahulu, sinkronisasi otomatis di latar belakang tanpa bentrok data (CRDTs, ElectricSQL, PowerSync), dan packaging ke toko aplikasi native melalui PWABuilder.
+
+### Kondisi Pemicu
+- Aplikasi yang memerlukan fungsionalitas offline penuh (pekerjaan lapangan, dashboard mobile, aplikasi transit).
+- Tuntutan pengalaman pengguna dengan latensi baca/tulis lokal 0ms tanpa loading spinner.
+- Arsitektur sinkronisasi multi-perangkat dengan resolusi konflik data otomatis.
+- Kebutuhan rilis aplikasi web ke Google Play Store, iOS Safari PWA, atau Microsoft Store.
+
+### Ringkasan Prinsip Local-First & PWA
+1. **0ms Latensi Lokal**: Komponen membaca dan menulis ke IndexedDB / OPFS lokal secara instan.
+2. **Sinkronisasi Reaktif Latar Belakang**: Replikasi data berjalan di background worker; mutasi offline dicatat dalam antrean IndexedDB dan di-flush saat jaringan online.
+3. **Pola Service Worker**: Stale-While-Revalidate untuk asset statis dan rute shell utama menggunakan Service Worker v3.
+4. **Distribusi Native**: Menggunakan PWABuilder CLI untuk menghasilkan APK Android TWA dan paket MSIX Windows.
+
+---
+
+## Integrasi Orkestrasi
+
+- **`senior-frontend`**: Integrasi UI indikator status offline dan hook mutasi optimistik.
+- **`state-management-expert`**: Menghubungkan RxDB / local storage ke Zustand atau TanStack Store.
+- **`database-orm-expert`**: Perancangan skema backend PostgreSQL yang kompatibel dengan replikasi CRDT / ElectricSQL.
+- **`mobile-push-notification-expert`**: Penanganan registrasi dan subscription Web Push Notification.

package/skills/pydantic-ai-expert/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: pydantic-ai-expert
+description: "Expert guide for type-safe Python AI agent development with Pydantic AI — dependency injection, structured outputs, model-agnostic routing, and graph workflows / Panduan ahli pengembangan agen AI Python type-safe dengan Pydantic AI."
+author: vibes-plug-swarm
+---
+
+# Pydantic AI Expert (Type-Safe Python Agent Engineering)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+Connects and orchestrates with domain skills like `python-programming-expert`, `multi-agent-orchestration`, `ai-llm-integration-expert`, `ai-evals-benchmark-expert`, and `database-orm-expert` to engineer type-safe, resilient backend AI agents.
+
+### Description
+Production-grade guide for building enterprise AI agents using **Pydantic AI** (from the creators of Pydantic). Unlike untyped or fragile agent libraries, Pydantic AI provides strict static typing (`Agent[DepsType, ReturnType]`), first-class dependency injection (`RunContext[Deps]`), automatic tool parameter validation via Pydantic v2 schemas, model-agnostic provider switching (Anthropic, OpenAI, Gemini, Groq, Ollama), dynamic system prompts, and deterministic structured outputs.
+
+**Swarm Synergy:** Within the **Backend & APIs Swarm**, this skill serves as the Lead Python Agent Engineer. It executes critical business operations, runs data pipelines, and integrates with SQL databases with compile-time type safety in Phase 4.
+
+### Trigger Conditions
+- Engineering Python-based autonomous agents requiring strict type safety and schema validation.
+- Implementing dependency injection (passing database connections, API clients, or user sessions) into agent tools.
+- Extracting guaranteed structured outputs from frontier reasoning models without JSON parsing errors.
+- Designing multi-agent delegation or agent handoffs in Python microservices.
+- Running unit tests and deterministic evals on agent logic using mock models (`TestModel`).
+
+### Pydantic AI Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AGENT DEFINITION                         │
+│  Agent[DatabaseDeps, AuditReport](                          │
+│    model='anthropic:claude-3-7-sonnet-latest',              │
+│    result_type=AuditReport,                                 │
+│  )                                                          │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+       ┌───────────────────────┴───────────────────────┐
+       ▼                                               ▼
+┌──────────────────────────────┐       ┌──────────────────────────────┐
+│     DEPENDENCY INJECTION     │       │     TOOL EXECUTION LOOP      │
+│  RunContext[DatabaseDeps]    │       │  @agent.tool                 │
+│  • Async DB connection pool  │       │  • Auto Pydantic validation  │
+│  • Tenant & session auth     │       │  • Structured error return   │
+└──────────────────────────────┘       └──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│             DETERMINISTIC STRUCTURED RESULT                 │
+│  result.data -> Pydantic BaseModel instance (Validated)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Implementation Guidelines
+
+#### 1. Type-Safe Agent with Dependency Injection
+Pass database pools or HTTP clients directly into tools without global state:
+```python
+from dataclasses import dataclass
+import asyncpg
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent, RunContext
+
+@dataclass
+class DatabaseDeps:
+    pool: asyncpg.Pool
+    tenant_id: str
+
+class UserAnomalyReport(BaseModel):
+    user_id: str
+    risk_score: float = Field(ge=0.0, le=1.0)
+    anomalous_events: list[str]
+    action_recommended: str
+
+# Typed agent: Agent[DependencyType, ResultType]
+security_agent = Agent[DatabaseDeps, UserAnomalyReport](
+    model='google-gla:gemini-2.5-flash',
+    result_type=UserAnomalyReport,
+    system_prompt=(
+        "You are an automated SecOps auditor. Analyze the user access logs provided "
+        "and generate a strictly structured anomaly assessment."
+    ),
+)
+
+@security_agent.system_prompt
+async def add_tenant_context(ctx: RunContext[DatabaseDeps]) -> str:
+    return f"Active Tenant ID: {ctx.deps.tenant_id}. Only audit records matching this tenant."
+
+@security_agent.tool
+async def query_audit_logs(ctx: RunContext[DatabaseDeps], user_id: str, limit: int = 50) -> list[dict]:
+    """Retrieve raw authentication events for a given user from the audit store."""
+    async with ctx.deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            "SELECT event_time, ip_address, action, status FROM audit_logs "
+            "WHERE tenant_id = $1 AND user_id = $2 ORDER BY event_time DESC LIMIT $3",
+            ctx.deps.tenant_id, user_id, limit
+        )
+        return [dict(r) for r in rows]
+
+# Execution:
+async def run_audit(pool: asyncpg.Pool, tenant_id: str, target_user: str) -> UserAnomalyReport:
+    deps = DatabaseDeps(pool=pool, tenant_id=tenant_id)
+    result = await security_agent.run(f"Audit user activity for {target_user}", deps=deps)
+    return result.data  # Guaranteed instance of UserAnomalyReport
+```
+
+#### 2. Model-Agnostic Switching & Local SLM Fallback
+Pydantic AI allows switching between cloud APIs and local Ollama models effortlessly:
+```python
+import os
+from pydantic_ai.models.anthropic import AnthropicModel
+from pydantic_ai.models.ollama import OllamaModel
+
+def get_agent_model():
+    if os.getenv("ENV") == "production":
+        return AnthropicModel('claude-3-7-sonnet-20250219')
+    else:
+        # Zero cost local development with Ollama
+        return OllamaModel(model_name='qwen2.5-coder:7b')
+```
+
+#### 3. Deterministic Testing with `TestModel`
+Write unit tests that verify tool invocations and structured output parsing without calling live LLMs:
+```python
+import pytest
+from pydantic_ai.models.test import TestModel
+
+@pytest.mark.asyncio
+async def test_security_agent_tool_dispatch():
+    # TestModel can simulate deterministic responses or tool calls
+    test_model = TestModel(call_tools=['query_audit_logs'])
+    
+    with security_agent.override(model=test_model):
+        deps = DatabaseDeps(pool=mock_pool, tenant_id="tenant_123")
+        result = await security_agent.run("Audit user 456", deps=deps)
+        assert result.data is not None
+```
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `python-programming-expert`, `multi-agent-orchestration`, `ai-llm-integration-expert`, `ai-evals-benchmark-expert`, dan `database-orm-expert` untuk membangun agen AI backend yang aman secara tipe (*type-safe*) dan tangguh.
+
+### Deskripsi
+Panduan produksi untuk membangun agen AI kelas perusahaan menggunakan **Pydantic AI** (dari pembuat library Pydantic). Tidak seperti library agen yang tidak bertipe statis atau mudah mengalami galat runtime, Pydantic AI menyediakan sistem tipe statis yang ketat (`Agent[DepsType, ReturnType]`), *dependency injection* bawaan kelas satu (`RunContext[Deps]`), validasi parameter tool otomatis melalui skema Pydantic v2, fleksibilitas pergantian model (*model-agnostic*), dan hasil output terstruktur yang terjamin validitasnya.
+
+**Sinergi Swarm:** Di dalam **Backend & APIs Swarm**, skill ini bertindak sebagai Insinyur Agen AI Python Utama. Bertanggung jawab atas eksekusi logika bisnis kritis, orkestrasi pipeline data, dan query database SQL dengan keamanan tipe kompilasi pada Fase 4.
+
+### Kondisi Pemicu
+- Membangun agen otonom Python yang menuntut keamanan tipe statis dan validasi skema data ketat.
+- Menerapkan injeksi dependensi (koneksi database, klien HTTP, session user) ke dalam tool agen tanpa variabel global.
+- Mengekstrak data terstruktur yang dijamin valid dari model penalaran tanpa kegagalan parsing JSON.
+- Merancang delegasi tugas antar agen (*agent handoffs*) pada arsitektur microservices berbasis Python.
+- Menjalankan unit test deterministik dan evaluasi agen dengan `TestModel` tanpa konsumsi token API nyata.