everything-gemini 0.0.0-stage → 1.0.0

package/skills/api-craftsman/examples/openapi-spec.yaml

@@ -0,0 +1,37 @@
+openapi: 3.1.0
+info:
+  title: Order Management API
+  version: 1.0.0
+  description: High-performance API contract for orders.
+paths:
+  /orders:
+    post:
+      summary: Create new order
+      operationId: createOrder
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [items, customerId]
+              properties:
+                customerId:
+                  type: string
+                  format: uuid
+                items:
+                  type: array
+                  items:
+                    type: object
+                    required: [productId, quantity]
+                    properties:
+                      productId:
+                        type: string
+                      quantity:
+                        type: integer
+                        minimum: 1
+      responses:
+        '201':
+          description: Order created successfully
+        '400':
+          description: Validation failure

package/skills/architecture-designer/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: architecture-designer
+description: >-
+  Creates comprehensive system design architectures, Mermaid diagrams, API contracts, and Architecture Decision Records (ADRs). Use when planning complex software systems or designing net-new components.
+---
+
+# Architecture Designer
+
+This skill structures software design workflows, creating standardized Architecture Decision Records (ADRs) and Mermaid diagrams.
+
+## Design Workflow
+
+### 1. Requirements & Constraint Gathering
+- Clarify functional and non-functional requirements (latency, throughput, availability, consistency).
+- Identify existing tech stack dependencies and constraints.
+
+### 2. High-Level Diagramming with Mermaid
+Always visualize architectures using GitHub-flavored Mermaid blocks:
+- **System Context (C4 Level 1)**
+- **Container / Service Diagram (C4 Level 2)**
+- **Sequence Diagram (Data Flow)**
+
+*Rule*: Quote node labels containing special characters: `id["Service Name (Tech Stack)"]`.
+
+### 3. Architecture Decision Record (ADR)
+Structure decisions in this format:
+- **Title**: `ADR-00X: Short descriptive title`
+- **Status**: Proposed / Accepted / Superseded
+- **Context**: Problem statement and forces at play.
+- **Decision**: The architectural choice and implementation strategy.
+- **Consequences**: Positive outcomes and trade-offs.
+
+For full examples, see [examples/c4-architecture.md](./examples/c4-architecture.md).

package/skills/architecture-designer/examples/c4-architecture.md

@@ -0,0 +1,33 @@
+# C4 Model & Mermaid Diagram Examples
+
+## Example: Microservices Architecture
+```mermaid
+graph TD
+    Client["Web / Mobile Client"] -->|HTTPS / REST| Gateway["API Gateway (Kong / Envoy)"]
+    Gateway -->|gRPC| AuthSvc["Authentication Service (Go)"]
+    Gateway -->|gRPC| OrderSvc["Order Processing Service (Node.js)"]
+    Gateway -->|gRPC| InventorySvc["Inventory Service (Python)"]
+
+    OrderSvc --> DB[(PostgreSQL Primary)]
+    OrderSvc --> Queue["Kafka Event Bus"]
+    Queue --> NotificationSvc["Notification Worker (Go)"]
+```
+
+## Example: Event Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Frontend
+    participant API as API Gateway
+    participant Svc as Payment Service
+    participant Stripe as Stripe API
+
+    User->>Frontend: Click "Pay Now"
+    Frontend->>API: POST /api/checkout
+    API->>Svc: InitiateCheckout(orderId)
+    Svc->>Stripe: CreatePaymentIntent()
+    Stripe-->>Svc: clientSecret
+    Svc-->>Frontend: 200 OK (clientSecret)
+    Frontend->>User: Confirm Payment Modal
+```

package/skills/browser-qa-tester/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: browser-qa-tester
+description: >-
+  Orchestrates automated UI, frontend, and end-to-end testing using Antigravity's native browser subagent with automatic WebP recording. Use when verifying web applications, visual bugs, or UI flows.
+---
+
+# Browser QA Tester
+
+This skill automates visual testing and end-to-end verification of web applications using Antigravity's native `browser_subagent`.
+
+## Why Browser Subagent?
+- **Autonomous Interaction**: Navigates, clicks, fills inputs, and scrolls.
+- **Automatic Recording**: Automatically captures WebP video recordings saved directly into the conversation artifacts directory.
+- **Console & Network Inspection**: Intercepts unhandled errors, failed network requests, and visual layout glitches.
+
+## Verification Procedure
+
+### 1. Ensure Local Server is Running
+Before launching the browser subagent, ensure the web app is running locally:
+```bash
+# Check if port is open
+lsof -i :3000 || lsof -i :5173
+```
+If not running, launch with `run_command` and `IsDaemon: true`:
+```bash
+npm run dev
+```
+
+### 2. Invoke `browser_subagent`
+Formulate a precise task description with explicit stop conditions:
+- Specify target URL (e.g., `http://localhost:3000`).
+- Specify unique element IDs or text labels to click/type.
+- Define what constitutes success (e.g., "Verify dashboard renders after login").
+
+### 3. Review Recording Artifacts
+After the subagent finishes:
+- Embed the generated WebP recording into your summary artifact:
+  ```markdown
+  ![Browser Test Recording](file:///absolute/path/to/artifacts/browser_test_demo.webp)
+  ```
+- Summarize any console warnings or errors detected during the test.
+
+For specialized testing recipes (Responsive testing, Form verification), see [references/browser-recipes.md](./references/browser-recipes.md).

package/skills/browser-qa-tester/references/browser-recipes.md

@@ -0,0 +1,21 @@
+# Browser Testing Recipes
+
+## Recipe 1: Form Fill and Submit Flow
+```text
+Task: Navigate to http://localhost:3000/contact.
+Locate input with id '#name' and type 'Test User'.
+Locate input with id '#email' and type 'test@example.com'.
+Locate button with text 'Send Message' and click it.
+Verify that the success message 'Thank you for contacting us' appears on screen.
+Stop condition: Success message is visible or error banner appears.
+```
+
+## Recipe 2: Responsive Layout Check
+```text
+Task: Open http://localhost:3000.
+Resize browser window to 375x812 (mobile iPhone viewport).
+Verify that the mobile hamburger navigation toggle is visible.
+Click the hamburger icon and verify the drawer menu slides in.
+Resize back to 1440x900 (desktop viewport) and verify desktop navigation links return.
+Stop condition: Both mobile and desktop nav states verified.
+```

package/skills/context-caching/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: context-caching
+description: >-
+  Use this skill when managing large-context Gemini operations (1M-2M tokens), architecting prefix-cached repository indexes, optimizing prompt structures for cost and latency, or structuring session memory for long-running agent workflows.
+---
+
+# Gemini Context Caching & Large-Context Optimization
+
+## Overview
+Gemini's 1M-to-2M token context window combined with explicit and implicit Context Caching allows agents to ingest entire codebases, documentation sets, and transaction logs. This skill outlines architectural strategies to maximize caching efficiency, cut API token costs by up to 75%, and minimize time-to-first-token (TTFT).
+
+## Context Architecture: Prefix Optimization
+
+Gemini caching relies on **deterministic prefix matching**. To ensure cache hits across agent invocations:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ 1. STATIC PREFIX (Cached - High Hit Rate)                    │
+│    - System Instructions & Repository Rules (GEMINI.md)     │
+│    - Architecture Specs & Database Schemas                  │
+│    - Base Codebase Index / AST Dump                         │
+├─────────────────────────────────────────────────────────────┤
+│ 2. DYNAMIC SUFFIX (Uncached - Fast Processing)              │
+│    - Current User Prompt / Incremental Task Diff            │
+│    - Recent Terminal Command Output                         │
+│    - Real-Time Conversation Turn                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Golden Rules for Caching
+1. **Never mutate the prefix**: Avoid injecting dynamic timestamps, random IDs, or changing session metadata at the beginning of the context.
+2. **Cluster Static Assets**: Place unchanging documentation, API contracts, and core schemas at the very top of context assemblies.
+3. **Chunking Thresholds**: Context caching provides optimal return on investment when static context exceeds 32k tokens.
+
+## Progressive Ingestion Strategies
+
+1. **Skeleton First**: Ingest file tree maps and interface definitions before pulling full function implementations.
+2. **Selective Hydration**: Ingest full source files only for components identified during initial skeleton mapping.
+3. **Session Compaction**: When conversation histories grow long, trigger the `Stop` or `PostInvocation` summarizer to compress intermediate thoughts into high-density Knowledge Items (KI).
+
+## Cost & Latency Economics
+- **Cached Input Cost**: ~75% cheaper than non-cached input tokens.
+- **Cache Hit Latency**: Reduces initial TTFT from seconds to milliseconds on large contexts.
+
+## Verification Checklist
+- [ ] Static instructions positioned consistently at the head of context
+- [ ] No variable timestamps or nonces in the static prefix block
+- [ ] Cache hit rates monitored during multi-turn batch workflows

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: continuous-learning
+description: >-
+  Extracts architectural lessons, developer corrections, and project conventions from the current session and records them into permanent rules or Knowledge Items. Activate when the user runs /learn or after resolving a complex issue.
+---
+
+# Continuous Learning & Instinct Recording
+
+This skill enables Antigravity to retain lessons and developer feedback so mistakes are never repeated.
+
+## Learning Workflow
+
+### 1. Identify the Core Insight
+Determine what was learned:
+- **Correction**: Did the user correct a style, framework version, or tool choice?
+- **Bug Fix**: Was an obscure bug or configuration issue solved after debugging?
+- **Workflow**: Was an optimal command sequence identified for building/testing?
+
+### 2. Format the Instinct
+Formulate a concise, imperative rule:
+- *Bad*: "We had an issue with Docker not starting on port 8080."
+- *Good*: "Always map Docker container port 8080 to host 8081 to avoid conflicting with local proxy."
+
+### 3. Persist to `.agents/rules/instincts.md`
+Append the new instinct under the appropriate section in `.agents/rules/instincts.md`:
+```markdown
+- **Topic Name**: Concrete rule statement.
+```
+
+### 4. For Major Architectural Changes: Create Knowledge Item
+If the insight affects the broader repository architecture, write a dedicated Knowledge Item in `<appDataDir>/knowledge` with `metadata.json` and artifact details.

package/skills/database-architect/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: database-architect
+description: >-
+  Designs relational and document database schemas, crafts zero-downtime database migrations, optimizes complex queries, and configures ORMs (Prisma, Drizzle, SQLAlchemy).
+---
+
+# Database Architect
+
+This skill guides data modeling, schema evolution, index tuning, and zero-downtime migration workflows.
+
+## Core Directives
+
+### 1. Schema Design Standards
+- **Primary Keys**: Use UUIDv7 or ULIDs for distributed systems, or identity integers for internal lookups.
+- **Foreign Keys**: Always define explicit foreign key constraints with appropriate `ON DELETE` behavior (`CASCADE`, `RESTRICT`, or `SET NULL`).
+- **Timestamps**: Every table must have `created_at TIMESTAMPTZ DEFAULT now()` and `updated_at TIMESTAMPTZ DEFAULT now()`.
+
+### 2. Zero-Downtime Migrations (Expand/Contract Pattern)
+- **Never rename or delete a column in a single migration**:
+  1. *Phase 1 (Expand)*: Add the new column as nullable or with a default. Deploy code that writes to both columns.
+  2. *Phase 2 (Backfill)*: Backfill existing records asynchronously.
+  3. *Phase 3 (Switch)*: Deploy code that reads from the new column only.
+  4. *Phase 4 (Contract)*: Remove the old column.
+- **Safe Index Creation**: In PostgreSQL, always use `CREATE INDEX CONCURRENTLY` to avoid blocking read/write queries.
+
+For the zero-downtime migration checklist, see [references/migration-checklist.md](./references/migration-checklist.md).

package/skills/database-architect/references/migration-checklist.md

@@ -0,0 +1,9 @@
+# Zero-Downtime Migration Checklist
+
+Before applying any migration to staging or production:
+
+- [ ] **No Exclusive Table Locks**: Are you adding a column with a non-constant default on older Postgres versions?
+- [ ] **Concurrent Indexes**: Are all new indexes declared with `CONCURRENTLY` (or equivalent in your database engine)?
+- [ ] **Reversible / Down Migrations**: Is there a verified `down` migration script in case a rollback is required?
+- [ ] **Idempotent Execution**: Can the migration be safely re-run if interrupted?
+- [ ] **Query Performance Impact**: Has `EXPLAIN (ANALYZE, BUFFERS)` been verified for queries hitting the modified tables?

package/skills/devops-pipeline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: devops-pipeline
+description: >-
+  Architects and configures Docker containers, multi-stage Dockerfiles, GitHub Actions CI/CD workflows, and infrastructure automation. Use when building or tuning deployment pipelines.
+---
+
+# DevOps Pipeline Engineering
+
+This skill structures Docker containerization, caching, security scanning, and CI/CD automation.
+
+## Core Directives
+
+### 1. Minimal Multi-Stage Dockerfiles
+- Use multi-stage builds (`AS builder` and `AS runner`) to keep final image sizes minimal (< 100MB).
+- Run applications as a non-root user (`USER node` or `USER appuser`) for defense-in-depth.
+- Order commands to maximize Docker layer cache hits (copy `package.json` / `requirements.txt` before copying source code).
+
+### 2. GitHub Actions CI/CD Best Practices
+- Cache dependencies (`actions/cache` or `actions/setup-node` with `cache: 'npm'`).
+- Run linting, typechecking, and unit tests concurrently using GitHub Actions job matrix.
+- Enforce status checks before permitting branch merges into `main`.
+
+For complete production CI/CD workflow templates, see [templates/github-ci.yml](./templates/github-ci.yml).

package/skills/devops-pipeline/templates/github-ci.yml

@@ -0,0 +1,31 @@
+name: CI Suite
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck --if-present
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Run Test Suite
+        run: npm test

package/skills/fullstack-nextjs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: fullstack-nextjs
+description: >-
+  Specialized engineering workflow for Next.js App Router, React Server Components (RSC), Server Actions, and API routes. Use when building or debugging modern Next.js applications.
+---
+
+# Fullstack Next.js Engineering
+
+This skill provides patterns for Next.js (App Router), React Server Components (RSC), and Server Actions.
+
+## Core Directives
+
+### 1. Server vs. Client Components
+- **Default to Server Components**: Fetch data directly on the server without `useEffect` or client-side fetch.
+- **`'use client'` Boundary**: Only mark components with `'use client'` when they require browser event listeners (`onClick`, `onChange`), React state (`useState`, `useReducer`), or browser APIs.
+- **Push Client Boundaries Down**: Keep client components at the leaves of the component tree to maximize server-side rendering performance.
+
+### 2. Server Actions & Mutations
+- Use `'use server'` functions for mutations.
+- Always validate input arguments using Zod schemas inside Server Actions before performing database queries.
+- Revalidate cache paths using `revalidatePath()` or `revalidateTag()` after data mutations.
+
+### 3. Hydration Bug Prevention
+- Avoid accessing `window`, `localStorage`, or `navigator` during initial render.
+- Ensure identical HTML output between SSR and hydration (e.g. avoid rendering random IDs or localized date strings on initial render without a client wrapper).
+
+For architectural layouts and route handler patterns, see [references/app-router-patterns.md](./references/app-router-patterns.md).

package/skills/fullstack-nextjs/references/app-router-patterns.md

@@ -0,0 +1,46 @@
+# Next.js App Router Architecture & Patterns
+
+## 1. Safe Server Action Pattern with Zod
+```typescript
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const CreateTodoSchema = z.object({
+  title: z.string().min(1).max(100),
+});
+
+export async function createTodo(formData: FormData) {
+  const parsed = CreateTodoSchema.safeParse({
+    title: formData.get('title'),
+  });
+
+  if (!parsed.success) {
+    return { error: 'Invalid input', issues: parsed.error.issues };
+  }
+
+  // Database insert
+  // await db.todos.create({ data: { title: parsed.data.title } });
+
+  revalidatePath('/todos');
+  return { success: true };
+}
+```
+
+## 2. Suspense & Streaming Data Fetching
+```tsx
+import { Suspense } from 'react';
+import { UserProfileSkeleton, UserProfile } from './UserProfile';
+
+export default function DashboardPage() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-bold">Dashboard</h1>
+      <Suspense fallback={<UserProfileSkeleton />}>
+        <UserProfile />
+      </Suspense>
+    </main>
+  );
+}
+```

package/skills/gemini-multimodal/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gemini-multimodal
+description: >-
+  Use this skill when analyzing visual mockups, inspecting UI screenshots, converting wireframes to frontend code, extracting architecture from diagrams, or performing visual QA regression checks using Gemini's native multimodal capabilities.
+---
+
+# Gemini Multimodal Engineering
+
+## Overview
+Gemini 1.5/3.8 models feature native multimodal grounding across images, diagrams, video frames, and audio tokens. This skill guides the agent on how to effectively extract structured specifications from visual assets and translate them into production code.
+
+## Procedural Workflow
+
+### 1. Visual Intake & Pre-Processing
+- **Aspect Ratio & Resolution**: Gemini processes visual inputs with native resolution preservation.
+- **Reference Assets**: When inspecting diagrams or UI mockups, identify layout hierarchy:
+  - Header / Navigation bars
+  - Main grid or flex container arrangements
+  - Typography weights, line heights, and color hex values
+  - Interactive elements (buttons, inputs, carousels, modals)
+
+### 2. Mockup-to-Code Translation Pattern
+When converting a visual mockup into web components:
+1. **Layout First**: Implement semantic HTML scaffolding matching visual hierarchy.
+2. **Design Tokens**: Extract exact color palettes, border radiuses, and shadow elevations into CSS variables.
+3. **Responsive Breakpoints**: Infer desktop, tablet, and mobile reflow logic from the visual layout.
+4. **Interactive States**: Emulate hover, focus-visible, and active states visible in the UI.
+
+### 3. Diagram & Flowchart Extraction
+When given an architectural whiteboard photo or flowchart:
+1. Transcribe nodes and connections into clean **Mermaid.js** diagrams.
+2. Extract data models, sequence flows, and component boundaries into typed interfaces.
+
+### 4. Visual QA & Regression Diffing
+1. Capture screenshots of the rendered application using `browser_subagent`.
+2. Inspect layout anomalies: overlapping text, clipped containers, misalignment across viewports.
+3. Apply surgical CSS adjustments without affecting sibling components.
+
+## Verification Checklist
+- [ ] Visual hierarchy precisely reflects the reference asset
+- [ ] No placeholder assets or mock text left in production components
+- [ ] CSS uses fluid units (`rem`, `ch`, `%`) and CSS grid/flexbox
+- [ ] Visual artifacts verified via browser inspection or recording

package/skills/git-craftsman/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: git-craftsman
+description: >-
+  Guides atomic commits, conventional commit formatting, clean branch strategies, and pull request walkthrough generation. Use when staging, committing, or preparing a PR.
+---
+
+# Git Craftsman
+
+This skill enforces clean version control habits, atomic commits, and structured pull request walkthroughs.
+
+## Atomic Commit Workflow
+
+### 1. Inspect Staged & Unstaged Diff
+Always review changes before staging:
+```bash
+git status -s
+git diff
+```
+
+### 2. Craft Conventional Commit Messages
+Format commit messages strictly following the Conventional Commits specification:
+```text
+<type>(<scope>): <short imperative summary>
+
+[optional detailed body explaining WHY, not just WHAT]
+
+[optional breaking changes or issue references]
+```
+
+**Permitted Types**:
+- `feat`: New feature or user-facing functionality.
+- `fix`: Bug fix.
+- `refactor`: Code change that neither fixes a bug nor adds a feature.
+- `perf`: Performance improvement.
+- `test`: Adding or correcting tests.
+- `docs`: Documentation only changes.
+- `chore`: Build system, configuration, or dependency updates.
+
+### 3. Pull Request Walkthrough Format
+When authoring a pull request summary, include:
+- **High-Level Objective**: What problem this PR solves.
+- **Key Changes**: Bulleted list of modified modules with clickable file links.
+- **Verification Performed**: Exact commands run (`npm test`, `cargo test`) and results.

package/skills/performance-profiler/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: performance-profiler
+description: >-
+  Profiles application latency, CPU usage, memory leaks, and database bottlenecks. Use when diagnosing slow response times, high resource consumption, or memory leaks.
+---
+
+# Performance Profiler
+
+This skill guides the agent through systematic latency and resource bottleneck profiling.
+
+## Profiling Workflow
+
+### 1. Identify the Bottleneck Metric
+Determine the performance symptom:
+- **High CPU**: Algorithmic complexity ($O(n^2)$), tight loops, excessive JSON serialization.
+- **High Memory / Leak**: Retained closures, unclosed database streams, unbounded in-memory caches.
+- **High Latency (I/O)**: N+1 database queries, unindexed SQL lookups, synchronous blocking disk I/O.
+
+### 2. Node.js & V8 Profiling
+Run Node with the V8 sampling profiler:
+```bash
+node --prof app.js
+node --prof-process isolate-*.log > processed.txt
+```
+
+### 3. Database Query Analysis
+- **PostgreSQL**: Run `EXPLAIN (ANALYZE, BUFFERS) <query>` to inspect sequential scans, join types, and execution time.
+- **Indexes**: Verify that high-cardinality `WHERE` and `JOIN` columns have appropriate B-Tree or Hash indexes.
+
+### 4. Memory Heap Dumps
+Capture heap snapshots or track memory diffs between iterations to isolate leaks:
+```javascript
+const mem = process.memoryUsage();
+console.log(`Heap Used: ${Math.round(mem.heapUsed / 1024 / 1024)} MB`);
+```

package/skills/performance-profiler/scripts/profile-node.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Quick Node.js CPU profiling helper
+
+TARGET="${1:-index.js}"
+DURATION="${2:-10}"
+
+echo "Starting CPU profiling for $TARGET ($DURATION seconds)..."
+NODE_V8_COVERAGE=coverage node --cpu-prof "$TARGET" &
+PID=$!
+
+sleep "$DURATION"
+kill -SIGINT "$PID" 2>/dev/null || true
+echo "CPU profile generated. Look for CPU.*.cpuprofile in the directory."

package/skills/repo-onboarding/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: repo-onboarding
+description: >-
+  Rapidly inspects an unfamiliar codebase, maps directory structures, identifies key patterns, and generates a structured Knowledge Item (KI) for permanent repository memory.
+---
+
+# Repository Onboarding & Knowledge Item (KI) Indexing
+
+When an agent enters a new codebase, this skill provides a structured exploration sequence to index architecture, conventions, and operational runbooks without wasting excessive context.
+
+## Onboarding Procedure
+
+### 1. Root & Ecosystem Inspection
+1. Read project manifest: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`.
+2. Check `.gitignore` to identify ignored artifacts, environment configs, and build outputs.
+3. Check `README.md` and docs for local setup and testing scripts.
+
+### 2. Architectural Survey
+1. Run `list_dir` on root and top-level directories to understand organizational patterns (e.g. Clean Architecture, Monorepo, MVC).
+2. Identify entry points (e.g., `src/index.ts`, `app/main.py`, `cmd/server/main.go`).
+3. Locate core data models and database schemas (e.g., Prisma schemas, SQLAlchemy models, migrations).
+
+### 3. Build & Test Verification
+Run the project's build and test commands to verify environment health:
+```bash
+# E.g.
+npm run build && npm test
+```
+
+### 4. Create Repository Knowledge Item (KI)
+Persist findings into the localized Knowledge Items store so subsequent sessions have instant architectural recall:
+- Create `metadata.json` outlining core patterns, key paths, and test instructions.
+- Create an architecture summary artifact in `<appDataDir>/knowledge`.
+
+For the schema and structure of Knowledge Items, see [references/knowledge-item-schema.md](./references/knowledge-item-schema.md).

package/skills/repo-onboarding/references/knowledge-item-schema.md

@@ -0,0 +1,30 @@
+# Knowledge Items (KI) Schema & Reference
+
+Knowledge Items are Antigravity's persistent, curated memory units stored in `<appDataDir>/knowledge`.
+
+## Structure
+```text
+<appDataDir>/knowledge/<ki-id>/
+├── metadata.json
+└── artifacts/
+    ├── architecture.md
+    └── common-patterns.md
+```
+
+## `metadata.json` Format
+```json
+{
+  "title": "Repository Architecture & Patterns",
+  "summary": "Fullstack Next.js app using PostgreSQL, Prisma, and Tailwind CSS. Tests run via Vitest.",
+  "createdAt": "2026-10-15T10:00:00Z",
+  "updatedAt": "2026-10-15T10:00:00Z",
+  "references": [
+    "package.json",
+    "prisma/schema.prisma",
+    "vitest.config.ts"
+  ]
+}
+```
+
+## When to Consult Knowledge Items
+Always check Knowledge Items before performing deep-dive architectural investigations to avoid duplicating work and violating established team conventions.

package/skills/root-cause-debugger/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: root-cause-debugger
+description: >-
+  Systematically diagnoses complex regressions, silent data corruptions, race conditions, and elusive bugs using binary search (git bisect), log analysis, and reproduction harnesses.
+---
+
+# Root Cause Debugger
+
+This skill provides an evidence-based debugging procedure to eliminate guessing and find root causes rapidly.
+
+## 5-Step Debugging Protocol
+
+### 1. Build a Minimal Reproducer (MRE)
+- Never start guessing fixes without an automated test or minimal script that reliably triggers the failure.
+- Strip away unrelated modules until only the failing component remains.
+
+### 2. Formulate & Test Hypotheses
+- List the top 2-3 plausible hypotheses for why the failure occurs.
+- Add targeted debug statements or breakpoints to confirm or falsify each hypothesis sequentially.
+
+### 3. Binary Search History with `git bisect`
+If the bug is a regression that didn't exist in an earlier commit:
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <known-good-commit>
+git bisect run ./test-runner.sh
+```
+This isolates the exact offending commit in $O(\log n)$ steps.
+
+### 4. Implement Minimal Surgical Fix
+- Resolve the root cause directly at its source. Avoid superficial patches that merely silence error messages.
+
+### 5. Add Regression Shield Test
+- Commit an automated test that explicitly verifies the regression never recurs.