tribunal-kit 4.5.0 → 4.6.0

package/.agent/agents/swarm-worker-contracts.md

@@ -1,166 +1,170 @@
-# 📋 Swarm Worker Contracts
-
-Defines the strict JSON schemas for all Swarm dispatch and result payloads.
-Every `WorkerRequest` and `WorkerResult` MUST conform to these schemas.
-Used by: `supervisor-agent`, `swarm_dispatcher.js`, `/swarm` workflow.
-
----
-
-## WorkerRequest Schema
-
-Emitted by the **Supervisor Agent** when dispatching a sub-task to a Worker.
-
-```typescript
-interface WorkerRequest {
-  // Unique identifier for correlating dispatches to results.
-  // Format: standard UUID v4 (randomly generated per invocation).
-  task_id: string;
-
-  // The category of work being requested.
-  type:
-    | "research"       // Understand or explain something
-    | "generate_code"  // Write new code
-    | "review_code"    // Audit existing code
-    | "debug"          // Find and fix a bug
-    | "plan"           // Produce a structured plan only (no code)
-    | "design_schema"  // Design a database or data schema
-    | "write_docs"     // Write documentation or comments
-    | "security_audit" // OWASP security review
-    | "optimize"       // Refactor for performance
-    | "test";          // Write or run tests
-
-  // The agent to route this WorkerRequest to.
-  // MUST match a filename in .agent/agents/ (without the .md extension).
-  agent: string;
-
-  // Single-sentence description of the task.
-  // MUST be specific and self-contained.
-  // ❌ "Handle the API"
-  // ✅ "Create a POST /users endpoint in Express that validates the request body"
-  goal: string;
-
-  // Minimal context the Worker requires to complete the goal.
-  // MUST NOT include: full file contents, entire conversation history, unrelated code.
-  // MUST include: relevant package versions, existing patterns, specific constraints.
-  context: string;
-
-  // Maximum number of retry attempts on failure, including the first attempt.
-  // Minimum: 1. Maximum: 3. Default: 3.
-  max_retries: number;
-}
-```
-
-### WorkerRequest Validation Rules
-
-|Field|Rules|
-|---|---|
-|`task_id`|Non-empty string. UUID v4 format preferred. Must be unique per swarm invocation.|
-|`type`|Must be one of the 10 listed enum values exactly.|
-|`agent`|Must match a file that exists at `.agent/agents/{agent}.md`.|
-|`goal`|Non-empty. Single sentence. Max 200 characters.|
-|`context`|Non-empty. Max 800 characters. No full file dumps.|
-|`max_retries`|Integer 1–3 inclusive.|
-
----
-
-## WorkerResult Schema
-
-Emitted by the **Worker Agent** (or Supervisor on behalf of a failed Worker) after completing or failing a task.
-
-```typescript
-interface WorkerResult {
-  // Must match the task_id from the originating WorkerRequest.
-  task_id: string;
-
-  // The agent that processed this request.
-  agent: string;
-
-  // Outcome of the Worker's execution.
-  status:
-    | "success"   // Task completed. Output is valid.
-    | "failure"   // Task failed but retries remain.
-    | "escalate"; // Task failed after max_retries. Requires human intervention.
-
-  // The agent's output if status is "success".
-  // Empty string if status is "failure" or "escalate".
-  output: string;
-
-  // Error message if status is "failure" or "escalate".
-  // MUST be specific — never just "Something went wrong."
-  // Empty string if status is "success".
-  error: string;
-
-  // Number of attempts made so far, including the current one.
-  // Starts at 1. Never exceeds max_retries from the WorkerRequest.
-  attempts: number;
-}
-```
-
-### WorkerResult Validation Rules
-
-|Field|Rules|
-|---|---|
-|`task_id`|Must match a previously dispatched WorkerRequest task_id.|
-|`agent`|Must match the agent from the originating WorkerRequest.|
-|`status`|Must be exactly: `"success"`, `"failure"`, or `"escalate"`.|
-|`output`|Required if status is `"success"`. Empty string otherwise.|
-|`error`|Required if status is `"failure"` or `"escalate"`. Empty string if success.|
-|`attempts`|Integer ≥ 1. Must not exceed `max_retries` from the WorkerRequest.|
-
----
-
-## Example: Successful Dispatch/Result Pair
-
-**WorkerRequest:**
-```json
-{
-  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-  "type": "generate_code",
-  "agent": "backend-specialist",
-  "goal": "Write an Express POST /users endpoint with zod body validation",
-  "context": "Express v4, zod v3.22. Body: { name: string, email: string }. Return 201 on success, 400 on validation failure.",
-  "max_retries": 3
-}
-```
-
-**WorkerResult:**
-```json
-{
-  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-  "agent": "backend-specialist",
-  "status": "success",
-  "output": "// ... generated code ...",
-  "error": "",
-  "attempts": 1
-}
-```
-
----
-
-## Example: Escalated Failure
-
-**WorkerResult:**
-```json
-{
-  "task_id": "b6a921c9-aa4e-4d1a-9862-d3f0b0e3f101",
-  "agent": "database-architect",
-  "status": "escalate",
-  "output": "",
-  "error": "Cannot infer schema without knowing whether PostgreSQL or MySQL is the target. Context is ambiguous.",
-  "attempts": 3
-}
-```
-
----
-
-## swarm_dispatcher.js Integration
-
-The `swarm_dispatcher.js` script validates **WorkerRequest** payloads before dispatch.
-
-**Usage:**
-```bash
-node .agent/scripts/swarm_dispatcher.js --mode swarm --file worker_request.json
-node .agent/scripts/swarm_dispatcher.js --mode swarm --payload '{"task_id":"...","type":"generate_code","agent":"backend-specialist","goal":"...","context":"...","max_retries":3}'
-```
-
-Exits `0` on valid payload. Exits `1` on any schema violation with a specific error message per field.
+# 📋 Swarm Worker Contracts
+
+Defines the strict JSON schemas for all Swarm dispatch and result payloads.
+Every `WorkerRequest` and `WorkerResult` MUST conform to these schemas.
+Used by: `supervisor-agent`, `swarm_dispatcher.js`, `/swarm` workflow.
+
+---
+
+## WorkerRequest Schema
+
+Emitted by the **Supervisor Agent** when dispatching a sub-task to a Worker.
+
+```typescript
+interface WorkerRequest {
+  // Unique identifier for correlating dispatches to results.
+  // Format: standard UUID v4 (randomly generated per invocation).
+  task_id: string;
+
+  // The category of work being requested.
+  type:
+    | "research" // Understand or explain something
+    | "generate_code" // Write new code
+    | "review_code" // Audit existing code
+    | "debug" // Find and fix a bug
+    | "plan" // Produce a structured plan only (no code)
+    | "design_schema" // Design a database or data schema
+    | "write_docs" // Write documentation or comments
+    | "security_audit" // OWASP security review
+    | "optimize" // Refactor for performance
+    | "test"; // Write or run tests
+
+  // The agent to route this WorkerRequest to.
+  // MUST match a filename in .agent/agents/ (without the .md extension).
+  agent: string;
+
+  // Single-sentence description of the task.
+  // MUST be specific and self-contained.
+  // ❌ "Handle the API"
+  // ✅ "Create a POST /users endpoint in Express that validates the request body"
+  goal: string;
+
+  // Minimal context the Worker requires to complete the goal.
+  // MUST NOT include: full file contents, entire conversation history, unrelated code.
+  // MUST include: relevant package versions, existing patterns, specific constraints.
+  context: string;
+
+  // Maximum number of retry attempts on failure, including the first attempt.
+  // Minimum: 1. Maximum: 3. Default: 3.
+  max_retries: number;
+}
+```
+
+### WorkerRequest Validation Rules
+
+| Field         | Rules                                                                            |
+| ------------- | -------------------------------------------------------------------------------- |
+| `task_id`     | Non-empty string. UUID v4 format preferred. Must be unique per swarm invocation. |
+| `type`        | Must be one of the 10 listed enum values exactly.                                |
+| `agent`       | Must match a file that exists at `.agent/agents/{agent}.md`.                     |
+| `goal`        | Non-empty. Single sentence. Max 200 characters.                                  |
+| `context`     | Non-empty. Max 800 characters. No full file dumps.                               |
+| `max_retries` | Integer 1–3 inclusive.                                                           |
+
+---
+
+## WorkerResult Schema
+
+Emitted by the **Worker Agent** (or Supervisor on behalf of a failed Worker) after completing or failing a task.
+
+```typescript
+interface WorkerResult {
+  // Must match the task_id from the originating WorkerRequest.
+  task_id: string;
+
+  // The agent that processed this request.
+  agent: string;
+
+  // Outcome of the Worker's execution.
+  status:
+    | "success" // Task completed. Output is valid.
+    | "failure" // Task failed but retries remain.
+    | "escalate"; // Task failed after max_retries. Requires human intervention.
+
+  // The agent's output if status is "success".
+  // Empty string if status is "failure" or "escalate".
+  output: string;
+
+  // Error message if status is "failure" or "escalate".
+  // MUST be specific — never just "Something went wrong."
+  // Empty string if status is "success".
+  error: string;
+
+  // Number of attempts made so far, including the current one.
+  // Starts at 1. Never exceeds max_retries from the WorkerRequest.
+  attempts: number;
+}
+```
+
+### WorkerResult Validation Rules
+
+| Field      | Rules                                                                       |
+| ---------- | --------------------------------------------------------------------------- |
+| `task_id`  | Must match a previously dispatched WorkerRequest task_id.                   |
+| `agent`    | Must match the agent from the originating WorkerRequest.                    |
+| `status`   | Must be exactly: `"success"`, `"failure"`, or `"escalate"`.                 |
+| `output`   | Required if status is `"success"`. Empty string otherwise.                  |
+| `error`    | Required if status is `"failure"` or `"escalate"`. Empty string if success. |
+| `attempts` | Integer ≥ 1. Must not exceed `max_retries` from the WorkerRequest.          |
+
+---
+
+## Example: Successful Dispatch/Result Pair
+
+**WorkerRequest:**
+
+```json
+{
+  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "type": "generate_code",
+  "agent": "backend-specialist",
+  "goal": "Write an Express POST /users endpoint with zod body validation",
+  "context": "Express v4, zod v3.22. Body: { name: string, email: string }. Return 201 on success, 400 on validation failure.",
+  "max_retries": 3
+}
+```
+
+**WorkerResult:**
+
+```json
+{
+  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+  "agent": "backend-specialist",
+  "status": "success",
+  "output": "// ... generated code ...",
+  "error": "",
+  "attempts": 1
+}
+```
+
+---
+
+## Example: Escalated Failure
+
+**WorkerResult:**
+
+```json
+{
+  "task_id": "b6a921c9-aa4e-4d1a-9862-d3f0b0e3f101",
+  "agent": "database-architect",
+  "status": "escalate",
+  "output": "",
+  "error": "Cannot infer schema without knowing whether PostgreSQL or MySQL is the target. Context is ambiguous.",
+  "attempts": 3
+}
+```
+
+---
+
+## swarm_dispatcher.js Integration
+
+The `swarm_dispatcher.js` script validates **WorkerRequest** payloads before dispatch.
+
+**Usage:**
+
+```bash
+node .agent/scripts/swarm_dispatcher.js --mode swarm --file worker_request.json
+node .agent/scripts/swarm_dispatcher.js --mode swarm --payload '{"task_id":"...","type":"generate_code","agent":"backend-specialist","goal":"...","context":"...","max_retries":3}'
+```
+
+Exits `0` on valid payload. Exits `1` on any schema violation with a specific error message per field.

package/.agent/agents/swarm-worker-registry.md

@@ -1,92 +1,92 @@
-# 🗂️ Swarm Worker Registry
-
-Maps task types and domain keywords to the correct specialist Worker agents.
-Used by `supervisor-agent` to select the correct `agent` field in every `WorkerRequest`.
-All agents listed here MUST exist as `.md` files in `.agent/agents/`.
-
----
-
-## Primary Routing Table
-
-|Task Type|Domain Keywords|Route to Agent|
-|---|---|---|
-|`research`|any|`explorer-agent`|
-|`research`|security, vulnerability, owasp|`security-auditor`|
-|`research`|database, schema, sql, orm|`database-architect`|
-|`research`|performance, profiling, optimization|`performance-optimizer`|
-|`generate_code`|api, route, endpoint, server, express, auth, jwt|`backend-specialist`|
-|`generate_code`|python, fastapi, django, flask|`python-pro`|
-|`generate_code`|c#, .net, blazor, aspnet|`dotnet-core-expert`|
-|`generate_code`|component, hook, react, next, ui, css|`frontend-specialist`|
-|`generate_code`|mobile, react native, flutter, ios, android|`mobile-developer`|
-|`generate_code`|docker, ci, cd, deploy, github actions, cloud|`devops-engineer`|
-|`generate_code`|sql, query, migration, prisma, drizzle|`sql-pro`|
-|`generate_code`|vue, nuxt|`vue-expert`|
-|`review_code`|api, backend, auth|`backend-specialist`|
-|`review_code`|react, component, hook|`frontend-specialist`|
-|`review_code`|sql, query|`sql-pro`|
-|`review_code`|security (any domain)|`security-auditor`|
-|`debug`|any|`debugger`|
-|`plan`|any|`project-planner`|
-|`design_schema`|any|`database-architect`|
-|`write_docs`|any|`documentation-writer`|
-|`security_audit`|any|`security-auditor`|
-|`optimize`|any|`performance-optimizer`|
-|`test`|any|`test-engineer`|
-
----
-
-## Tiebreaker Rules
-
-When multiple domain keywords match, apply the following priority order:
-
-1. **Most specific agent wins.** `sql-pro` beats `database-architect` for SQL query generation. `react-specialist` beats `frontend-specialist` for advanced React architecture.
-2. **Security always runs in parallel.** Even if the primary agent is `backend-specialist`, flag security-sensitive tasks to also route through `security-auditor` as a parallel reviewer.
-3. **When in doubt, use `explorer-agent` first.** If the codebase is unknown, map it before generating.
-
----
-
-## Agent Capability Summary
-
-Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
-
-|Agent File|Best For|Do NOT Use For|
-|---|---|---|
-|`backend-specialist.md`|REST APIs, auth flows, server logic|React components|
-|`python-pro.md`|FastAPI, Django, data scripts|Node/TypeScript code|
-|`dotnet-core-expert.md`|.NET 8+, C#, Blazor, AOT|Python or Node backends|
-|`frontend-specialist.md`|Web UI, CSS, components|Server code|
-|`react-specialist.md`|Advanced React patterns, Next.js architecture|Vue or mobile|
-|`vue-expert.md`|Vue 3, Nuxt 3, Pinia|React or Angular|
-|`mobile-developer.md`|React Native, Flutter|Web browser UI|
-|`database-architect.md`|Schema design, ORM selection, migrations|Raw SQL query tuning|
-|`sql-pro.md`|Complex queries, CTEs, window functions, indexes|Schema design|
-|`devops-engineer.md`|CI/CD, Docker, Kubernetes, cloud infra|Application code|
-|`security-auditor.md`|OWASP review, pen test findings, auth hardening|Feature development|
-|`performance-optimizer.md`|Profiling, bottleneck resolution, caching|New feature design|
-|`debugger.md`|Root cause analysis, systematic issue isolation|Code generation|
-|`project-planner.md`|Planning, task breakdown, estimates|Implementation|
-|`documentation-writer.md`|READMEs, API docs, inline comments|Code or schemas|
-|`test-engineer.md`|Unit/integration test design and strategy|Production code|
-|`explorer-agent.md`|Mapping unknown codebases before acting|Building new features|
-
----
-
-## Hard Constraints
-
-```
-❌ Never route to an agent not listed in this registry
-❌ Never route "generate_code" to "project-planner" or "documentation-writer"
-❌ Never route "plan" to any code-generating agent
-❌ Never route multi-domain tasks to a single agent — split into multiple WorkerRequests
-```
-
----
-
-## Adding New Workers
-
-When a new specialist agent is added to `.agent/agents/`, update this registry:
-
-1. Add a row to the **Primary Routing Table** for each `type` and keyword combination it handles
-2. Add a row to the **Agent Capability Summary** with "Best For" and "Do NOT Use For" guidance
-3. Run `python .agent/scripts/config-validator.py` to verify consistency
+# 🗂️ Swarm Worker Registry
+
+Maps task types and domain keywords to the correct specialist Worker agents.
+Used by `supervisor-agent` to select the correct `agent` field in every `WorkerRequest`.
+All agents listed here MUST exist as `.md` files in `.agent/agents/`.
+
+---
+
+## Primary Routing Table
+
+| Task Type        | Domain Keywords                                  | Route to Agent          |
+| ---------------- | ------------------------------------------------ | ----------------------- |
+| `research`       | any                                              | `explorer-agent`        |
+| `research`       | security, vulnerability, owasp                   | `security-auditor`      |
+| `research`       | database, schema, sql, orm                       | `database-architect`    |
+| `research`       | performance, profiling, optimization             | `performance-optimizer` |
+| `generate_code`  | api, route, endpoint, server, express, auth, jwt | `backend-specialist`    |
+| `generate_code`  | python, fastapi, django, flask                   | `python-pro`            |
+| `generate_code`  | c#, .net, blazor, aspnet                         | `dotnet-core-expert`    |
+| `generate_code`  | component, hook, react, next, ui, css            | `frontend-specialist`   |
+| `generate_code`  | mobile, react native, flutter, ios, android      | `mobile-developer`      |
+| `generate_code`  | docker, ci, cd, deploy, github actions, cloud    | `devops-engineer`       |
+| `generate_code`  | sql, query, migration, prisma, drizzle           | `sql-pro`               |
+| `generate_code`  | vue, nuxt                                        | `vue-expert`            |
+| `review_code`    | api, backend, auth                               | `backend-specialist`    |
+| `review_code`    | react, component, hook                           | `frontend-specialist`   |
+| `review_code`    | sql, query                                       | `sql-pro`               |
+| `review_code`    | security (any domain)                            | `security-auditor`      |
+| `debug`          | any                                              | `debugger`              |
+| `plan`           | any                                              | `project-planner`       |
+| `design_schema`  | any                                              | `database-architect`    |
+| `write_docs`     | any                                              | `documentation-writer`  |
+| `security_audit` | any                                              | `security-auditor`      |
+| `optimize`       | any                                              | `performance-optimizer` |
+| `test`           | any                                              | `test-engineer`         |
+
+---
+
+## Tiebreaker Rules
+
+When multiple domain keywords match, apply the following priority order:
+
+1. **Most specific agent wins.** `sql-pro` beats `database-architect` for SQL query generation. `react-specialist` beats `frontend-specialist` for advanced React architecture.
+2. **Security always runs in parallel.** Even if the primary agent is `backend-specialist`, flag security-sensitive tasks to also route through `security-auditor` as a parallel reviewer.
+3. **When in doubt, use `explorer-agent` first.** If the codebase is unknown, map it before generating.
+
+---
+
+## Agent Capability Summary
+
+Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
+
+| Agent File                 | Best For                                         | Do NOT Use For          |
+| -------------------------- | ------------------------------------------------ | ----------------------- |
+| `backend-specialist.md`    | REST APIs, auth flows, server logic              | React components        |
+| `python-pro.md`            | FastAPI, Django, data scripts                    | Node/TypeScript code    |
+| `dotnet-core-expert.md`    | .NET 8+, C#, Blazor, AOT                         | Python or Node backends |
+| `frontend-specialist.md`   | Web UI, CSS, components                          | Server code             |
+| `react-specialist.md`      | Advanced React patterns, Next.js architecture    | Vue or mobile           |
+| `vue-expert.md`            | Vue 3, Nuxt 3, Pinia                             | React or Angular        |
+| `mobile-developer.md`      | React Native, Flutter                            | Web browser UI          |
+| `database-architect.md`    | Schema design, ORM selection, migrations         | Raw SQL query tuning    |
+| `sql-pro.md`               | Complex queries, CTEs, window functions, indexes | Schema design           |
+| `devops-engineer.md`       | CI/CD, Docker, Kubernetes, cloud infra           | Application code        |
+| `security-auditor.md`      | OWASP review, pen test findings, auth hardening  | Feature development     |
+| `performance-optimizer.md` | Profiling, bottleneck resolution, caching        | New feature design      |
+| `debugger.md`              | Root cause analysis, systematic issue isolation  | Code generation         |
+| `project-planner.md`       | Planning, task breakdown, estimates              | Implementation          |
+| `documentation-writer.md`  | READMEs, API docs, inline comments               | Code or schemas         |
+| `test-engineer.md`         | Unit/integration test design and strategy        | Production code         |
+| `explorer-agent.md`        | Mapping unknown codebases before acting          | Building new features   |
+
+---
+
+## Hard Constraints
+
+```
+❌ Never route to an agent not listed in this registry
+❌ Never route "generate_code" to "project-planner" or "documentation-writer"
+❌ Never route "plan" to any code-generating agent
+❌ Never route multi-domain tasks to a single agent — split into multiple WorkerRequests
+```
+
+---
+
+## Adding New Workers
+
+When a new specialist agent is added to `.agent/agents/`, update this registry:
+
+1. Add a row to the **Primary Routing Table** for each `type` and keyword combination it handles
+2. Add a row to the **Agent Capability Summary** with "Best For" and "Do NOT Use For" guidance
+3. Run `python .agent/scripts/config-validator.py` to verify consistency

package/.agent/agents/system-architect.md

@@ -0,0 +1,85 @@
+# System Architect Agent
+
+## Role
+
+You are a **System Architect** — a specialist in large-scale distributed system design. You are activated when the task requires reasoning about system capacity, scalability, architecture decisions, or designing systems from scratch.
+
+## Primary Skills
+
+- `system-design-pro` ← Load this first for all system design tasks
+- `architecture` ← Load for clean architecture, DDD, ADRs, and micro vs monolith decisions
+
+## Activation Triggers
+
+You are routed here when the request contains:
+
+- "design a system for..."
+- "how would you architect..."
+- "scale this to N users"
+- "capacity planning"
+- "handle N requests per second"
+- "distributed system"
+- "high availability"
+- "fault tolerant"
+- "system design interview"
+- "what database should I use for..."
+- "CAP theorem"
+- "load balancing strategy"
+
+## Mandatory Pre-Work
+
+Before generating any design, you MUST:
+
+1. **Establish scale numbers** — Ask for or estimate DAU, QPS (read/write), storage growth, latency requirements
+2. **Clarify scope** — What features are in this design? What is explicitly OUT of scope?
+3. **Confirm consistency needs** — Is eventual consistency OK or does this require strong consistency?
+
+**Never design a system without these numbers. Scale determines every architectural decision.**
+
+## Output Format
+
+```
+## System: [Name]
+
+### Scale Estimates
+- DAU: [N]
+- Read QPS: [N]  |  Write QPS: [N]
+- Storage: [N GB/TB] / year
+
+### API Design
+[Core endpoints]
+
+### Data Model
+[Core entities + key fields]
+
+### High-Level Architecture
+[Diagram or component list]
+
+### Bottleneck Analysis
+- Primary bottleneck: [component]
+- Scaling strategy: [approach]
+- Failure mode: [what breaks] → Mitigation: [fix]
+```
+
+## Hallucination Guard
+
+```
+❌ Never design microservices for <10K QPS without explicit justification
+❌ Never recommend sharding before connection pooling + read replicas
+❌ Never choose NoSQL without explaining the tradeoff on ACID/queries
+❌ Never skip scale estimation — no design is architecture-agnostic
+```
+
+## Socratic Gate (Required for Complex Requests)
+
+For vague requests like "design Instagram," ask before designing:
+
+1. What scale? (DAU, geography)
+2. What features are IN SCOPE for this session? (just the feed? or also DMs, stories?)
+3. What's the consistency requirement for the feed? (eventual OK?)
+4. Is there an existing system or is this greenfield?
+
+## Coordination
+
+When the design requires implementation details on cloud/infra, hand off to `@cloud-engineer`.
+When the design requires database-specific deep dives, hand off to `@database-architect`.