vibes-plug 1.0.0 → 2.11.0

package/skills/graph-rag-knowledge-expert/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: graph-rag-knowledge-expert
+description: "Expert guide for Knowledge Graphs, GraphRAG, Microsoft GraphRAG, Neo4j Text2Cypher, multi-hop relational retrieval, and hybrid vector-graph search / Panduan ahli Knowledge Graph, GraphRAG, dan pencarian relasional multi-hop."
+author: "Roedy Rustam"
+---
+
+# GraphRAG & Knowledge Graph Expert (2026 Edition)
+
+Expert guide for implementing Knowledge Graph-augmented Retrieval (GraphRAG), solving the fatal weaknesses of vector search: multi-hop reasoning, relationship discovery, and global corpus understanding. Covers Microsoft GraphRAG, Neo4j Text2Cypher, FalkorDB, and hybrid Vector + Graph retrieval pipelines.
+
+*Panduan ahli untuk implementasi Knowledge Graph dan GraphRAG untuk mengatasi kelemahan mendasar vector search murni dalam pemikiran multi-hop, deteksi relasi entitas tersembunyi, dan ringkasan global korpus.*
+
+---
+
+## 1. Why GraphRAG Over Pure Vector Search?
+
+| Capability | Pure Vector Search (RAG) | GraphRAG (Graph + Vector) |
+| :--- | :--- | :--- |
+| **Direct Similarity ("What is X?")** | 🟢 Fast, accurate | 🟢 High accuracy |
+| **Multi-Hop Traversal ("How does X affect Z via Y?")** | 🔴 Blind (returns fragmented chunks) | 🟢 Explores interconnected graph edges |
+| **Global Corpus Query ("What are the main themes across all documents?")** | 🔴 Fails (limited to Top-K chunks) | 🟢 Hierarchical Community Summaries |
+| **Hallucination Rate on Complex Queries** | 🔴 Moderate to High (context stitching) | 🟢 Grounded in explicit knowledge edges |
+
+---
+
+## 2. Production Recipe: Text2Cypher Knowledge Graph Querying (TypeScript)
+
+Using Neo4j with deterministic schema introspection, preventing arbitrary syntax hallucinations.
+
+```typescript
+// text2cypher.ts - Safe Neo4j Query Generation & Execution
+import neo4j, { Driver } from 'neo4j-driver';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+export class GraphRAGService {
+  private driver: Driver;
+
+  constructor(uri: string, user: string, pass: string) {
+    this.driver = neo4j.driver(uri, neo4j.auth.basic(user, pass));
+  }
+
+  // 1. Fetch live Graph Schema to ground the LLM
+  private async getGraphSchema(): Promise<string> {
+    const session = this.driver.session();
+    try {
+      const result = await session.run(`
+        CALL apoc.meta.schema() YIELD value
+        RETURN value
+      `);
+      return JSON.stringify(result.records[0]?.get('value') || {});
+    } finally {
+      await session.close();
+    }
+  }
+
+  // 2. Synthesize strict read-only Cypher query
+  public async queryGraph(userQuestion: string): Promise<any[]> {
+    const schema = await this.getGraphSchema();
+
+    const { text: cypherQuery } = await generateText({
+      model: openai('gpt-4o-mini'),
+      system: `
+        You are an expert Neo4j Cypher generator.
+        Generate ONLY valid, read-only CYPHER queries based on this schema:
+        ${schema}
+
+        Rules:
+        - Never generate CREATE, MERGE, DELETE, or SET statements.
+        - Always use parameterization where appropriate.
+        - Output ONLY the raw Cypher query, without markdown or backticks.
+      `,
+      prompt: `Translate this question into Cypher: ${userQuestion}`,
+    });
+
+    const sanitizedCypher = cypherQuery.trim().replace(/^```cypher|```$/g, '');
+
+    // 3. Execute with read-only transaction
+    const session = this.driver.session({ defaultAccessMode: neo4j.session.READ });
+    try {
+      const res = await session.run(sanitizedCypher);
+      return res.records.map((r) => r.toObject());
+    } finally {
+      await session.close();
+    }
+  }
+
+  public async close(): Promise<void> {
+    await this.driver.close();
+  }
+}
+```
+
+---
+
+## 3. Production Recipe: Entity & Relation Extraction (Python)
+
+```python
+# graph_extractor.py - Structured Entity & Relation Extraction
+from typing import List
+from pydantic import BaseModel, Field
+import instructor
+from openai import OpenAI
+
+client = instructor.from_openai(OpenAI())
+
+class Entity(BaseModel):
+    name: str = Field(description="Normalized entity name, uppercase")
+    type: str = Field(description="ORGANIZATION, PERSON, TECHNOLOGY, CONCEPT, LOCATION")
+    description: str = Field(description="Summary of entity role")
+
+class Relationship(BaseModel):
+    source_entity: str
+    target_entity: str
+    relation_type: str = Field(description="USES, DEVELOPS, OWNS, LOCATED_IN, DEPENDS_ON")
+    weight: float = Field(default=1.0, ge=0.0, le=1.0)
+    description: str
+
+class KnowledgeGraph(BaseModel):
+    entities: List[Entity]
+    relationships: List[Relationship]
+
+def extract_knowledge_graph(document_text: str) -> KnowledgeGraph:
+    """Extracts entities and relationships from raw text into structured schema."""
+    return client.chat.completions.create(
+        model="gpt-4o-mini",
+        response_model=KnowledgeGraph,
+        messages=[
+            {
+                "role": "system",
+                "content": (
+                    "Extract all named entities and factual relationships between them. "
+                    "Ensure entity names are canonicalized and relationships are directed."
+                ),
+            },
+            {"role": "user", "content": document_text},
+        ],
+        temperature=0.0,
+    )
+```
+
+---
+
+## 4. Microsoft GraphRAG: Hierarchical Communities
+
+For high-level summaries ("Summarize all technical debts reported across the system"):
+1. **Extraction**: Chunk documents ➔ Extract Entities & Relationships.
+2. **Clustering**: Apply **Leiden Algorithm** to detect hierarchical communities (Level 0: Micro, Level 1: Sub-domain, Level 2: Macro domain).
+3. **Summarization**: LLM generates pre-computed summaries for each community cluster.
+4. **Global Search**: Query runs across pre-computed community summaries in parallel, eliminating the need to read millions of tokens at inference time.
+
+---
+
+## Orchestration & Integration
+
+- **`vector-db-rag-expert`**: For hybrid dense-vector similarity search combined with graph path discovery.
+- **`database-orm-expert`**: For maintaining transactional relational mappings alongside graph stores.
+- **`ai-llm-integration-expert`**: Connects reasoning models to multi-hop graph context.
+- **`search-engine-expert`**: For keyword lexical indexing of graph node attributes.

package/skills/graphql-apollo-expert/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: graphql-apollo-expert
+description: "Expert guide for designing and consuming GraphQL APIs. Covers Apollo Server/Client, NestJS GraphQL (Code-First & Schema-First), TypeGraphQL, caching, and N+1 query optimization."
+author: "Roedy Rustam"
+---
+
+# GraphQL & Apollo Expert
+
+[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
+Production-grade guidance for building and consuming **GraphQL APIs**. Focuses on the **Apollo** ecosystem (Apollo Server, Apollo Client, Federation), **NestJS GraphQL** integration, and solving common performance pitfalls like the N+1 query problem using DataLoaders.
+
+### Trigger Conditions
+Activate this skill when the user is:
+- Setting up a GraphQL server with NestJS, Express, or Apollo Server.
+- Using `@apollo/client` or `@vue/apollo-composable` on the frontend.
+- Deciding between Code-First vs. Schema-First GraphQL design.
+- Optimizing backend database queries triggered by GraphQL resolvers (N+1 problem).
+- Implementing GraphQL Subscriptions via WebSockets.
+
+### Core Concepts
+
+#### 1. Code-First vs Schema-First (NestJS)
+- **Code-First (Recommended for TypeScript):** Define resolvers and object types using TS decorators. The schema `.gql` file is automatically generated. Ensures a single source of truth.
+- **Schema-First:** Write raw `.gql` files and use tools to generate TypeScript interfaces.
+
+```typescript
+// NestJS Code-First Example
+import { ObjectType, Field, Int } from '@nestjs/graphql';
+
+@ObjectType()
+export class User {
+  @Field(() => Int)
+  id: number;
+
+  @Field()
+  email: string;
+}
+
+import { Resolver, Query } from '@nestjs/graphql';
+
+@Resolver(() => User)
+export class UserResolver {
+  @Query(() => [User])
+  async users(): Promise<User[]> {
+    return [{ id: 1, email: 'user@example.com' }];
+  }
+}
+```
+
+#### 2. The N+1 Problem & DataLoader
+GraphQL's resolver architecture easily causes the N+1 query problem (e.g., querying authors and their posts results in 1 query for authors, and N queries for each author's posts).
+**Solution:** Always use `DataLoader` to batch and cache database requests within a single GraphQL execution tick.
+
+#### 3. Apollo Client (Frontend)
+Use Apollo Client for robust caching and normalized state management on the frontend.
+```tsx
+import { useQuery, gql } from '@apollo/client';
+
+const GET_USERS = gql`
+  query GetUsers {
+    users {
+      id
+      email
+    }
+  }
+`;
+
+function UserList() {
+  const { loading, error, data } = useQuery(GET_USERS);
+  if (loading) return <p>Loading...</p>;
+  return <div>{data.users[0].email}</div>;
+}
+```
+
+### Integration with Other Skills (MANDATORY)
+This skill works best when combined with:
+- `js-backend-expert` — For setting up the underlying Node.js/NestJS server architecture.
+- `database-orm-expert` — For connecting Prisma/Drizzle ORM directly to GraphQL resolvers and DataLoaders.
+- `senior-frontend` / `vue-frontend-expert` — For integrating Apollo Client into React or Vue applications.
+
+### Referenced By Orchestrators (MANDATORY)
+- `brainstorming` — Add to "API Design & Contracts".
+- `zero-to-prod-orchestrator` — Phase 4 (Backend APIs).
+
+---
+
+<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
+Panduan produksi untuk membangun dan mengkonsumsi API **GraphQL**. Mencakup ekosistem **Apollo**, **NestJS GraphQL**, dan teknik optimasi performa seperti *DataLoader*.
+
+### Kondisi Pemicu
+- Saat mengkonfigurasi server GraphQL menggunakan NestJS atau Apollo.
+- Saat menggunakan Apollo Client di aplikasi React atau Vue.
+- Saat menghadapi masalah performa N+1 query pada resolusi data.
+
+### Panduan Singkat
+- **Pilih Code-First di TypeScript:** Di NestJS atau TypeScript murni, gunakan pendekatan *Code-First* (`@nestjs/graphql` atau TypeGraphQL) agar Anda tidak perlu mengelola file `.gql` dan *interface* TS secara terpisah.
+- **Gunakan DataLoader Wajib:** Jangan pernah melakukan *query* database langsung di dalam resolver yang mengembalikan *list of objects* bersarang. Gunakan `DataLoader` dari Facebook untuk mengumpulkan (batching) request database.
+- **Frontend Caching:** Manfaatkan normalisasi *cache* bawaan Apollo Client agar Anda tidak perlu menggunakan Redux atau state manager lain untuk menyimpan data dari server.

package/skills/headless-cms-expert/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: headless-cms-expert
+description: "Expert guide for Headless CMS integration (Sanity, Payload CMS, Strapi, Contentful, Storyblok) with modern frameworks / Panduan ahli integrasi Headless CMS (Sanity, Payload, Strapi, Contentful) dengan framework modern."
+author: "Roedy Rustam"
+---
+
+# Headless CMS Expert (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+- **`nextjs-app-router-expert`**: SSR/ISR content fetching and caching strategies.
+- **`api-design-expert`**: REST/GraphQL API patterns for CMS queries.
+- **`seo`**: Structured data, sitemaps, and metadata from CMS content.
+- **`astro-framework-expert`**: Content collections and static site generation with CMS.
+- **`rich-text-editor-expert`**: Custom editor components for CMS authoring.
+
+### Description
+Expert guide for selecting, integrating, and optimizing Headless CMS platforms in modern web applications. Covers Sanity v3 (GROQ, Portable Text, Content Lake), Payload CMS 3.x (TypeScript-first, code-defined schemas), Strapi 5 (open-source, self-hosted), Contentful (enterprise, GraphQL), and Storyblok (visual editing). Includes content modeling, preview mode, webhook-based revalidation, and migration strategies.
+
+### Trigger Conditions
+- Choosing or integrating a headless CMS.
+- Building content-driven websites (blogs, docs, marketing sites).
+- Implementing CMS preview/draft mode in Next.js or Astro.
+- Designing content models and structured content schemas.
+- Migrating from WordPress or monolithic CMS to headless.
+
+---
+
+### CMS Selection Guide
+
+| Criteria | Sanity v3 | Payload 3.x | Strapi 5 | Contentful | Storyblok |
+|----------|-----------|-------------|----------|------------|-----------|
+| Hosting | Cloud (free tier) | Self-hosted / Cloud | Self-hosted | Cloud | Cloud |
+| Schema Definition | Code (JS/TS) | Code (TS) | Admin UI / Code | Web UI | Web UI |
+| Query Language | GROQ | REST / GraphQL | REST / GraphQL | GraphQL / REST | REST / GraphQL |
+| Rich Text | Portable Text | Lexical / Slate | Blocks | Rich Text API | Rich Text |
+| TypeScript | ★★★★★ | ★★★★★ | ★★★★ | ★★★ | ★★★ |
+| Real-time | ★★★★★ | ★★★★ | ★★★ | ★★★ | ★★★★ |
+| Visual Editing | Sanity Studio | Admin Panel | Admin Panel | Web App | Visual Editor |
+| **Best For** | Developers | Code-first teams | Open-source fans | Enterprise | Marketing teams |
+
+**Recommendation:** Use **Sanity v3** for developer-heavy teams. Use **Payload CMS** when you need full TypeScript control and self-hosting. Use **Strapi** for open-source requirements.
+
+### Core Patterns
+
+#### 1. Sanity v3 Integration
+
+```typescript
+// sanity.config.ts — Schema-as-code
+import { defineConfig, defineField, defineType } from 'sanity';
+
+export const postSchema = defineType({
+  name: 'post',
+  title: 'Blog Post',
+  type: 'document',
+  fields: [
+    defineField({ name: 'title', type: 'string', validation: (r) => r.required() }),
+    defineField({ name: 'slug', type: 'slug', options: { source: 'title' } }),
+    defineField({ name: 'body', type: 'array', of: [{ type: 'block' }] }),
+    defineField({ name: 'publishedAt', type: 'datetime' }),
+  ],
+});
+```
+
+```typescript
+// Fetching with GROQ in Next.js App Router
+import { createClient } from 'next-sanity';
+
+const client = createClient({
+  projectId: process.env.SANITY_PROJECT_ID!,
+  dataset: 'production',
+  apiVersion: '2026-08-01',
+  useCdn: true,
+});
+
+// Server Component
+async function BlogPage() {
+  const posts = await client.fetch(
+    `*[_type == "post"] | order(publishedAt desc) {
+      title, slug, publishedAt,
+      "excerpt": array::join(string::split(pt::text(body), "")[0..200], "")
+    }`
+  );
+  return <PostList posts={posts} />;
+}
+```
+
+#### 2. Payload CMS 3.x Integration
+
+```typescript
+// payload.config.ts
+import { buildConfig } from 'payload';
+import { postgresAdapter } from '@payloadcms/db-postgres';
+import { lexicalEditor } from '@payloadcms/richtext-lexical';
+
+export default buildConfig({
+  db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URL! } }),
+  editor: lexicalEditor(),
+  collections: [
+    {
+      slug: 'posts',
+      fields: [
+        { name: 'title', type: 'text', required: true },
+        { name: 'content', type: 'richText' },
+        { name: 'status', type: 'select', options: ['draft', 'published'] },
+      ],
+    },
+  ],
+});
+```
+
+#### 3. Webhook Revalidation (Next.js)
+
+```typescript
+// app/api/revalidate/route.ts
+import { revalidateTag } from 'next/cache';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const secret = req.headers.get('x-webhook-secret');
+  if (secret !== process.env.REVALIDATION_SECRET) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const body = await req.json();
+  revalidateTag(body._type); // Revalidate by content type
+  return NextResponse.json({ revalidated: true });
+}
+```
+
+#### 4. Preview Mode Pattern
+
+```typescript
+// app/api/draft/route.ts — Sanity preview
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET(req: NextRequest) {
+  const { searchParams } = new URL(req.url);
+  const secret = searchParams.get('secret');
+  const slug = searchParams.get('slug');
+  if (secret !== process.env.SANITY_PREVIEW_SECRET) {
+    return new Response('Invalid token', { status: 401 });
+  }
+  (await draftMode()).enable();
+  redirect(`/posts/${slug}`);
+}
+```
+
+### Production Checklist
+- [ ] Webhook-based ISR revalidation configured.
+- [ ] Preview/draft mode working with CMS studio.
+- [ ] Image optimization pipeline (next/image or Sanity image URL builder).
+- [ ] Content backup/export strategy defined.
+- [ ] CORS and API permissions locked down.
+- [ ] CDN caching for API responses configured.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+- **`nextjs-app-router-expert`**: Strategi pengambilan konten SSR/ISR dan caching.
+- **`api-design-expert`**: Pola API REST/GraphQL untuk query CMS.
+- **`seo`**: Data terstruktur, sitemap, dan metadata dari konten CMS.
+
+### Deskripsi
+Panduan ahli untuk memilih, mengintegrasikan, dan mengoptimalkan platform Headless CMS dalam aplikasi web modern. Mencakup Sanity v3, Payload CMS 3.x, Strapi 5, Contentful, dan Storyblok. Termasuk pemodelan konten, mode preview, revalidasi berbasis webhook, dan strategi migrasi.
+
+### Kondisi Pemicu
+- Memilih atau mengintegrasikan headless CMS.
+- Membangun website berbasis konten (blog, docs, marketing).
+- Mengimplementasikan mode preview/draft CMS di Next.js atau Astro.
+- Merancang model konten dan skema konten terstruktur.
+- Migrasi dari WordPress atau CMS monolitik ke headless.