tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/documentation-templates/SKILL.md

@@ -1,194 +1,248 @@
 ---
 name: documentation-templates
 description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
-allowed-tools: Read, Glob, Grep
+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
 ---
 
-# Documentation Templates
+# Documentation Standards
 
-> Templates and structure guidelines for common documentation types.
+> Documentation is a product. It has users. Those users are often future-you,
+> three months from now, having completely forgotten how this works.
 
 ---
 
-## 1. README Structure
+## Documentation Types and Their Audiences
 
-### Essential Sections (Priority Order)
+| Type | Audience | Goal |
+|---|---|---|
+| README | New developer joining the project | "Get me running in 10 minutes" |
+| API docs | External integrator or frontend dev | "Tell me exactly what I can call and what I'll get back" |
+| Architecture decision (ADR) | Future engineer inheriting the codebase | "Tell me why it works this way, not just how" |
+| Code comment | Reviewer, maintainer | "Explain the non-obvious; skip the obvious" |
+| Runbook | On-call engineer at 2am | "Tell me what to do, not what to think about" |
 
-| Section | Purpose |
-|---------|---------|
-| **Title + One-liner** | What is this? |
-| **Quick Start** | Running in <5 min |
-| **Features** | What can I do? |
-| **Configuration** | How to customize |
-| **API Reference** | Link to detailed docs |
-| **Contributing** | How to help |
-| **License** | Legal |
+---
 
-### README Template
+## README Template
 
 ```markdown
 # Project Name
 
-Brief one-line description.
+One sentence: what this is and what problem it solves.
 
 ## Quick Start
 
-[Minimum steps to run]
+\`\`\`bash
+git clone ...
+cd project
+npm install
+cp .env.example .env
+npm run dev
+\`\`\`
+
+Open http://localhost:3000
+
+## Requirements
+
+- Node.js 20+
+- PostgreSQL 15+
+- [Any other hard requirements]
 
-## Features
+## Project Structure
 
-- Feature 1
-- Feature 2
+\`\`\`
+src/
+  api/        API routes
+  lib/        Shared utilities
+  services/   Business logic
+\`\`\`
 
-## Configuration
+## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| PORT | Server port | 3000 |
+| Variable | Required | Description |
+|---|---|---|
+| DATABASE_URL | Yes | PostgreSQL connection string |
+| JWT_SECRET | Yes | Secret for signing JWTs |
 
-## Documentation
+## Running Tests
 
-- [API Reference](./docs/api.md)
-- [Architecture](./docs/architecture.md)
+\`\`\`bash
+npm test              # unit tests
+npm run test:e2e      # end-to-end tests
+\`\`\`
 
-## License
+## Contributing
 
-MIT
+[Brief contribution guide or link to CONTRIBUTING.md]
 ```
 
 ---
 
-## 2. API Documentation Structure
+## API Documentation Standards
 
-### Per-Endpoint Template
+For each endpoint, document:
 
 ```markdown
-## GET /users/:id
+### POST /api/users
+
+Creates a new user account.
+
+**Request Body**
+\`\`\`json
+{
+  "email": "string (required, valid email)",
+  "name": "string (required, 2–100 chars)",
+  "role": "admin | user (optional, default: user)"
+}
+\`\`\`
+
+**Responses**
+
+| Status | Meaning | Body |
+|---|---|---|
+| 201 | User created | `{ data: User }` |
+| 400 | Validation failed | `{ error: string, details: string[] }` |
+| 409 | Email already exists | `{ error: string }` |
+
+**Example**
+\`\`\`bash
+curl -X POST /api/users \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "name": "Jane"}'
+\`\`\`
+```
+
+---
 
-Get a user by ID.
+## Code Comment Rules
 
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| id | string | Yes | User ID |
+**Comment the why, not the what:**
 
-**Response:**
-- 200: User object
-- 404: User not found
+```ts
+// ❌ States what the code does (obvious from reading it)
+// Multiply price by tax rate
+const total = price * taxRate;
 
-**Example:**
-[Request and response example]
+// ✅ Explains why this specific value exists
+// Vietnamese tax law requires 10% VAT on all digital goods (Circular 92/2015)
+const VN_DIGITAL_TAX_RATE = 1.10;
+const total = price * VN_DIGITAL_TAX_RATE;
 ```
 
+**When to always comment:**
+- Non-obvious business rules
+- Workarounds for external library bugs (with issue link if possible)
+- Performance decisions that look like premature optimization but aren't
+- Magic numbers and why they have that value
+
 ---
 
-## 3. Code Comment Guidelines
-
-### JSDoc/TSDoc Template
-
-```typescript
-/**
- * Brief description of what the function does.
- * 
- * @param paramName - Description of parameter
- * @returns Description of return value
- * @throws ErrorType - When this error occurs
- * 
- * @example
- * const result = functionName(input);
- */
-```
+## AI-Friendly Documentation
 
-### When to Comment
+When a codebase will be worked on by AI assistants:
 
-| ✅ Comment | ❌ Don't Comment |
-|-----------|-----------------|
-| Why (business logic) | What (obvious) |
-| Complex algorithms | Every line |
-| Non-obvious behavior | Self-explanatory code |
-| API contracts | Implementation details |
+- Keep a `CODEBASE.md` at root with: tech stack, folder structure, key conventions
+- Add a `ARCHITECTURE.md` with: system boundaries, data flow, key decisions
+- Add `// @purpose:` comments on complex functions so AI can understand intent without reading the full implementation
+- Document which files are auto-generated and should not be edited directly
 
 ---
 
-## 4. Changelog Template (Keep a Changelog)
+## Runbook Template
 
 ```markdown
-# Changelog
-
-## [Unreleased]
-### Added
-- New feature
-
-## [1.0.0] - 2025-01-01
-### Added
-- Initial release
-### Changed
-- Updated dependency
-### Fixed
-- Bug fix
-```
+# Runbook: [Service or Incident Type]
 
----
+## Symptoms
+- [What the user or monitor reports]
 
-## 5. Architecture Decision Record (ADR)
+## Likely Causes
+1. [Most common cause]
+2. [Second most common]
 
-```markdown
-# ADR-001: [Title]
+## Investigation Steps
+\`\`\`bash
+# Check service health
+kubectl get pods -n production
+
+# Check recent errors
+kubectl logs deployment/api --since=15m | grep ERROR
+\`\`\`
 
-## Status
-Accepted / Deprecated / Superseded
+## Resolution Steps
+### If Cause 1:
+[Exact steps to resolve]
 
-## Context
-Why are we making this decision?
+### If Cause 2:
+[Exact steps to resolve]
 
-## Decision
-What did we decide?
+## Escalation
+If unresolved after 30 minutes → page @on-call-lead
 
-## Consequences
-What are the trade-offs?
+## Post-Incident
+[ ] Write incident report
+[ ] Add monitoring for this failure mode
+[ ] Update this runbook if steps changed
 ```
 
 ---
 
-## 6. AI-Friendly Documentation (2025)
+## Output Format
 
-### llms.txt Template
+When this skill completes a task, structure your output as:
 
-For AI crawlers and agents:
+```
+━━━ Documentation Templates Output ━━━━━━━━━━━━━━━━━━━━━━━━
+Task:        [what was performed]
+Result:      [outcome summary — one line]
+─────────────────────────────────────────────────
+Checks:      ✅ [N passed] · ⚠️  [N warnings] · ❌ [N blocked]
+VBC status:  PENDING → VERIFIED
+Evidence:    [link to terminal output, test result, or file diff]
+```
 
-```markdown
-# Project Name
-> One-line objective.
 
-## Core Files
-- [src/index.ts]: Main entry
-- [src/api/]: API routes
-- [docs/]: Documentation
 
-## Key Concepts
-- Concept 1: Brief explanation
-- Concept 2: Brief explanation
-```
+---
+
+## 🤖 LLM-Specific Traps
 
-### MCP-Ready Documentation
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-For RAG indexing:
-- Clear H1-H3 hierarchy
-- JSON/YAML examples for data structures
-- Mermaid diagrams for flows
-- Self-contained sections
+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.
 
 ---
 
-## 7. Structure Principles
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-| Principle | Why |
-|-----------|-----|
-| **Scannable** | Headers, lists, tables |
-| **Examples first** | Show, don't just tell |
-| **Progressive detail** | Simple → Complex |
-| **Up to date** | Outdated = misleading |
+**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?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-> **Remember:** Templates are starting points. Adapt to your project's needs.
+**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/dotnet-core-expert/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: dotnet-core-expert
+description: Senior .NET Core expert with expertise in .NET 10, C# 14, and modern minimal APIs. Use for cloud-native patterns, microservices architecture, cross-platform performance, and native AOT compilation.
+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
+---
+
+# Dotnet Core Expert - Claude Code Sub-Agent
+
+You are a senior .NET Core expert with expertise in .NET 10 and modern C# 14+ development. Your focus spans minimal APIs, cloud-native patterns, microservices architecture, and cross-platform development with emphasis on building high-performance applications that leverage the latest .NET innovations.
+
+## Configuration & Context Assessment
+When invoked:
+1. Query context manager for .NET project requirements and architecture
+2. Review application structure, performance needs, and deployment targets
+3. Analyze microservices design, cloud integration, and scalability requirements
+4. Implement .NET solutions with performance and maintainability focus
+
+---
+
+## The .NET Excellence Checklist
+- .NET 10 features utilized properly
+- C# 14 features leveraged effectively
+- Nullable reference types enabled correctly
+- AOT compilation ready configured thoroughly
+- Test coverage > 80% achieved consistently
+- OpenAPI documented completed properly
+- Container optimized verified successfully
+- Performance benchmarked maintained effectively
+
+---
+
+## Core Architecture Decision Framework
+
+### C# 14 & Innovative Language Features
+*   Record types, Pattern matching, Global usings, File-scoped types, Init-only properties.
+*   Top-level programs, Source generators, Required members.
+
+### Next-Gen Minimal APIs & ASP.NET Core
+*   **Minimal Endpoints:** Endpoint routing, Request handling, Model binding, Validation patterns, OpenAPI/Swagger.
+*   **Middleware:** Middleware pipeline, Filters/attributes, Caching strategies, Session management, Cookie auth, JWT tokens.
+*   **Advanced Networking:** gRPC services, SignalR hubs, Background services, Channels, Web APIs, GraphQL.
+
+### Microservices & Cloud-Native
+*   **Architecture:** Domain/Application/Infrastructure layers, Clean Architecture, Dependency Injection, CQRS/MediatR, Repository pattern.
+*   **Microservices Design:** API gateway, Service discovery, Resilience patterns, Circuit breakers, Distributed tracing, Event bus.
+*   **Cloud Integrations:** Docker optimization, Kubernetes deployment, Health checks, Graceful shutdown, Secret management, Observability.
+
+### Extreme Performance Optimization
+*   Native AOT & Trimming
+*   Memory pooling, Span/Memory usage, SIMD operations
+*   Response compression, Connection pooling
+
+---
+
+## Output Format
+
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Dotnet Core Expert Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Dotnet Core Expert
+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` · `dependency` · `type-safety`**
+
+### ❌ Forbidden AI Tropes in .NET Core
+1. **Bloated Controllers** — always favor Minimal APIs or CQRS architectures over monolithic MVC Controllers for new APIs.
+2. **Ignoring AOT Compatibility** — do not use `Reflection.Emit` or heavy runtime reflection if targeting Native AOT environments.
+3. **Synchronous DB/File I/O** — always use async variants (`ReadLineAsync`, `ToListAsync`). 
+4. **Improper DI Lifetimes** — avoid injecting Transient services into Singletons (Captive Dependency) unless using factory patterns.
+5. **No Structured Logging** — always use `ILogger` with structured tags rather than `Console.WriteLine` or string interpolation.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating .NET Core code:
+```text
+✅ Is my minimal API mapped using structured endpoint groups with OpenAPI extensions?
+✅ Have I properly handled dependency injection scopes (Scoped/Transient/Singleton)?
+✅ Is the code strictly Native AOT compatible (if applicable)?
+✅ Did I use robust background service architectures (`IHostedService` or Channels) instead of raw background threads?
+✅ Did I properly manage secrets via environment configurations instead of hardcoded strings?
+```

package/.agent/skills/edge-computing/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: edge-computing
+description: Edge function design principles. Cloudflare Workers, Durable Objects, edge-compatible data patterns, cold start elimination, and global data locality. Use when designing latency-sensitive features, AI inference at the edge, or globally distributed applications.
+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
+---
+
+# Edge Computing Principles
+
+> Edge is not "just serverless but faster."
+> It's a fundamentally different execution model with different constraints.
+
+---
+
+## Edge vs Serverless vs Server
+
+Before choosing edge, understand what you're getting and what you're giving up:
+
+| Property | Traditional Server | Serverless (Lambda) | Edge (Workers) |
+|---|---|---|---|
+| Cold start | None | 100ms–2s | < 5ms (V8 isolates) |
+| Runtime | Full Node.js | Full Node.js | ⚠️ Subset of Web APIs only |
+| Latency to user | One region | One region | < 30ms globally |
+| Max CPU time | Unlimited | 15 min | 30ms–1s per request |
+| `fs` module | ✅ | ✅ | ❌ No filesystem |
+| `child_process` | ✅ | ✅ | ❌ No subprocess |
+| Memory | GB+ | 128MB–3GB | 128MB |
+| Persistent state | DB + disk | DB only | Durable Objects / KV |
+| Cost model | Fixed | Per invocation | Per invocation (cheaper) |
+
+**Rule: Choose edge when latency is the primary constraint and you can work within its API restrictions.**
+
+---
+
+## Edge Runtime Constraints
+
+The edge runtime implements **Web Platform APIs**, not Node.js APIs. This causes the most hallucinations:
+
+```ts
+// ❌ Node.js APIs — not available at the edge
+import fs from 'fs';                          // No filesystem
+import { createHash } from 'crypto';          // No Node crypto module
+import { exec } from 'child_process';         // No subprocess
+import path from 'path';                      // No path module
+const __dirname = path.dirname(fileURLToPath(import.meta.url));  // No __dirname
+
+// ✅ Web Platform APIs — available everywhere at the edge
+const hash = await crypto.subtle.digest('SHA-256', Buffer.from(input));
+const response = await fetch('https://api.example.com/data');
+const encoded = btoa(jsonString);
+const parsed = JSON.parse(body);
+```
+
+---
+
+## Cloudflare Workers Patterns
+
+### Basic Worker Structure
+
+```ts
+// src/index.ts — Cloudflare Workers (Hono framework recommended)
+import { Hono } from 'hono';
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.get('/api/hello', async (c) => {
+  // Access environment variables via c.env — not process.env
+  const apiKey = c.env.API_KEY;
+  return c.json({ message: 'Hello from the edge' });
+});
+
+export default app;
+```
+
+### Durable Objects — Stateful Edge
+
+Durable Objects provide a single-threaded, globally-unique actor model for stateful workloads at the edge (think: per-room chat state, rate limiters, presence):
+
+```ts
+// Durable Object — each instance is a unique stateful actor
+export class RoomState {
+  private state: DurableObjectState;
+  private users = new Set<WebSocket>();
+
+  constructor(state: DurableObjectState) {
+    this.state = state;
+    // Restore state across hibernation
+    this.state.getWebSockets().forEach(ws => this.users.add(ws));
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    if (request.headers.get('Upgrade') === 'websocket') {
+      const [client, server] = Object.values(new WebSocketPair());
+      this.state.acceptWebSocket(server);
+      this.users.add(server);
+      return new Response(null, { status: 101, webSocket: client });
+    }
+    return new Response('Not a WebSocket', { status: 400 });
+  }
+}
+```
+
+---
+
+## Edge-Compatible Data Patterns
+
+The edge has no local disk. Data access must be network-based and ultra-low-latency:
+
+| Data Type | Edge Solution | Do Not Use |
+|---|---|---|
+| Key-value | Cloudflare KV, Upstash Redis (HTTP) | Redis TCP (not HTTP) |
+| Relational | Turso (libSQL over HTTP), Neon (HTTP) | PostgreSQL TCP connection |
+| Blob / files | Cloudflare R2, S3 (via HTTP) | Local disk |
+| Session / cache | Cloudflare KV | In-memory (dies per request) |
+| Vector search | Vectorize (Cloudflare), Pinecone HTTP | pgvector (TCP) |
+
+```ts
+// ✅ Turso — SQLite at the edge via HTTP API
+import { createClient } from '@libsql/client/http';
+
+const db = createClient({
+  url: env.TURSO_DATABASE_URL,
+  authToken: env.TURSO_AUTH_TOKEN,
+});
+
+const { rows } = await db.execute('SELECT * FROM users WHERE id = ?', [userId]);
+```
+
+---
+
+## Cold Start Design
+
+The main advantage of edge (V8 isolates) is cold starts under 5ms vs Lambda's 100ms+. But you can still waste this advantage:
+
+```ts
+// ❌ Heavy initialization in module scope — runs on every cold start
+import { HeavyDependency } from 'huge-library';  // 50KB parse time
+const expensiveClient = new HeavyDependency({ ... });  // Slow init
+
+// ✅ Lazy initialization — only create when needed
+let client: HeavyClient | null = null;
+function getClient(env: Env) {
+  if (!client) client = new HeavyClient({ apiKey: env.OPENAI_API_KEY });
+  return client;
+}
+```
+
+---
+
+## Data Locality & GDPR Compliance
+
+```
+Problem: User in Germany hits edge node in Singapore → data can't leave EU.
+
+Solution: Cloudflare Smart Placement + regional routing
+
+// wrangler.toml — restrict processing to EU jurisdiction
+[placement]
+mode = "smart"
+
+// Or explicit routing: route EU traffic to EU DOs only
+const id = env.ROOM.idFromName(`eu:${roomId}`);
+```
+
+---
+
+## Output Format
+
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Edge Computing Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Edge Computing
+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` · `dependency`**
+
+### ❌ Forbidden AI Tropes in Edge Computing
+
+1. **Importing Node.js built-ins** — `fs`, `path`, `crypto` (Node), `child_process` are not available at the edge. The edge runtime is Web Platform APIs only.
+2. **`process.env` at the edge** — Cloudflare Workers use `env` parameter (binding), not `process.env`. Wrangler `vars` are accessed via `c.env.VAR_NAME`.
+3. **TCP database connections** — standard PostgreSQL TCP connections don't work from edge. Use HTTP-based drivers (Neon serverless, Turso libSQL, PlanetScale HTTP).
+4. **Any in-request state persistence** — edge workers are stateless per request. Use Durable Objects for state, KV for cache.
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Does this code use only Web Platform APIs (fetch, crypto.subtle, btoa, etc.)?
+✅ Are all database connections via HTTP drivers, not TCP (no pg.Pool at the edge)?
+✅ Are environment variables accessed via the env binding, not process.env?
+✅ Is any stateful data stored in KV or Durable Objects, not in-memory variables?
+✅ Are heavy module imports lazy-loaded to avoid unnecessary cold start delays?
+```