tribunal-kit 9.2.4 → 9.2.5

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

@@ -1,251 +1,251 @@
----
-name: documentation-templates
-description: "Use when Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - readme-builder
-  - geo-fundamentals
-  - clean-code
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Documentation Standards
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Hallucination Traps (Read First)
-
-- ❌ Writing documentation that only AI-generated code can understand -> ✅ Docs are for HUMANS; use clear language and real examples
-- ❌ Documenting implementation details instead of behavior -> ✅ Document WHAT it does and WHY, not HOW (code shows how)
-- ❌ Skipping the 'Quick Start' section -> ✅ The first 30 seconds of a README determine if someone uses your project
-
----
-
----
-
-## Documentation Types and Their Audiences
-
-| 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"            |
-
----
-
-## Skill Pattern Inheritance
-
-The Tribunal Agent Kit supports 5 standard Agent Design Kit (ADK) base patterns.
-To build a skill using a robust, tested agent behavior model, add `pattern: [pattern-name]` to the YAML frontmatter of your `SKILL.md`.
-
-| Pattern          | Value                   | When to use                                                                       |
-| ---------------- | ----------------------- | --------------------------------------------------------------------------------- |
-| **Inversion**    | `pattern: inversion`    | Forces the agent to interview the user (Socratic Gate) before acting.             |
-| **Reviewer**     | `pattern: reviewer`     | Evaluates artifacts against a checklist and severity levels.                      |
-| **Tool Wrapper** | `pattern: tool-wrapper` | Strictly executes external CLI tools via provided documentation without guessing. |
-| **Generator**    | `pattern: generator`    | Produces structured output (docs, boilerplate) by filling a rigid template.       |
-| **Pipeline**     | `pattern: pipeline`     | Executes sequential tasks with strict halting gates between steps.                |
-
-_Templates defining the specific rules for these patterns live in `.agent/patterns/`._
-
----
-
-## README Template
-
-```markdown
-# Project Name
-
-One sentence: what this is and what problem it solves.
-
-## Quick Start
-
-\`\`\`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]
-
-## Project Structure
-
-\`\`\`
-src/
-api/ API routes
-lib/ Shared utilities
-services/ Business logic
-\`\`\`
-
-## Environment Variables
-
-| Variable     | Required | Description                  |
-| ------------ | -------- | ---------------------------- |
-| DATABASE_URL | Yes      | PostgreSQL connection string |
-| JWT_SECRET   | Yes      | Secret for signing JWTs      |
-
-## Running Tests
-
-\`\`\`bash
-npm test # unit tests
-npm run test:e2e # end-to-end tests
-\`\`\`
-
-## Contributing
-
-[Brief contribution guide or link to CONTRIBUTING.md]
-```
-
----
-
-## API Documentation Standards
-
-For each endpoint, document:
-
-```markdown
-### 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"}'
-\`\`\`
-```
-
----
-
-## Code Comment Rules
-
-**Comment the why, not the what:**
-
-```ts
-// ❌ States what the code does (obvious from reading it)
-// Multiply price by tax rate
-const total = price * taxRate;
-
-// ✅ 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.1;
-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
-
----
-
-## AI-Friendly Documentation
-
-When a codebase will be worked on by AI assistants:
-
-- 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
-
----
-
-## Runbook Template
-
-```markdown
-# Runbook: [Service or Incident Type]
-
-## Symptoms
-
-- [What the user or monitor reports]
-
-## Likely Causes
-
-1. [Most common cause]
-2. [Second most common]
-
-## Investigation Steps
-
-\`\`\`bash
-
-# Check service health
-
-kubectl get pods -n production
-
-# Check recent errors
-
-kubectl logs deployment/api --since=15m | grep ERROR
-\`\`\`
-
-## Resolution Steps
-
-### If Cause 1:
-
-[Exact steps to resolve]
-
-### If Cause 2:
-
-[Exact steps to resolve]
-
-## Escalation
-
-If unresolved after 30 minutes → page @on-call-lead
-
-## Post-Incident
-
-[ ] Write incident report
-[ ] Add monitoring for this failure mode
-[ ] Update this runbook if steps changed
-```
-
----
-
-## Output Format
-
-When this skill completes a task, structure your output as:
-
-```
-━━━ 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]
-```
+---
+name: documentation-templates
+description: "Use when Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - readme-builder
+  - geo-fundamentals
+  - clean-code
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Documentation Standards
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## Hallucination Traps (Read First)
+
+- ❌ Writing documentation that only AI-generated code can understand -> ✅ Docs are for HUMANS; use clear language and real examples
+- ❌ Documenting implementation details instead of behavior -> ✅ Document WHAT it does and WHY, not HOW (code shows how)
+- ❌ Skipping the 'Quick Start' section -> ✅ The first 30 seconds of a README determine if someone uses your project
+
+---
+
+---
+
+## Documentation Types and Their Audiences
+
+| 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"            |
+
+---
+
+## Skill Pattern Inheritance
+
+The Tribunal Agent Kit supports 5 standard Agent Design Kit (ADK) base patterns.
+To build a skill using a robust, tested agent behavior model, add `pattern: [pattern-name]` to the YAML frontmatter of your `SKILL.md`.
+
+| Pattern          | Value                   | When to use                                                                       |
+| ---------------- | ----------------------- | --------------------------------------------------------------------------------- |
+| **Inversion**    | `pattern: inversion`    | Forces the agent to interview the user (Socratic Gate) before acting.             |
+| **Reviewer**     | `pattern: reviewer`     | Evaluates artifacts against a checklist and severity levels.                      |
+| **Tool Wrapper** | `pattern: tool-wrapper` | Strictly executes external CLI tools via provided documentation without guessing. |
+| **Generator**    | `pattern: generator`    | Produces structured output (docs, boilerplate) by filling a rigid template.       |
+| **Pipeline**     | `pattern: pipeline`     | Executes sequential tasks with strict halting gates between steps.                |
+
+_Templates defining the specific rules for these patterns live in `.agent/patterns/`._
+
+---
+
+## README Template
+
+```markdown
+# Project Name
+
+One sentence: what this is and what problem it solves.
+
+## Quick Start
+
+\`\`\`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]
+
+## Project Structure
+
+\`\`\`
+src/
+api/ API routes
+lib/ Shared utilities
+services/ Business logic
+\`\`\`
+
+## Environment Variables
+
+| Variable     | Required | Description                  |
+| ------------ | -------- | ---------------------------- |
+| DATABASE_URL | Yes      | PostgreSQL connection string |
+| JWT_SECRET   | Yes      | Secret for signing JWTs      |
+
+## Running Tests
+
+\`\`\`bash
+npm test # unit tests
+npm run test:e2e # end-to-end tests
+\`\`\`
+
+## Contributing
+
+[Brief contribution guide or link to CONTRIBUTING.md]
+```
+
+---
+
+## API Documentation Standards
+
+For each endpoint, document:
+
+```markdown
+### 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"}'
+\`\`\`
+```
+
+---
+
+## Code Comment Rules
+
+**Comment the why, not the what:**
+
+```ts
+// ❌ States what the code does (obvious from reading it)
+// Multiply price by tax rate
+const total = price * taxRate;
+
+// ✅ 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.1;
+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
+
+---
+
+## AI-Friendly Documentation
+
+When a codebase will be worked on by AI assistants:
+
+- 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
+
+---
+
+## Runbook Template
+
+```markdown
+# Runbook: [Service or Incident Type]
+
+## Symptoms
+
+- [What the user or monitor reports]
+
+## Likely Causes
+
+1. [Most common cause]
+2. [Second most common]
+
+## Investigation Steps
+
+\`\`\`bash
+
+# Check service health
+
+kubectl get pods -n production
+
+# Check recent errors
+
+kubectl logs deployment/api --since=15m | grep ERROR
+\`\`\`
+
+## Resolution Steps
+
+### If Cause 1:
+
+[Exact steps to resolve]
+
+### If Cause 2:
+
+[Exact steps to resolve]
+
+## Escalation
+
+If unresolved after 30 minutes → page @on-call-lead
+
+## Post-Incident
+
+[ ] Write incident report
+[ ] Add monitoring for this failure mode
+[ ] Update this runbook if steps changed
+```
+
+---
+
+## Output Format
+
+When this skill completes a task, structure your output as:
+
+```
+━━━ 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]
+```

package/.agent/skills/domain-modeling/SKILL.md

@@ -1,61 +1,61 @@
----
-name: domain-modeling
-description: "Use when Builds and sharpens project domain models, ubiquitous language, entity relationships, and bounded contexts before writing code."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - architecture
-  - codebase-design
-  - database-design
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Domain Modeling — Ubiquitous Language & Bounded Contexts
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
----
-
-## 4 Domain Modeling Rules
-
-### 1. Establish Ubiquitous Language
-
-- Agree on strict, unambiguous terms used identically across domain experts, code variable names, database tables, and UI copy.
-  - ❌ _User_, _Account_, _Member_, _Client_ used interchangeably for the same concept.
-  - ✅ Define 1 clear term: **Customer** (for billing context) vs **User** (for authentication context).
-
-### 2. Define Bounded Contexts
-
-- Separate large systems into distinct bounded contexts. An entity named `Product` in the _Inventory Context_ (stock level, warehouse bin) has different attributes than `Product` in the _Catalog Context_ (hero image, pricing).
-
-### 3. Aggregates & Invariants
-
-- An **Aggregate Root** (e.g. `Order`) enforces internal business invariants across child entities (`OrderItem`).
-- Never mutate a child entity (`OrderItem`) directly without passing through the aggregate root method (`order.addItem(product, qty)`).
-
-### 4. Value Objects Over Primitives
-
-- Wrap primitives into type-safe Value Objects to enforce validation logic:
-
-```typescript
-// Value Object enforcing domain rule
-export class EmailAddress {
-  private readonly value: string;
-
-  constructor(email: string) {
-    if (!email.includes('@')) throw new Error('Invalid email domain');
-    this.value = email.toLowerCase().trim();
-  }
-
-  public toString(): string {
-    return this.value;
-  }
-}
-```
+---
+name: domain-modeling
+description: "Use when Builds and sharpens project domain models, ubiquitous language, entity relationships, and bounded contexts before writing code."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - architecture
+  - codebase-design
+  - database-design
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Domain Modeling — Ubiquitous Language & Bounded Contexts
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+---
+
+## 4 Domain Modeling Rules
+
+### 1. Establish Ubiquitous Language
+
+- Agree on strict, unambiguous terms used identically across domain experts, code variable names, database tables, and UI copy.
+  - ❌ _User_, _Account_, _Member_, _Client_ used interchangeably for the same concept.
+  - ✅ Define 1 clear term: **Customer** (for billing context) vs **User** (for authentication context).
+
+### 2. Define Bounded Contexts
+
+- Separate large systems into distinct bounded contexts. An entity named `Product` in the _Inventory Context_ (stock level, warehouse bin) has different attributes than `Product` in the _Catalog Context_ (hero image, pricing).
+
+### 3. Aggregates & Invariants
+
+- An **Aggregate Root** (e.g. `Order`) enforces internal business invariants across child entities (`OrderItem`).
+- Never mutate a child entity (`OrderItem`) directly without passing through the aggregate root method (`order.addItem(product, qty)`).
+
+### 4. Value Objects Over Primitives
+
+- Wrap primitives into type-safe Value Objects to enforce validation logic:
+
+```typescript
+// Value Object enforcing domain rule
+export class EmailAddress {
+  private readonly value: string;
+
+  constructor(email: string) {
+    if (!email.includes('@')) throw new Error('Invalid email domain');
+    this.value = email.toLowerCase().trim();
+  }
+
+  public toString(): string {
+    return this.value;
+  }
+}
+```