tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/local-first/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: local-first
+description: Local-first software principles. Offline-capable apps, CRDTs, sync engines (ElectricSQL, Replicache, Zero), conflict resolution, and the migration path from REST-first to local-first architecture. Use when building apps that need offline support, fast UI, or collaborative editing.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Local-First Software Principles
+
+> In a local-first app, the network is an enhancement, not a requirement.
+> The app works fully offline. Sync happens in the background when possible.
+
+---
+
+## The Local-First Promise
+
+Local-first apps satisfy all of these simultaneously — traditional web apps satisfy none:
+
+```
+✅ Fast UI       — reads from local replica, never waits for network
+✅ Offline use   — full functionality without internet
+✅ Collaboration — multiple users edit the same data
+✅ Privacy       — data lives on device by default
+✅ Longevity     — app works even if vendor servers go down
+```
+
+---
+
+## Architecture Spectrum
+
+```
+REST-First (most apps today):
+  Client → HTTP → Server → DB
+  Offline: ❌  Speed: Network-bound  Collaboration: Manual
+
+Optimistic UI (halfway):
+  Client → Local cache → HTTP → Server → DB
+  Offline: Partial  Speed: Fast for reads  Collaboration: Conflict-prone
+
+Local-First:
+  Client → Local replica (SQLite/CRDT) → Sync engine ↔ Server → DB
+  Offline: ✅  Speed: Instant  Collaboration: ✅ via CRDTs
+```
+
+---
+
+## Sync Engine Selection
+
+Choose based on your database, team size, and product requirements:
+
+| Engine | Sync Model | Database | Best For |
+|---|---|---|---|
+| **ElectricSQL** | Postgres → SQLite on client | PostgreSQL only | Postgres-native teams |
+| **Replicache** | Mutation log + pull | Any backend | Custom sync logic needed |
+| **Zero (Rocicorp)** | Reactive queries | PostgreSQL | Real-time apps, Figma-speed UIs |
+| **Liveblocks** | CRDT + storage API | Managed | Collaborative SaaS (no own server) |
+| **Yjs + y-indexeddb** | CRDT + local persistence | Any | Text editing, whiteboard |
+
+---
+
+## CRDT Choices
+
+CRDTs (Conflict-free Replicated Data Types) resolve concurrent edits mathematically — no server arbitration needed:
+
+| CRDT Type | Use For | Library |
+|---|---|---|
+| **LWW Register** | Scalar values (settings, status) | Built-in or custom |
+| **G-Counter** | Incrementing counters (likes, views) | Custom |
+| **OR-Set** | Sets that support add + remove | Yjs `Y.Array` |
+| **Y.Text** | Collaborative rich text | Yjs |
+| **Y.Map** | Shared key-value state | Yjs |
+
+```ts
+import * as Y from 'yjs';
+import { IndexeddbPersistence } from 'y-indexeddb';
+
+const doc = new Y.Doc();
+
+// Persist to IndexedDB — survives page reload, works offline
+new IndexeddbPersistence('my-doc-id', doc);
+
+// Shared text — any concurrent edits from any user auto-merge
+const text = doc.getText('content');
+text.insert(0, 'Hello ');  // User A
+text.insert(6, 'World');   // User B — concurrent, no conflict
+// Result: "Hello World" — always correct, always the same
+```
+
+---
+
+## Optimistic UI Patterns
+
+Before full local-first, optimistic UI gives most of the speed benefit:
+
+```ts
+// ❌ Pessimistic — user waits for server response before any UI update
+async function likePost(postId: string) {
+  const updated = await api.likePost(postId);  // 200ms wait → UI freezes
+  setPost(updated);
+}
+
+// ✅ Optimistic — update UI immediately, sync in background
+async function likePost(postId: string) {
+  // 1. Instant UI update
+  setPost(prev => ({ ...prev, likes: prev.likes + 1, liked: true }));
+
+  try {
+    // 2. Sync to server in background
+    await api.likePost(postId);
+  } catch {
+    // 3. Rollback on failure
+    setPost(prev => ({ ...prev, likes: prev.likes - 1, liked: false }));
+    toast.error('Failed to like post');
+  }
+}
+```
+
+---
+
+## Conflict Resolution Strategies
+
+When two users edit the same data offline and then sync:
+
+| Strategy | When to Use | Downside |
+|---|---|---|
+| **Last-Write-Wins (LWW)** | Settings, preferences | Concurrent edits silently overwrite each other |
+| **First-Write-Wins** | Booking/reservation slots | Rejecters unhappy, complex UX |
+| **CRDT merge** | Text, lists, collaborative state | Complex to implement from scratch — use Yjs |
+| **3-way merge** | Code files, configs | Requires common ancestor to compute diff |
+| **User-prompted resolution** | Critical data (contracts) | Adds friction but preserves intent |
+
+---
+
+## Migration Path: REST → Local-First
+
+Don't try to go from REST to full local-first in one step:
+
+```
+Phase 1: Optimistic UI
+  → Client mutates locally, syncs async
+  → Easy win: 200ms → 0ms perceived latency
+  → Risk: conflicts on concurrent updates
+
+Phase 2: Offline Detection + Queue
+  → Queue mutations when offline
+  → Apply queue on reconnect
+  → Risk: conflict ordering
+
+Phase 3: CRDT-backed Shared State
+  → Replace mutable shared data with CRDTs
+  → Full offline + collaboration
+  → No more conflicts
+```
+
+---
+
+## Output Format
+
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Local First Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Local First
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
+```
+
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
+
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/tribunal-backend`**
+**Active reviewers: `logic` · `security`**
+
+### ❌ Forbidden AI Tropes in Local-First
+
+1. **Treating CRDTs as magic** — CRDTs solve concurrent edits to shared state, not schema migrations or access control.
+2. **Inventing CRDT libraries** — `crdt-js`, `conflict-free`, `local-sync` are not real packages. Yjs, Automerge, and Loro are the real libraries.
+3. **Skipping conflict detection in LWW** — Last-Write-Wins silently drops data. Always make the conflict resolution strategy explicit and communicate it to the user.
+4. **Local storage for everything** — `localStorage` is synchronous, has a 5MB limit, and is not available in workers. Use IndexedDB via Dexie or Origin Private File System.
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Is the conflict resolution strategy explicit and documented?
+✅ Are only real CRDT libraries used (Yjs, Automerge, Loro)?
+✅ Is offline state persisted to IndexedDB, not localStorage?
+✅ Is the sync queue replay idempotent (safe to process the same mutation twice)?
+✅ Does the UI clearly communicate offline/syncing/synced state to the user?
+```

package/.agent/skills/mcp-builder/SKILL.md

@@ -2,175 +2,223 @@
 name: mcp-builder
 description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
 allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# MCP Builder
+# MCP Server Development
 
-> Principles for building MCP servers.
+> An MCP server exposes capabilities to AI assistants.
+> Design tools the way you design a good API: clear contracts, predictable behavior, honest errors.
 
 ---
 
-## 1. MCP Overview
+## What MCP Servers Do
 
-### What is MCP?
+An MCP (Model Context Protocol) server gives an AI assistant structured access to:
 
-Model Context Protocol - standard for connecting AI systems with external tools and data sources.
+- **Tools** — actions the AI can invoke (run a query, send a message, fetch data)
+- **Resources** — data the AI can read (files, database records, API responses)
+- **Prompts** — reusable prompt templates with parameters
 
-### Core Concepts
+---
 
-| Concept | Purpose |
-|---------|---------|
-| **Tools** | Functions AI can call |
-| **Resources** | Data AI can read |
-| **Prompts** | Pre-defined prompt templates |
+## Tool Design Principles
 
----
+### 1. One tool, one responsibility
 
-## 2. Server Architecture
+A tool that does two things is a tool that confuses the model. Split tools when they serve different goals.
 
-### Project Structure
+```ts
+// ❌ Ambiguous — does it list AND filter?
+{ name: "get_users", description: "Get users, optionally filtered by role" }
 
-```
-my-mcp-server/
-├── src/
-│   └── index.ts      # Main entry
-├── package.json
-└── tsconfig.json
+// ✅ Separate concerns
+{ name: "list_users", description: "List all users with pagination" }
+{ name: "find_users_by_role", description: "Find users matching a specific role" }
 ```
 
-### Transport Types
+### 2. Descriptions are the interface
 
-| Type | Use |
-|------|-----|
-| **Stdio** | Local, CLI-based |
-| **SSE** | Web-based, streaming |
-| **WebSocket** | Real-time, bidirectional |
+The AI reads descriptions to decide which tool to call. Write them for the AI, not for humans.
 
----
+- State exactly what the tool does in plain terms
+- State what the tool returns
+- State when NOT to use it if there's common confusion
+
+```ts
+{
+  name: "search_products",
+  description: "Search products by keyword. Returns an array of matching product records " +
+    "with id, name, price, and stock. Use this for keyword search, not for fetching a " +
+    "specific product by ID — use get_product_by_id for that."
+}
+```
 
-## 3. Tool Design Principles
+### 3. Input schemas are contracts
+
+Every tool input must have a JSON Schema definition with:
+- Required vs. optional fields clearly marked
+- Descriptions on each field
+- Sensible defaults on optional fields
+
+```ts
+inputSchema: {
+  type: "object",
+  required: ["query"],
+  properties: {
+    query: {
+      type: "string",
+      description: "Search keyword. Minimum 2 characters."
+    },
+    limit: {
+      type: "number",
+      description: "Maximum results to return. Default: 10. Max: 100.",
+      default: 10
+    }
+  }
+}
+```
 
-### Good Tool Design
+### 4. Errors must be informative
 
-| Principle | Description |
-|-----------|-------------|
-| Clear name | Action-oriented (get_weather, create_user) |
-| Single purpose | One thing well |
-| Validated input | Schema with types and descriptions |
-| Structured output | Predictable response format |
+When a tool fails, the AI needs to understand what went wrong and whether to retry.
 
-### Input Schema Design
+```ts
+// ❌ Useless error
+throw new Error("Failed");
 
-| Field | Required? |
-|-------|-----------|
-| Type | Yes - object |
-| Properties | Define each param |
-| Required | List mandatory params |
-| Description | Human-readable |
+// ✅ Actionable error
+return {
+  isError: true,
+  content: [{
+    type: "text",
+    text: "Product search failed: the search index is temporarily unavailable. " +
+          "Try again in a few seconds or use list_products for unfiltered results."
+  }]
+};
+```
 
 ---
 
-## 4. Resource Patterns
+## Resource Design
 
-### Resource Types
+Resources give the AI read-only access to data. Use them for content the AI needs to understand context, not for actions.
 
-| Type | Use |
-|------|-----|
-| Static | Fixed data (config, docs) |
-| Dynamic | Generated on request |
-| Template | URI with parameters |
+```ts
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
 
-### URI Patterns
+  if (uri.startsWith("product://")) {
+    const id = uri.replace("product://", "");
+    const product = await db.products.findById(id);
 
-| Pattern | Example |
-|---------|---------|
-| Fixed | `docs://readme` |
-| Parameterized | `users://{userId}` |
-| Collection | `files://project/*` |
+    return {
+      contents: [{
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(product, null, 2)
+      }]
+    };
+  }
+});
+```
 
 ---
 
-## 5. Error Handling
-
-### Error Types
+## Security Rules
 
-| Situation | Response |
-|-----------|----------|
-| Invalid params | Validation error message |
-| Not found | Clear "not found" |
-| Server error | Generic error, log details |
+MCP servers execute with user-level permissions and may have access to sensitive systems:
 
-### Best Practices
-
-- Return structured errors
-- Don't expose internal details
-- Log for debugging
-- Provide actionable messages
+- **Never trust tool arguments without validation** — the AI can be prompted to send malicious input
+- **Parameterize all database queries** — treat tool input as untrusted user input
+- **Scope API keys narrowly** — the MCP server should have the minimum permissions needed
+- **Log tool invocations** — especially for tools that write data or delete records
+- **Rate limit tool calls** — prevent runaway AI loops from hammering backends
 
 ---
 
-## 6. Multimodal Handling
-
-### Supported Types
+## Configuration Template
+
+```json
+{
+  "mcpServers": {
+    "your-server": {
+      "command": "npx",
+      "args": ["-y", "your-mcp-package"],
+      "env": {
+        "API_KEY": "${YOUR_API_KEY}"
+      }
+    }
+  }
+}
+```
 
-| Type | Encoding |
-|------|----------|
-| Text | Plain text |
-| Images | Base64 + MIME type |
-| Files | Base64 + MIME type |
+Place in `~/.cursor/mcp.json` (Cursor) or `~/.gemini/antigravity/mcp_config.json` (Antigravity).
 
 ---
 
-## 7. Security Principles
+## Output Format
 
-### Input Validation
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Mcp Builder Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Mcp Builder
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
+```
 
-- Validate all tool inputs
-- Sanitize user-provided data
-- Limit resource access
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
-### API Keys
 
-- Use environment variables
-- Don't log secrets
-- Validate permissions
 
 ---
 
-## 8. Configuration
+## 🤖 LLM-Specific Traps
 
-### Claude Desktop Config
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-| Field | Purpose |
-|-------|---------|
-| command | Executable to run |
-| args | Command arguments |
-| env | Environment variables |
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
 
 ---
 
-## 9. Testing
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-### Test Categories
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
 
-| Type | Focus |
-|------|-------|
-| Unit | Tool logic |
-| Integration | Full server |
-| Contract | Schema validation |
+### ❌ Forbidden AI Tropes
 
----
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
 
-## 10. Best Practices Checklist
+### ✅ Pre-Flight Self-Audit
 
-- [ ] Clear, action-oriented tool names
-- [ ] Complete input schemas with descriptions
-- [ ] Structured JSON output
-- [ ] Error handling for all cases
-- [ ] Input validation
-- [ ] Environment-based configuration
-- [ ] Logging for debugging
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
 
----
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.