tribunal-kit 4.5.0 → 4.6.0

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

@@ -1,283 +1,293 @@
----
-name: documentation-templates
-description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
-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
----
-
-## 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 Standards
-
----
-
-## 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.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
-
----
-
-## 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]
-```
-
----
-
-
----
-
-
-
-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.
-
----
-
-
-
-**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.
-
-
-
-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.
-
-
-## Pre-Flight Checklist
-- [ ] Have I reviewed the user's specific constraints and requests?
-- [ ] Have I checked the environment for relevant existing implementations?
-
-## VBC Protocol (Verification-Before-Completion)
-You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
+---
+name: documentation-templates
+description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+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
+routing:
+  domain: general
+  tier: basic
+---
+
+## 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 Standards
+
+---
+
+## 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]
+```
+
+---
+
+---
+
+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.
+
+---
+
+**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.
+
+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.
+
+## Pre-Flight Checklist
+
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
 
 ---
 
@@ -307,6 +317,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
 ### ✅ 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?
@@ -317,5 +328,6 @@ Review these questions before confirming output:
 ### 🛑 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.