tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/api-patterns/SKILL.md

@@ -2,80 +2,256 @@
 name: api-patterns
 description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
 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
 ---
 
-# API Patterns
+# API Design Patterns
 
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
+> Build APIs that serve their consumers — not APIs that match the tutorial you read last.
+> Every decision here has a trade-off. Know the trade-off before you pick a side.
 
-## 🎯 Selective Reading Rule
+## How to Use This Skill
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+Only read the files you actually need for this task. The map below tells you where to look.
 
 ---
 
-## 📑 Content Map
-
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
-| `response.md` | Envelope pattern, error format, pagination | Response structure |
-| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
-| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
-| `versioning.md` | URI/Header/Query versioning | API evolution planning |
-| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| `rate-limiting.md` | Token bucket, sliding window | API protection |
-| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
-| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+## File Index
+
+| File | What It Covers | Load When |
+|---|---|---|
+| `api-style.md` | Choosing between REST, GraphQL, and tRPC | Client type is unclear or debated |
+| `rest.md` | Endpoint naming, HTTP verbs, status code semantics | Building a REST surface |
+| `response.md` | Unified response envelope, error shapes, cursor pagination | Defining response contracts |
+| `graphql.md` | Schema-first design, N+1 awareness, when NOT to use GraphQL | GraphQL is on the table |
+| `trpc.md` | Type-safe RPC for TypeScript monorepos | Full-stack TypeScript project |
+| `versioning.md` | URI, header, and content-type versioning strategies | API needs to evolve without breaking clients |
+| `auth.md` | JWT, OAuth 2.0, Passkeys, API keys — picking the right one | Authentication is being designed |
+| `rate-limiting.md` | Token bucket vs sliding window, burst handling | Protecting public or high-traffic endpoints |
+| `documentation.md` | OpenAPI spec quality, example-driven docs | API is being documented |
+| `security-testing.md` | OWASP API Top 10, authorization boundary testing | Security review |
+
+---
+
+## Related Expertise
+
+| If You Also Need | Load This |
+|---|---|
+| Server implementation | `@[skills/nodejs-best-practices]` |
+| Data layer | `@[skills/database-design]` |
+| Vulnerability review | `@[skills/vulnerability-scanner]` |
+
+---
+
+## Pre-Design Checklist
+
+Answer these before writing a single route:
+
+- [ ] Who calls this API? (browser, mobile, service-to-service, third party)
+- [ ] What data shape does the consumer need — or does it vary per caller?
+- [ ] REST, GraphQL, or tRPC — and does the team agree?
+- [ ] What does a failed response look like across the whole surface?
+- [ ] How will this API change in 6 months without breaking callers?
+- [ ] Is there a rate-limit story?
+- [ ] Will there be public docs, and who maintains them?
+
+---
+
+## Common Mistakes
+
+**Patterns that cause pain later:**
+
+- Treating REST as default without considering the consumer's actual fetch patterns
+- Verbs in endpoint paths (`/getUser`, `/deleteItem`) — REST resources are nouns
+- Inconsistent error shapes across routes — consumers have to guess
+- Leaking stack traces or internal identifiers in error responses
+- No versioning plan until the first breaking change hits production
+
+**What good looks like:**
+
+- API style chosen for the actual use case, not habit
+- Consumer requirements asked and confirmed before design starts
+- Every response — success and failure — follows the same shape
+- HTTP status codes mean what they're supposed to mean
+
+---
+
+## AI-Era API Patterns (2025+)
+
+### SSE vs WebSocket for AI Streaming
+
+```
+SSE (Server-Sent Events) — use for AI text streaming:
+  ✅ One-directional: server → client (exactly what LLM streaming is)
+  ✅ HTTP/2-native, works through all proxies
+  ✅ No library needed — native EventSource API in browsers
+  ❌ If the client also needs to send data mid-stream → WebSocket instead
+
+WebSocket — use for bidirectional real-time:
+  ✅ Full-duplex (both directions)
+  ✅ Real-time collaboration, chat, game state
+  ❌ More complex lifecycle management
+```
+
+```ts
+// ✅ SSE endpoint for AI streaming response
+app.get('/api/generate', async (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+
+  const stream = await openai.chat.completions.create({ ..., stream: true });
+
+  for await (const chunk of stream) {
+    const text = chunk.choices[0]?.delta?.content ?? '';
+    if (text) res.write(`data: ${JSON.stringify({ text })}\n\n`);
+  }
+
+  res.write('data: [DONE]\n\n');
+  res.end();
+});
+```
+
+### Model Context Protocol (MCP)
+
+MCP is the emerging standard (2025) for AI models to interface with external tools and data sources:
+
+```ts
+// MCP server — expose your API's capabilities as MCP tools
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const server = new McpServer({ name: 'my-api', version: '1.0.0' });
+
+// Register a tool that AI agents can call
+server.tool(
+  'search_products',
+  'Search the product catalog by keyword and category',
+  {
+    query: z.string().describe('Search terms'),
+    category: z.string().optional().describe('Filter by category'),
+  },
+  async ({ query, category }) => {
+    const results = await db.searchProducts(query, category);
+    return { content: [{ type: 'text', text: JSON.stringify(results) }] };
+  }
+);
+```
+
+### Idempotency Keys for LLM Request Deduplication
+
+LLM requests can be expensive. If a client retries due to a timeout, you may charge twice:
+
+```ts
+// ✅ Idempotency key — same key = return cached response
+app.post('/api/generate', async (req, res) => {
+  const idempotencyKey = req.headers['idempotency-key'];
+
+  if (idempotencyKey) {
+    const cached = await cache.get(`llm:${idempotencyKey}`);
+    if (cached) return res.json(cached);
+  }
+
+  const result = await callLLM(req.body);
+
+  if (idempotencyKey) {
+    await cache.set(`llm:${idempotencyKey}`, result, { ex: 3600 }); // 1hr TTL
+  }
+
+  res.json(result);
+});
+```
 
 ---
 
-## 🔗 Related Skills
+## Scripts
 
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
+| Script | Purpose | Run With |
+|---|---|---|
+| `scripts/api_validator.py` | Validates endpoint naming and response shape consistency | `python scripts/api_validator.py <project_path>` |
 
 ---
 
-## ✅ Decision Checklist
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
 
-Before designing an API:
+```
+━━━ Api Patterns Recommendation ━━━━━━━━━━━━━━━━
+Decision:    [what was chosen / proposed]
+Rationale:   [why — one concise line]
+Trade-offs:  [what is consciously accepted]
+Next action: [concrete next step for the user]
+─────────────────────────────────────────────────
+Pre-Flight:  ✅ All checks passed
+             or ❌ [blocking item that must be resolved first]
+```
 
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
 
 ---
 
-## ❌ Anti-Patterns
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/tribunal-backend`**
+**Active reviewers: `logic` · `security` · `dependency`**
 
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
+### ❌ Forbidden AI Tropes in API Design
+
+1. **REST = CRUD assumption** — do not assume every REST endpoint maps 1:1 with a database table. APIs model behaviors, not just data.
+2. **Missing Input Validation** — never generate an endpoint that accepts external data without validating it (e.g., Zod, Joi).
+3. **Hardcoded 200 OK** — returning 200 for created resources (should be 201) or async accepted (should be 202). Use precise status codes.
+4. **No Pagination strategy** — returning unbound lists endpoints (e.g., `GET /users`) without limits or cursors.
+5. **Leaky Error Responses** — returning raw database errors or stack traces to the client.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating API design or code:
+```
+✅ Are all inputs validated at the boundary?
+✅ Does every endpoint have an explicit authentication AND authorization check?
+✅ Did I use the correct HTTP verbs and semantic status codes?
+✅ Is the response shape consistent with the rest of the API?
+✅ Did I handle pagination for lists and rate limiting for public endpoints?
+```
 
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
 
 ---
 
-## Script
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+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.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ 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.
+
+### ✅ Pre-Flight Self-Audit
+
+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?
+```
 
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
+**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.

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

@@ -1,75 +1,238 @@
 ---
 name: app-builder
 description: Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
+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
 ---
 
-# App Builder - Application Building Orchestrator
+# App Builder — Application Orchestrator
 
-> Analyzes user's requests, determines tech stack, plans structure, and coordinates agents.
+> Building a full application is a coordination problem, not a coding problem.
+> Coordinate the experts. Keep the boundaries clean.
 
-## 🎯 Selective Reading Rule
+---
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When This Skill Activates
 
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `project-detection.md` | Keyword matrix, project type detection | Starting new project |
-| `tech-stack.md` | 2026 default stack, alternatives | Choosing technologies |
-| `agent-coordination.md` | Agent pipeline, execution order | Coordinating multi-agent work |
-| `scaffolding.md` | Directory structure, core files | Creating project structure |
-| `feature-building.md` | Feature analysis, error handling | Adding features to existing project |
-| `templates/SKILL.md` | **Project templates** | Scaffolding new project |
+Activate when the user request involves:
+- Creating a new application from scratch
+- Building a major feature that spans frontend + backend + database
+- Bootstrapping a project structure for a new stack
 
 ---
 
-## 📦 Templates (13)
-
-Quick-start scaffolding for new projects. **Read the matching template only!**
-
-| Template | Tech Stack | When to Use |
-|----------|------------|-------------|
-| [nextjs-fullstack](templates/nextjs-fullstack/TEMPLATE.md) | Next.js + Prisma | Full-stack web app |
-| [nextjs-saas](templates/nextjs-saas/TEMPLATE.md) | Next.js + Stripe | SaaS product |
-| [nextjs-static](templates/nextjs-static/TEMPLATE.md) | Next.js + Framer | Landing page |
-| [nuxt-app](templates/nuxt-app/TEMPLATE.md) | Nuxt 3 + Pinia | Vue full-stack app |
-| [express-api](templates/express-api/TEMPLATE.md) | Express + JWT | REST API |
-| [python-fastapi](templates/python-fastapi/TEMPLATE.md) | FastAPI | Python API |
-| [react-native-app](templates/react-native-app/TEMPLATE.md) | Expo + Zustand | Mobile app |
-| [flutter-app](templates/flutter-app/TEMPLATE.md) | Flutter + Riverpod | Cross-platform mobile |
-| [electron-desktop](templates/electron-desktop/TEMPLATE.md) | Electron + React | Desktop app |
-| [chrome-extension](templates/chrome-extension/TEMPLATE.md) | Chrome MV3 | Browser extension |
-| [cli-tool](templates/cli-tool/TEMPLATE.md) | Node.js + Commander | CLI app |
-| [monorepo-turborepo](templates/monorepo-turborepo/TEMPLATE.md) | Turborepo + pnpm | Monorepo |
+## Orchestration Flow
+
+```
+1. CLARIFY      → Understand what and who for
+2. DECIDE       → Choose the stack
+3. PLAN         → Break into ordered, dependency-aware tasks
+4. COORDINATE   → Run specialists in the right sequence
+5. INTEGRATE    → Verify boundaries are consistent
+6. PREVIEW      → Start the dev server
+```
 
 ---
 
-## 🔗 Related Agents
+## Phase 1 — Clarification
+
+Before selecting a stack or writing a line of code, ask:
 
-| Agent | Role |
-|-------|------|
-| `project-planner` | Task breakdown, dependency graph |
-| `frontend-specialist` | UI components, pages |
-| `backend-specialist` | API, business logic |
-| `database-architect` | Schema, migrations |
-| `devops-engineer` | Deployment, preview |
+```
+1. What is the core thing this app does? (not features — the primary purpose)
+2. Who uses it? (internal tool, public-facing, B2B, mobile users?)
+3. What constraints matter most? (time to ship, cost, performance, existing stack?)
+4. What already exists that this integrates with?
+```
+
+Wait for answers. Stack decisions depend on these answers.
 
 ---
 
-## Usage Example
+## Phase 2 — Stack Selection
+
+| App Type | Frontend | Backend | Database |
+|---|---|---|---|
+| Content / marketing site | Next.js | Next.js API routes | PostgreSQL (if dynamic) |
+| SaaS web app | Next.js | Next.js API routes / Fastify | PostgreSQL + Redis |
+| Mobile app (cross-platform) | React Native (Expo) | Node.js API | PostgreSQL |
+| Internal dashboard / admin | Next.js | Next.js API routes | Existing |
+| Real-time (chat, collaboration) | Next.js | Fastify + WebSockets | PostgreSQL + Redis |
+| Data-heavy API | — | FastAPI (Python) | PostgreSQL |
+| AI assistant / RAG app | Next.js (streaming) | Fastify + LLM SDK | PostgreSQL + pgvector |
+| Edge-global, latency-critical | Next.js | Hono (Cloudflare Workers) | Turso / Cloudflare KV |
+
+**If unclear:** Next.js + PostgreSQL covers 80% of use cases and is the safest default for web apps.
+
+---
+
+## AI-Native App Orchestration
+
+For RAG apps and AI assistants, the build order changes:
 
 ```
-User: "Make an Instagram clone with photo sharing and likes"
+Step 1: vector-database-architect
+  → Design the embedding schema and chunking strategy
+  → Output: schema with vector column + indexing strategy
+
+Step 2: ingest-pipeline (backend-specialist)
+  → Build document ingestion: load → chunk → embed → store
+  → Output: ingest API endpoint
 
-App Builder Process:
-1. Project type: Social Media App
-2. Tech stack: Next.js + Prisma + Cloudinary + Clerk
-3. Create plan:
-   ├─ Database schema (users, posts, likes, follows)
-   ├─ API routes (12 endpoints)
-   ├─ Pages (feed, profile, upload)
-   └─ Components (PostCard, Feed, LikeButton)
-4. Coordinate agents
-5. Report progress
-6. Start preview
+Step 3: retrieval-api (backend-specialist, uses Steps 1+2)
+  → Build: embed query → vector search → rerank → prompt assembly
+  → Output: /api/generate endpoint with SSE streaming
+
+Step 4: streaming-frontend (frontend-specialist, uses Step 3)
+  → Build: EventSource consumer → streaming text UI → loading states
+  → Output: AI chat or search interface
 ```
+
+**Never wire the frontend to the LLM directly** — always proxy through your backend to keep API keys server-side.
+
+---
+
+## Phase 3 — Project Structure
+
+**Web (Next.js):**
+
+```
+app/
+  (auth)/       Auth pages — login, register
+  (app)/        Protected app routes
+  api/          API routes
+components/
+  ui/           Primitive components (button, input, modal)
+  features/     Feature-specific components
+lib/
+  db/           Database client and utilities
+  auth/         Auth helpers
+  utils/        Shared utilities
+```
+
+**API-only (Node.js / Fastify):**
+
+```
+src/
+  routes/       Route definitions (thin)
+  handlers/     Request handling and response formatting
+  services/     Business logic
+  repositories/ Database access
+  lib/          Shared utilities
+```
+
+---
+
+## Phase 4 — Agent Coordination
+
+Build in dependency order:
+
+```
+Step 1: database-architect
+  → Design and document the schema
+  → Output: SQL schema, type definitions
+
+Step 2: backend-specialist (uses schema from Step 1)
+  → Build API routes
+  → Output: API endpoint spec (URL, method, request, response shapes)
+
+Step 3: frontend-specialist (uses API spec from Step 2)
+  → Build UI components
+  → Connect to real API contracts
+  → Output: Working pages
+
+Step 4: test-engineer (uses all of the above)
+  → Create integration and E2E tests
+  → Output: Test suite
+```
+
+**Never run Step 2 against a guessed schema. Never run Step 3 against a guessed API.**
+
+---
+
+## Phase 5 — Integration Verification
+
+Before presenting to the user, verify consistency:
+
+- API endpoints the frontend calls → exist on the backend
+- Database column names the backend queries → exist in the schema
+- TypeScript types match across package boundaries
+- Environment variables referenced in code → are in `.env.example`
+
+---
+
+## Phase 6 — Preview Launch
+
+After integration verification, start the dev server:
+
+```bash
+# Check for dev script
+python .agent/scripts/auto_preview.py start
+
+# Or manually
+npm run dev
+```
+
+Report the URL to the user.
+
+---
+
+## Template Index
+
+| Template | Path | When to Use |
+|---|---|---|
+| Next.js Full-Stack | `templates/nextjs-app/` | Web app with API routes |
+| React Native | `templates/react-native-app/` | Cross-platform mobile |
+| API Only | `templates/api-only/` | Backend service, no UI |
+
+---
+
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ App Builder Recommendation ━━━━━━━━━━━━━━━━
+Decision:    [what was chosen / proposed]
+Rationale:   [why — one concise line]
+Trade-offs:  [what is consciously accepted]
+Next action: [concrete next step for the user]
+─────────────────────────────────────────────────
+Pre-Flight:  ✅ All checks passed
+             or ❌ [blocking item that must be resolved first]
+```
+
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/create`**
+**Active reviewers: `orchestrator` · `project-planner`**
+
+### ❌ Forbidden AI Tropes in App Building
+
+1. **Skipping Constraints** — immediately starting to generate code without asking the user about their constraints and audience.
+2. **Building the Whole App at Once** — attempting to generate 50 files in a single turn.
+3. **Out-of-Order Execution** — writing frontend components before the API or DB schema is actually designed.
+4. **Magic Dependencies** — assuming packages are installed without updating `package.json`.
+5. **Ignoring Boundaries** — mismatching the API response format between the server and the frontend client.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before orchestrating a full app build:
+```
+✅ Did I ask the clarifying questions regarding constraints and target audience?
+✅ Is my generated plan broken into modular, sequenced steps (DB -> API -> UI)?
+✅ Have I explicitly defined the API contracts so the frontend and backend match?
+✅ Did I correctly track which dependencies need to be installed?
+✅ Am I verifying integration at each boundary before moving to the next layer?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring an application architecture or full-stack integration complete without verifying the seams.
+- ✅ **Required:** You are explicitly forbidden from completing an app build or integration phase without providing **concrete terminal evidence** (e.g., successful local dev server start logs, passing build logs, or successful API local test results).