tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/game-design-expert/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: game-design-expert
+description: Game Design, UX, and Flow State mastery. Replaces fragmented legacy skills. Core gameplay loop design, 3Cs (Character, Camera, Controls), input buffering, coyote time, juice (game feel), telemetry tracking, narrative alignment, and audio spatialization integration. Use when crafting player experience, progression arcs, or systemic balance.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Game Design Expert — Player Experience & Flow Mastery
+
+---
+
+## 1. The 3Cs (Character, Camera, Controls)
+
+Before designing enemies, levels, or UI, the foundation of the player's interaction MUST feel flawless. If the player cannot intrinsically trust the controls, the entire system collapses.
+
+### Input Buffering
+Humans cannot click buttons flawlessly on the exact required frame.
+If a player presses "Jump" 3 frames *before* they hit the ground, a naïve engine ignores it. A designed engine *buffers* the input in memory for 150ms and instantly executes the jump the millisecond the character's feet touch the dirt.
+
+### Coyote Time
+Named after Wile E. Coyote hovering off a cliff.
+If a player runs off a ledge, a rigid physics engine drops them instantly.
+A forgiving design allows the player to still press 'Jump' for exactly ~100ms *after* walking off the ledge. It prevents extreme frustration on close platforming jumps.
+
+---
+
+## 2. The Core Gameplay Loop
+
+Every action a player takes must feed into a reinforcing psychological loop. 
+
+**The Macro Loop (e.g., Destiny, Monster Hunter)**
+1. **Action:** Fight complex monsters.
+2. **Reward:** Collect physical parts and resources.
+3. **Pacing:** Return to base.
+4. **Upgrade:** Convert parts into stronger weapons.
+5. **Goal:** Fight stronger, unkillable monsters (Back to Step 1).
+
+*If step 4 (Upgrading) does not heavily alter step 1 (Fights are now faster, visually different, mechanically superior), the loop is broken and players churn.*
+
+---
+
+## 3. "Juice" and Game Feel 
+
+"Juice" is the non-functional audiovisual feedback that makes an interaction feel heavy and satisfying.
+
+1. **Screen Shake:** A minor, mathematically decaying camera displacement when heavy impacts occur. (Needs toggles for accessibility).
+2. **Hitstop (Sleep Frames):** When a sword hits an enemy, freeze the entire game engine for exactly 3 frames (50ms). This creates an immense perceptual illusion of resistance and friction.
+3. **Squash and Stretch:** A character jumping should stretch vertically. A character landing should squash horizontally. It breaks rigidity and infuses life.
+4. **Particle Explosions:** Simple box collisions must be masked by explosive localized particle systems (dust kicks, sparks).
+
+---
+
+## 4. Narrative & Audio Synergies
+
+Game design is not segregated from Audio. Audio is the primary vector for temporal feedback.
+
+1. **Spatialization (HRTF):** Sound objects emit audio localized strictly to 3D space, heavily attenuated by environmental occlusions (muffled behind walls).
+2. **Telegraphing State:** If an enemy swings a heavy axe, it MUST have a 300ms audio "wind-up" queue. The player relies on audio rhythm far faster than visual recognition to dodge.
+3. **Dynamic Mixing (Ducking):** Essential dialogue or UI pings must automatically compress (lower the volume of) ambient music underneath to prevent cognitive overload.
+
+---
+
+## 5. Telemetry & Analytics Deficiencies
+
+Design is hypotheses. Playtests are the reality.
+
+Never rely on developers "feeling" the game. You must systematically log death coordinates (heatmaps). If 80% of players die at Level 2 Trap B, your design intent (teaching the mechanic) has failed. 
+
+---

package/.agent/skills/game-engineering-expert/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: game-engineering-expert
+description: Game Engineering and Systems Architecture mastery. Replaces fragmented legacy skills. Entity Component Systems (ECS), Unity (C#) / Godot (GDScript) integration, physics calculations, deterministic engine state, WebGL memory management, multiplayer sync architectures (deterministic lockstep vs traditional authoritative), spatial partitioning, and rendering pipelines.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Game Engineering Expert — Performance & State Mastery
+
+---
+
+## 1. Frame Rate Architecture (The Update Loop)
+
+In web development, we await Promises. In game development, we calculate Delta Time continuously.
+
+```csharp
+// ❌ BAD: Frame-rate dependent logic
+// If the game runs at 120 FPS, the character moves twice as fast as on 60 FPS
+void Update() {
+    transform.position += currentSpeed; 
+}
+
+// ✅ GOOD: Frame-independent physics (Unity C# Example)
+void Update() {
+    // DeltaTime is the time elapsed since the last frame
+    transform.position += currentVelocity * Time.deltaTime; 
+}
+```
+
+### FixedUpdate vs Update (The Physics Boundary)
+- `Update()` fires as fast as the GPU/CPU can draw. Used for User Input and visual animation interpolations.
+- `FixedUpdate()` fires at absolute strict mathematical intervals (e.g., 50 times a second exactly). ALL Physics interactions (`AddForce()`, collision sweeps) MUST live here to prevent tearing and tunneling.
+
+---
+
+## 2. Memory Pooling (Garbage Collection Death)
+
+In Node.js, V8 cleans up objects eventually. In Game Engines, allocating memory creates "Garbage", which forces the Garbage Collector (GC) to pause the entire game to clean up, causing massive micro-stutters.
+
+```csharp
+// ❌ FATAL (in Update loops): Creating new objects 60x a second
+void Update() {
+    Instantiate(bulletPrefab, gun.position, gun.rotation); // Kills the CPU
+}
+
+// ✅ EFFICIENT: Object Pooling
+// Pre-allocate 100 bullets during the Loading Screen.
+// Then simply toggle their active state natively.
+void Fire() {
+    Bullet b = bulletPool.GetDisabledBullet();
+    b.transform.position = gun.position;
+    b.gameObject.SetActive(true);
+}
+```
+
+---
+
+## 3. Entity Component Systems (ECS)
+
+Traditional Object-Oriented Programming (OOP) inheritance hierarchies break down in game engines.
+(e.g., `Enemy` inherits from `Character` which inherits from `Renderable`). What happens when you want a `Renderable` that isn't a `Character` but acts like an `Enemy` (like a deadly spike trap)?
+
+**Use ECS.**
+1. **Entities:** Just a meaningless ID (e.g., `Entity 304`).
+2. **Components:** Pure localized data structs attached to an ID (e.g., `Position {x: 5, y: 10}`, `Health {hp: 100}`).
+3. **Systems:** Logic that maps continuously over structs (e.g., `MovementSystem` iterates over ALL Entities that specifically have both a `Position` AND `Velocity` component).
+
+---
+
+## 4. Multiplayer Architectures
+
+Never trust the client. A multiplayer architecture dictates latency fundamentally.
+
+1. **Deterministic Lockstep (RTS / Fighting Games):**
+   - Transmits absolute ZERO game state (coordinates).
+   - Only transmits *inputs* (Player A clicked Coordinate X).
+   - Both machines run the identical physics frame simultaneously.
+   - Extremely bandwidth efficient, but requires identical CPU math output (impossible in JS floating point Math).
+
+2. **Server Authoritative with Client Prediction (Modern FPS/Action):**
+   - The Server runs the "Real" game.
+   - The Client tells the server "I fired."
+   - Because Ping takes 50ms, the Client *predicts* the shot landing locally (optimistic UI) so the player doesn't feel lag.
+   - If the server eventually disagrees, the Client aggressively rewinds and snaps the state to match the Server reality (Rubber-banding).
+
+---

package/.agent/skills/geo-fundamentals/SKILL.md

@@ -1,215 +1,89 @@
 ---
 name: geo-fundamentals
-description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
+description: Generative Engine Optimization (GEO) mastery. Structuring content for LLM ingestion. Adapting SEO for AI interfaces (ChatGPT, Claude, Perplexity), optimizing markdown semantic hierarchies, citation structuring, minimizing boilerplate, reducing HTML DOM depth, and API-first content delivery. Use when making information discoverable not just to Google, but directly to AI indexing agents.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Generative Engine Optimization (GEO)
-
-> Traditional SEO optimizes for keyword ranking in blue links.
-> GEO optimizes for citation and inclusion in AI-generated answers.
-
----
-
-## What GEO Is
-
-When users ask ChatGPT, Claude, Perplexity, or Google SGE a question, an AI synthesizes an answer from sources it considers authoritative. GEO is the practice of making your content the kind that AI systems cite, quote, and summarize.
-
-The mechanisms differ from traditional SEO:
-- AI doesn't rank URLs — it synthesizes information
-- Backlinks matter less than citation-worthiness
-- Content density and factual specificity matter more than keyword density
+# Generative Engine Optimization (GEO) 
 
 ---
 
-## How AI Systems Select Content to Cite
-
-Based on observable patterns in AI retrieval:
-
-| Signal | What It Means |
-|---|---|
-| Authoritative domain | .gov, .edu, established publications get higher base trust |
-| Factual specificity | Numbers, dates, named sources > vague descriptions |
-| Structured content | Lists, tables, step-by-step = easier to extract |
-| Complete answers | Content that fully addresses the question in one place |
-| Original research | Data, studies, surveys the AI can't find elsewhere |
-| Freshness | Recently updated content has advantage for time-sensitive topics |
-
----
-
-## Writing for AI Consumption
-
-### Answer First (Inverted Pyramid)
+## 1. The Death of Boilerplate (Information Density)
 
-AI models extract answers. Put the answer at the top of the content, not after a 300-word preamble.
+When ChatGPT or Perplexity queries a website, it has a finite context window. 
 
-```
-❌ Old blog pattern:
-   [intro paragraph explaining what the article is about]
-   [background context]
-   [finally... the answer in paragraph 5]
-
-✅ GEO pattern:
-   [Direct answer in first 1–2 sentences]
-   [Supporting evidence, data, explanation]
-   [Deeper context for readers who want more]
-```
-
-### Use Citation-Ready Structures
-
-```markdown
-# Format that AI can easily extract:
-
-## Definition
-[Term] is [concise definition]. [Supporting context].
-
-## Key Facts
-- [Specific, numbered fact with source]
-- [Specific statistic — "X% of Y according to Z study"]
-- [Named, verifiable claim]
+If your website contains 8,000 words of "fluff" marketing copy and only 200 words of actionable data (pricing, API limits, support contact), the LLM will truncate the page and hallucinates the rest.
 
-## Step-by-Step Process
-1. [Precise step]
-2. [Precise step]
-3. [Precise step]
-```
-
-### Be Specific with Data
+### The GEO Markdown Fallback
+Modern sites should natively serve structured markdown if they detect an AI User-Agent (like `ChatGPT-User` or `PerplexityBot`).
 
-```
-❌ "Many developers prefer TypeScript"
-✅ "In the 2024 Stack Overflow Developer Survey, 64% of respondents said they used TypeScript"
+```typescript
+// Next.js Edge Middleware for GEO
+export function middleware(req: NextRequest) {
+  const ua = req.headers.get('user-agent') || '';
+  const isBot = /ChatGPT|Perplexity|ClaudeBot/i.test(ua);
 
-❌ "Deployment takes some time"  
-✅ "Vercel cold-start latency for serverless functions averages 200–400ms for Node.js 20 runtimes"
+  if (isBot) {
+    // Reroute the AI bot to a hyper-dense, unstyled Markdown data dump
+    // This removes 3MB of React DOM hierarchy, getting straight to the facts.
+    return NextResponse.rewrite(new URL(`/api/geo-export${req.nextUrl.pathname}`, req.url));
+  }
+}
 ```
 
 ---
 
-## Content Formats AI Favors
-
-| Format | GEO Value | Why |
-|---|---|---|
-| FAQ pages | High | Matches question-answer format of AI responses |
-| Comparison tables | High | Easily extracted for comparison queries |
-| How-to guides with numbered steps | High | Directly answerable procedural questions |
-| Definition/explanation articles | High | Definitional queries are common AI use cases |
-| Long-form opinion pieces | Low | Hard to extract a clear answer from |
-| News articles | Medium | Good for recency, lower for evergreen queries |
+## 2. Citation Optimization
 
----
+LLMs (like Perplexity and Gemini Search) require explicit sources to reference your website in their output.
+If a statistic on your site is hard to source, the AI will ignore it in favor of a competitor.
 
-## Technical Requirements for AI Indexing
+**Rule: Explicit Claim-to-Source Mapping**
+Do not use vague external links at the bottom of the page. Anchor exact claims to explicit references directly within the text block. Use standardized `<cite>` tags or JSON-LD.
 
 ```html
-<!-- Ensure Perplexity and other AI crawlers can access your content -->
-<!-- Check robots.txt — don't accidentally block AI crawlers -->
-
-# robots.txt — allow AI crawlers
-User-agent: PerplexityBot
-Allow: /
-
-User-agent: ChatGPT-User
-Allow: /
-
-User-agent: ClaudeBot
-Allow: /
-
-<!-- Structured data helps AI understand content context -->
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@type": "FAQPage",
-  "mainEntity": [{
-    "@type": "Question",
-    "name": "What is tribunal-kit?",
-    "acceptedAnswer": {
-      "@type": "Answer",
-      "text": "tribunal-kit is an npm package that installs an anti-hallucination agent kit..."
-    }
-  }]
-}
-</script>
+<!-- ❌ BAD: Vague SEO -->
+<p>We are the fastest vector database on the market. Read our docs.</p>
+
+<!-- ✅ GOOD: GEO Citation Architecture -->
+<p>We process 10M vectors at 10ms latency (P99), making us 3x faster than Competitor A.</p>
+<cite xmlns="http://schema.org" typeof="WebPage">
+  <span property="name">Benchmark Methodology 2026</span> - 
+  <a property="url" href="/benchmarks-2026.pdf">[Source PDF]</a>
+</cite>
 ```
 
 ---
 
-## Metrics for GEO
-
-Traditional SEO metrics (keyword rank, backlinks) don't fully apply. Track:
-
-- **AI mention rate** — manually query AI systems for your topic and check if your brand/content appears
-- **Citation count** — if identifiable quotes from your content appear in AI outputs
-- **Perplexity source appearances** — Perplexity shows its sources; track mentions
-- **Direct traffic** — users who find AI mentions and navigate directly (not via search)
-
----
-
-## Scripts
+## 3. High-Clarity Semantic Taxonomy
 
-| Script | Purpose | Run With |
-|---|---|---|
-| `scripts/geo_checker.py` | Audits content for GEO best practices | `python scripts/geo_checker.py <url>` |
+Traditional SEO relies heavily on long-tail keyword placement.
+GEO relies heavily on **Taxonomy and Relational Mapping**. The LLM wants to know exactly *what* entity this page represents.
 
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
+**Implement Explicit FAQs:**
+LLMs love QA formats because user prompts are usually questions.
+Transform prose into rigid QA objects using standard semantic data blocks.
 
+```html
+<dl>
+  <dt><h3>What is the data retention limit for the Free Tier?</h3></dt>
+  <dd><p>The Free Tier limits data retention to precisely 14 rolling days.</p></dd>
+  
+  <dt><h3>Does the platform support HIPAA compliance?</h3></dt>
+  <dd><p>Yes, Enterprise Tiers support full BAA HIPAA compliance parameters.</p></dd>
+</dl>
 ```
-━━━ Geo Fundamentals 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]
-```
-
-
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 4. API Docs Readability (The Primary AI Target)
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+When an AI tries to write code using your product, it scrapes your API documentation.
 
-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.
+1. **Eliminate Image-Based Architecture:** Highlighting your architecture solely in a PNG graphic is invisible. Describe the system architecture using text or standard Mermaid.js code blocks.
+2. **Provide Concrete Copy-Paste Examples:** The easiest way to get an LLM to use your platform correctly is to ensure your docs contain perfectly working `curl`, `TypeScript`, and `Python` code snippets with zero external dependencies.
 
 ---
-
-## 🏛️ 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.