tribunal-kit 1.0.0 → 2.4.0

package/.agent/skills/config-validator/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: config-validator
+description: Self-validation skill for the .agent directory. Checks that all agents, skills, workflows, and scripts referenced across the system actually exist and are consistent. Use after modifying agent configuration files.
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Config Validator — Agent System Self-Check
+
+This skill validates the internal consistency of the `.agent/` directory itself. When the agent system references files that don't exist, behavior becomes unpredictable. This skill catches those gaps.
+
+---
+
+## When to Use
+
+- After adding, renaming, or removing any agent, skill, workflow, or script
+- After copying the `.agent/` directory to a new project
+- When something "should work" but the agent seems to ignore it
+- As part of `/audit` to ensure the agent system itself is healthy
+
+---
+
+## What Gets Checked
+
+### 1. Agent File Existence
+
+Every agent referenced in `rules/GEMINI.md` routing table must have a corresponding `.md` file in `agents/`.
+
+```
+For each agent in the routing table:
+  → Does agents/{agent-name}.md exist?
+  → If not: report as MISSING AGENT
+```
+
+### 2. Skill References in Agent Frontmatter
+
+Every skill listed in an agent's `skills:` frontmatter field must exist as a directory in `skills/` with a `SKILL.md` file.
+
+```
+For each agent file:
+  → Read YAML frontmatter
+  → For each skill in skills: field
+    → Does skills/{skill-name}/SKILL.md exist?
+    → If not: report as MISSING SKILL
+```
+
+### 3. Workflow File Existence
+
+Every slash command listed in `GEMINI.md` or `ARCHITECTURE.md` must have a corresponding `.md` file in `workflows/`.
+
+```
+For each /command referenced:
+  → Does workflows/{command}.md exist?
+  → If not: report as MISSING WORKFLOW
+```
+
+### 4. Script File Existence
+
+Every script referenced in `rules/GEMINI.md` script table must exist in `scripts/`.
+
+```
+For each script in the reference table:
+  → Does scripts/{script-name} exist?
+  → If not: report as MISSING SCRIPT
+```
+
+### 5. Cross-Reference Consistency
+
+- Agent names in the routing table match filenames in `agents/`
+- Workflow names in the command table match filenames in `workflows/`
+- No orphan files (files that exist but are never referenced anywhere)
+
+---
+
+## Validation Process
+
+Run this check manually or mentally when modifying the `.agent/` structure:
+
+```
+Step 1: Read rules/GEMINI.md → Extract agent names, script names
+Step 2: Read GEMINI.md → Extract slash command names
+Step 3: Read ARCHITECTURE.md → Extract all references
+Step 4: Read each agent .md → Extract skill references from frontmatter
+Step 5: Cross-check every reference against the filesystem
+Step 6: Report any mismatches
+```
+
+### Report Format
+
+```
+🔧 Config Validation Report
+━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Agents:    27 found, 27 referenced ✅
+Skills:    37 found, 34 referenced ⚠️ (3 unreferenced)
+Workflows: 22 found, 22 referenced ✅
+Scripts:   10 found, 10 referenced ✅
+
+Issues:
+  ❌ MISSING: skills/some-removed-skill/SKILL.md (referenced by agents/backend-specialist.md)
+  ⚠️ ORPHAN: agents/old-unused-agent.md (not referenced in routing table)
+```
+
+---
+
+## Fixing Common Issues
+
+| Issue | Fix |
+|---|---|
+| Missing agent file | Create the agent `.md` file or remove from routing table |
+| Missing skill directory | Create `skills/{name}/SKILL.md` or remove from agent `skills:` field |
+| Missing workflow file | Create `workflows/{name}.md` or remove from slash command table |
+| Missing script | Create the script or remove from script reference table |
+| Orphan file | Either reference it somewhere or delete it |
+
+---
+
+## Hallucination Guard
+
+- Never report a file as "existing" without actually checking the filesystem
+- Never report a reference as "valid" without reading the referencing file
+- If a file exists but has different content than expected, flag it rather than assuming it's correct
+
+
+---
+
+## 🤖 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?
+```
+
+### 🛑 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/csharp-developer/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: csharp-developer
+description: Senior C# developer with mastery of .NET 8+ and the Microsoft ecosystem. Specializing in high-performance web applications, cloud-native solutions, cross-platform development, ASP.NET Core, Blazor, and Entity Framework Core.
+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
+---
+
+# Csharp Developer - Claude Code Sub-Agent
+
+You are a senior C# developer with mastery of .NET 8+ and the Microsoft ecosystem. Your focus spans building high-performance web applications, cloud-native solutions, cross-platform development, and modern C# language features with a focus on clean code and architectural patterns.
+
+## Configuration & Context Assessment
+When invoked:
+1. Query context manager for existing .NET solution structure and project configuration
+2. Review `.csproj` files, NuGet packages, and solution architecture
+3. Analyze C# patterns, nullable reference types usage, and performance characteristics
+4. Implement solutions leveraging modern C# features and .NET best practices
+
+---
+
+## The C# Excellence Checklist
+- Nullable reference types enabled
+- Code analysis with `.editorconfig`
+- StyleCop and analyzer compliance
+- Test coverage exceeding 80%
+- API versioning implemented
+- Performance profiling completed
+- Security scanning passed
+- Documentation XML generated
+
+---
+
+## Core Architecture Decision Framework
+
+### Modern C# Patterns & Language Features
+*   **Immutability & Types:** Record types, Nullable reference types discipline, Global using directives.
+*   **Control Flow & Expressions:** Pattern matching expressions, LINQ optimization techniques, Expression trees usage.
+*   **Advanced Concepts:** Async/await best practices, Source generators adoption.
+*   **Async Programming:** `ConfigureAwait` usage, Cancellation tokens, Async streams, `Parallel.ForEachAsync`, Channels for producers, Exception handling, Deadlock prevention.
+
+### ASP.NET Core & Blazor Development
+*   **Minimal APIs:** Middleware pipeline optimization, Endpoint filters, OpenAPI integration, Route groups, custom model binding, Output caching strategies, Health checks.
+*   **Blazor:** Component architecture design, State management patterns, JavaScript interop, WebAssembly optimization, Server-side vs WASM, Component lifecycle, Real-time with SignalR.
+*   **gRPC Integration:** Service definition, Client factory setup, Interceptors, Streaming patterns.
+
+### Entity Framework Core & Data Access
+*   Code-first migrations and Interceptors
+*   Query optimization, compiled queries, and bulk operations
+*   Complex relationships and change tracking optimization
+*   Multi-tenancy implementation
+
+### Extreme Performance & Architecture Patterns
+*   `Span<T>` and `Memory<T>` usage, ArrayPool for allocations
+*   ValueTask patterns, SIMD operations
+*   AOT compilation readiness, trimming compatibility
+*   Clean Architecture setup, CQRS with MediatR, Repository pattern, Result/Options pattern.
+
+---
+
+## Output Format
+
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Csharp Developer Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Csharp Developer
+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 C#
+1. **Missing Async/Await** — always use async methods for I/O bound operations. Never use `.Wait()` or `.Result` synchronously.
+2. **Ignoring Nullable Reference Types** — always respect `?` and `!` annotations; do not hallucinate null-checks if the compiler validates it.
+3. **Leaking Entity instances to APIs** — always use DTOs or ViewModels instead of returning raw Entity Framework models from controllers/Minimal APIs.
+4. **Hardcoded Connection Strings** — always use `IConfiguration` or secret managers (Azure Key Vault).
+5. **Inefficient LINQ** — beware of multiple enumeration or pulling entire DB tables into memory before filtering (`.ToList().Where(...)`).
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating C# code:
+```text
+✅ Did I maximize the use of modern C# features (records, pattern matching, primary constructors)?
+✅ Are all asynchronous methods passing `CancellationToken` correctly?
+✅ Is dependency injection configured properly without anti-patterns (e.g. Service Locator)?
+✅ Are my Minimal APIs grouped and versioned properly?
+✅ Did I use MediatR or Repository layers instead of stuffing logic into the Endpoint/Controller?
+```

package/.agent/skills/database-design/SKILL.md

@@ -2,51 +2,274 @@
 name: database-design
 description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
 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
 ---
 
-# Database Design
+# Database Design Principles
 
-> **Learn to THINK, not copy SQL patterns.**
+> A schema is cheap to design and expensive to migrate.
+> Design it right for the queries your app actually runs.
 
-## 🎯 Selective Reading Rule
+---
+
+## Core Decision: What Database?
+
+Before schema design, the database type must be justified — not assumed.
+
+| Need | Consider |
+|---|---|
+| Relational data with integrity constraints | PostgreSQL (default choice for most apps) |
+| Horizontal write scaling, flexible schema | MongoDB, DynamoDB |
+| Sub-millisecond reads, ephemeral/session data | Redis, Upstash |
+| Full-text search as primary use case | Elasticsearch, Typesense |
+| Serverless, zero-ops, edge-deployable | Turso, PlanetScale, Neon |
+| Time-series events | InfluxDB, TimescaleDB |
+| Semantic / vector similarity search | pgvector (in PostgreSQL), Qdrant, Pinecone |
+
+**Default when uncertain:** PostgreSQL. It handles relational, JSON, full-text, and time-series use cases well enough that you rarely need to deviate for most applications.
+
+---
+
+## Vector Database Patterns
+
+AI applications need semantic search — finding documents by meaning, not keyword. Vector databases store high-dimensional embeddings and search them by similarity.
+
+### pgvector — Stay in PostgreSQL
+
+```sql
+-- Enable extension once
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Add embedding column to existing table
+ALTER TABLE documents ADD COLUMN embedding vector(1536);  -- 1536 for text-embedding-3-small
+
+-- IVFFlat index for approximate nearest neighbor search
+CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+-- lists = sqrt(num_rows) is a good starting point
+
+-- Query: find 5 most semantically similar documents
+SELECT id, content, 1 - (embedding <=> $1) AS similarity
+FROM documents
+ORDER BY embedding <=> $1  -- cosine distance operator
+LIMIT 5;
+```
+
+### Dedicated Vector DB: When pgvector Isn't Enough
+
+| Trigger to Upgrade | Recommended |
+|---|---|
+| > 1M vectors + sub-10ms p99 | Qdrant (self-hosted, Rust) or Pinecone (managed) |
+| Multimodal (text + images) | Weaviate |
+| Managed, predictable pricing | Pinecone |
+| Zero-ops prototype | ChromaDB (local) |
+
+### Chunking + Storage Best Practice
+
+```ts
+// Always store both the raw text AND the embedding — embeddings are not reversible
+await db.query(`
+  INSERT INTO documents (content, source_url, chunk_index, embedding)
+  VALUES ($1, $2, $3, $4)
+`, [chunkText, sourceUrl, chunkIndex, JSON.stringify(embedding)]);
+// embedding is float[] — serialize to JSON for parameterized query
+```
+
+---
+
+## Schema Design Rules
+
+### Model for queries, not for elegance
+
+The most normalized schema is not always the right schema. Ask: **what does the application actually read?**
+
+Design the schema to make the most frequent, performance-critical queries fast — even if that means some denormalization.
+
+### Naming Conventions
+
+```sql
+-- Tables: plural, snake_case
+CREATE TABLE user_sessions (...);
+
+-- Primary keys: always "id"
+id UUID PRIMARY KEY DEFAULT gen_random_uuid();
+
+-- Foreign keys: {referenced_table_singular}_id
+user_id UUID REFERENCES users(id);
+
+-- Timestamps: always include both
+created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW();
+
+-- Booleans: is_ prefix
+is_active BOOLEAN NOT NULL DEFAULT TRUE;
+```
+
+### Required on Every Table
+
+```sql
+id          UUID PRIMARY KEY    -- or BIGSERIAL for high-insert tables
+created_at  TIMESTAMPTZ         -- immutable creation time
+updated_at  TIMESTAMPTZ         -- changes on every update (trigger or ORM)
+```
+
+---
+
+## Indexing Strategy
+
+An index makes reads faster and writes slightly slower. Index on the columns you filter and sort — not every column.
+
+**Index when:**
+- Column appears in `WHERE` clauses frequently
+- Column is used for `JOIN` conditions
+- Column is used in `ORDER BY` on large result sets
+- Column is a foreign key that will be queried by relationship
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+**Don't index when:**
+- Table has under a few thousand rows — full scan is faster than index lookup overhead
+- Column has very low cardinality (e.g., a boolean field with 95% TRUE)
+- Column is rarely queried
 
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
-| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
-| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
-| `indexing.md` | Index types, composite indexes | Performance tuning |
-| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
-| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+```sql
+-- Composite index: order matters — most selective first
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Partial index: only index what you query
+CREATE INDEX idx_active_users ON users(email) WHERE is_active = TRUE;
+```
 
 ---
 
-## ⚠️ Core Principle
+## N+1 Queries
+
+The most common ORM performance failure. N+1 happens when you fetch N records then make a separate query for each one.
+
+```ts
+// ❌ N+1 — 1 query for posts + N queries for authors
+const posts = await Post.findAll();
+for (const post of posts) {
+  post.author = await User.findById(post.userId); // N queries
+}
 
-- ASK user for database preferences when unclear
-- Choose database/ORM based on CONTEXT
-- Don't default to PostgreSQL for everything
+// ✅ Eager load — 2 queries total
+const posts = await Post.findAll({ include: ['author'] });
+```
+
+**Detection:** Enable query logging in development. If you see repetitive queries differing only by ID, you have N+1.
 
 ---
 
-## Decision Checklist
+## Migration Rules
+
+- Every schema change is a migration — never modify the database directly in production
+- Migrations are additive first: add the column, deploy code that uses it, then remove the old column later
+- Never drop a column in the same migration that deploys the code removing its references
+- Test migrations on a production-size dataset — a 10-second migration on dev can lock a table for hours on prod
 
-Before designing schema:
+---
+
+## File Index
 
-- [ ] Asked user about database preference?
-- [ ] Chosen database for THIS context?
-- [ ] Considered deployment environment?
-- [ ] Planned index strategy?
-- [ ] Defined relationship types?
+| File | Covers | Load When |
+|---|---|---|
+| `schema-design.md` | Detailed schema patterns and relationship modeling | Designing or reviewing a schema |
+| `indexing.md` | When and how to index, partial indexes, covering indexes | Performance investigation |
+| `orm-selection.md` | Prisma vs Drizzle vs TypeORM vs raw SQL trade-offs | Choosing ORM |
+| `migrations.md` | Safe migration patterns, rollback strategy | Changing existing schema |
+| `optimization.md` | Query analysis, EXPLAIN output, common fixes | Slow query diagnosis |
+| `database-selection.md` | Detailed database selection framework | Architecture decision |
 
 ---
 
-## Anti-Patterns
+## Scripts
+
+| Script | Purpose | Run With |
+|---|---|---|
+| `scripts/schema_validator.py` | Validates schema for missing indexes, naming issues | `python scripts/schema_validator.py <project_path>` |
+
+---
+
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ Database Design 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: `/tribunal-database`**
+**Active reviewers: `logic` · `security` · `sql`**
+
+### ❌ Forbidden AI Tropes in Database Design
+
+1. **Blindly guessing column types** — e.g., using `VARCHAR(255)` for everything instead of precise types or `TEXT`.
+2. **Missing `updated_at` triggers** — defining `updated_at` without a mechanism to actually update it.
+3. **N+1 queries by default** — returning code that queries relations in a loop.
+4. **Destructive migrations** — dropping a column in the same migration that drops the code using it.
+5. **Over-indexing** — adding indexes to every single column regardless of cardinality or query patterns.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating database schemas or queries:
+```
+✅ Did I design for the queries the application actually runs, rather than theoretical elegance?
+✅ Are my suggested indexes selective and actually used in `WHERE` or `JOIN` clauses?
+✅ Is this code safe from N+1 query performance problems?
+✅ Did I rely on parameterized queries (no string concatenation)?
+✅ Did I use the correct primary key strategy (e.g., UUID vs BIGSERIAL) for the scale?
+```
+
+
+---
+
+## 🤖 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?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-❌ Default to PostgreSQL for simple apps (SQLite may suffice)
-❌ Skip indexing
-❌ Use SELECT * in production
-❌ Store JSON when structured data is better
-❌ Ignore N+1 queries
+**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.