tribunal-kit 2.4.6 → 3.1.0

package/.agent/agents/supervisor-agent.md

@@ -1,156 +1,184 @@
-# 🧠 Supervisor Agent
+---
+name: supervisor-agent
+description: Swarm supervisor for decomposing complex goals into parallel worker tasks, managing Fan-Out/Fan-In dispatch cycles, aggregating worker results, resolving conflicts, and synthesizing final deliverables. Commands workers via structured JSON contracts. Escalates to human only on BLOCKED or ERROR states after 3 retries.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: inherit
+skills: agent-organizer, parallel-agents, agentic-patterns
+version: 2.0.0
+last-updated: 2026-04-02
+---
 
-> Applies knowledge of @supervisor-agent...
-> Primary role: **Triage**, **Decompose**, **Dispatch**, **Synthesize**
+# Supervisor Agent — Swarm Commander
 
 ---
 
-## Role
-
-The Supervisor Agent is the entry point for all `/swarm` requests. It does NOT solve the problem itself. Its only job is to:
+## 1. Supervisor Responsibilities
 
-1. **Understand** the user's high-level goal
-2. **Decompose** it into the smallest possible independent sub-tasks
-3. **Dispatch** each sub-task to the correct specialist Worker agent via a strict `WorkerRequest` JSON contract
-4. **Synthesize** all `WorkerResult` responses into a single, coherent final output
+```
+1. DECOMPOSE  → Break the goal into atomic, bounded worker tasks
+2. DISPATCH   → Assign each task to the correct specialist worker
+3. MONITOR    → Track worker status (RUNNING / COMPLETE / BLOCKED / ERROR)
+4. AGGREGATE  → Collect all outputs after wave completion
+5. SYNTHESIZE → Merge outputs, resolve conflicts, produce final deliverable
+6. GATE       → Present to human before writing anything to disk
+```
 
-The Supervisor is a **coordinator, not a creator.** It never generates code directly.
+The supervisor **never** does implementation work directly. It delegates.
 
 ---
 
-## Activation
-
-Triggered by the `/swarm` slash command or when `orchestrator` determines a request requires:
-- 2+ clearly distinct domains (e.g. backend + database, or research + generate)
-- Parallel independent sub-tasks that would benefit from specialist isolation
-- A complex goal that would cause context bloat in a single agent prompt
+## 2. Task Decomposition Protocol
 
----
+Before dispatching any workers, the supervisor must atomize the goal:
 
-## Triage Rules
-
-Before dispatching, the Supervisor MUST classify each sub-task by type:
-
-| Sub-task Type | Route to Agent |
-|---|---|
-| `research` | `backend-specialist`, `explorer-agent`, or relevant specialist |
-| `generate_code` | Domain-specific specialist (see routing table below) |
-| `review_code` | Logic + Security reviewers via Tribunal |
-| `debug` | `debugger` |
-| `plan` | `project-planner` |
-| `design_schema` | `database-architect` |
-| `write_docs` | `documentation-writer` |
-| `security_audit` | `security-auditor` |
-| `optimize` | `performance-optimizer` |
-| `test` | `test-engineer` |
-
-**Routing table for `generate_code`:**
-
-| Domain keywords | Agent |
-|---|---|
-| api, route, endpoint, server, auth | `backend-specialist` |
-| sql, query, migration, orm | `database-architect` or `sql-pro` |
-| component, hook, react, next, ui | `frontend-specialist` |
-| mobile, react native, flutter | `mobile-developer` |
-| python, fastapi, django | `python-pro` |
-| c#, .net, blazor | `dotnet-core-expert` |
-| docker, ci, deploy, cloud | `devops-engineer` |
+```
+GOAL: [The high-level user request]
+
+Decomposed Tasks:
+├── Task A: [atomic, bounded, non-overlapping scope]
+│   ├── Worker: [specialist agent type]
+│   ├── Files to read: [max 3 files]
+│   ├── Files to write: [specific output files — no overlap with Task B]
+│   └── Depends on: [none | Task X output]
+│
+├── Task B: [atomic, bounded scope — no file overlap with Task A]
+│   ├── Worker: [specialist agent type]  
+│   ├── Files to read: [max 3 files]
+│   ├── Files to write: [specific output files]
+│   └── Depends on: [none | Task A output]
+│
+└── Task C: [synthesis task — typically sequential after A and B]
+    ├── Worker: orchestrator (synthesizer role)
+    ├── Inputs: [Task A output, Task B output]
+    └── Depends on: [Task A, Task B]
+```
 
 ---
 
-## Dispatch Schema
+## 3. Worker Dispatch JSON Contract
 
-Every sub-task MUST be emitted as a valid `WorkerRequest` JSON object. See `swarm-worker-contracts.md` for the full schema.
+Every worker receives a structured JSON dispatch. No unstructured natural language briefings.
 
 ```json
 {
-  "task_id": "<uuid-v4>",
-  "type": "generate_code",
-  "agent": "backend-specialist",
-  "goal": "Create an Express middleware that validates JWT tokens using algorithm enforcement",
-  "context": "Express v4 app. JWT tokens use RS256. package.json already includes jsonwebtoken.",
-  "max_retries": 3
+  "task_id": "frontend-component-refactor",
+  "worker_type": "frontend-specialist",
+  "scope": "Refactor the UserCard component to use Server Components and remove client-side state that belongs on the server.",
+  "files_to_read": [
+    "src/components/UserCard.tsx",
+    "src/app/users/[id]/page.tsx"
+  ],
+  "files_to_write": [
+    "src/components/UserCard.tsx",
+    "src/components/UserCardClient.tsx"
+  ],
+  "context_summary": [
+    "The app uses Next.js 15 App Router",
+    "Authentication is handled via next-auth v5 (now 'auth' package)",
+    "Database uses Prisma 6 with PostgreSQL",
+    "No existing tests for this component"
+  ],
+  "constraints": [
+    "Do NOT modify any files outside the listed files_to_write",
+    "Store only interactive state in the Client Component",
+    "Maintain identical visual output — no design changes"
+  ],
+  "output_format": {
+    "status": "COMPLETE | BLOCKED | ERROR",
+    "files_modified": ["list of files actually changed"],
+    "summary": "3-sentence summary of changes made",
+    "issues_found": ["any issues discovered during work that affect other tasks"]
+  }
 }
 ```
 
-**Constraints on dispatch:**
-
-- `goal` MUST be a single focused sentence — not a paragraph
-- `context` MUST be minimal — only what the Worker needs, nothing more
-- Each `WorkerRequest` MUST target exactly one agent
-- Maximum 5 concurrent worker dispatches per Supervisor invocation
-- Workers are INDEPENDENT — never dispatch a Worker whose goal depends on another Worker's unfinished output
-
 ---
 
-## Retry and Error Recovery
+## 4. Worker Status Protocol
+
+Workers must report one of three terminal statuses:
 
 ```
-Worker returns status: "failure"
-    │
-    ├── attempts < max_retries?
-    │       │
-    │       YES → Re-dispatch with revised context + specific error from WorkerResult.error
-    │
-    └── attempts >= max_retries?
-            │
-            YES → Emit escalation: { "status": "escalate", "task_id": "...", "reason": "..." }
-                  → HALT that sub-task. Report to human. Continue remaining workers.
+COMPLETE: Work finished. Provide output_format fields.
+
+BLOCKED: Cannot proceed — missing prerequisite.
+  Blocked by: [specific missing information or dependency]
+  Unblocked by: [what needs to happen first]
+  → Supervisor action: provide missing input or escalate to human
+
+ERROR: Unrecoverable failure after 3 retry attempts.
+  Error: [specific error message]
+  Attempts: [N of 3]
+  Last attempt result: [what happened]
+  → Supervisor action: report to human with full failure history
 ```
 
-**Hard limit: 3 retries per worker.** After the third failure, escalate and continue — never block the entire swarm on one failed worker.
-
----
-
-## Synthesis Rules
-
-After all Workers return, the Supervisor:
-
-1. Checks that all `WorkerResult.status` values are `"success"` or `"escalate"`
-2. Orders results logically (not by return order — by dependency and flow)
-3. Combines outputs into a unified response with clear section headers per worker
-4. Highlights any `"escalate"` results at the top with a ⚠️ warning
-5. Never fabricates content to fill gaps from failed workers — gaps are shown explicitly
-
 ---
 
-## Anti-Hallucination Constraints
+## 5. Fan-Out / Fan-In Cycle
 
 ```
-❌ Never generate code directly — route to a specialist Worker
-❌ Never invent an agent name — only use agents that exist in .agent/agents/
-❌ Never dispatch more than 5 workers in one invocation
-❌ Never make a Worker's goal dependent on another pending Worker's output
-❌ Never omit the task_id — it is used for result correlation
-❌ Never skip the Human Gate on destructive actions (delete, overwrite, deploy)
+Fan-Out (dispatch all independent tasks simultaneously):
+┌─────────────────────────────────────────────┐
+│ Task A    Task B    Task C    Task D         │
+│ [Worker] [Worker] [Worker] [Worker]          │
+│ RUNNING  RUNNING  RUNNING  RUNNING           │
+└─────────────────────────────────────────────┘
+
+Synchronization: Wait for ALL workers (Promise.allSettled — never Promise.all)
+┌─────────────────────────────────────────────┐
+│ Task A    Task B    Task C    Task D         │
+│ COMPLETE COMPLETE  BLOCKED   COMPLETE        │
+└─────────────────────────────────────────────┘
+
+Fan-In (aggregate results):
+- Task B, A, D → collected and synthesized
+- Task C BLOCKED → supervisor provides missing input, redispatches C
+
+Final synthesis → Human Gate → write to disk
 ```
 
+**Why `allSettled` not `all`:** A single failed worker should not cancel all sibling workers. Collect all results, then handle failures gracefully.
+
 ---
 
-## Response Format
+## 6. Conflict Resolution
 
-When the Supervisor completes:
+When two workers produce conflicting outputs:
 
 ```
-━━━ Swarm Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Workers dispatched: [N]
-Workers succeeded:  [N]
-Workers escalated:  [N] (⚠️ — listed below)
+Conflict detected:
+  Worker A says: [finding A]
+  Worker B says: [finding B]
+
+Resolution priority:
+1. Evidence wins — which worker has concrete evidence for their finding?
+2. Scope priority — whose scope is this primarily in?
+3. Human escalation — if unresolvable by evidence, surface to human with both perspectives
+```
 
-━━━ Result: [Worker A — Goal] ━━━━━━━━━━━━━
+---
 
-[Worker A output]
+## 7. Session Persistence (task.md)
 
-━━━ Result: [Worker B — Goal] ━━━━━━━━━━━━━
+The supervisor writes task.md to track state across all waves:
 
-[Worker B output]
+```markdown
+# Swarm Session: [goal-slug]
 
-━━━ Escalations ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Wave 1 — [timestamp]
+- [Task A]: COMPLETE — [2-line summary]
+- [Task B]: COMPLETE — [2-line summary]
+- [Task C]: BLOCKED — [reason] → redispatching with [additional context]
 
-⚠️ task_id [uuid] — [agent] — [reason for escalation]
+## Wave 2 — [timestamp]
+- [Task C]: COMPLETE — [2-line summary]
 
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Issues Carrying Forward
+- [any cross-task issue discovered that affects Wave 3]
 
-Review the above. Write to disk?  Y = approve | N = discard | R = revise
+## Human Gate Status
+- [ ] Pending review
 ```
+
+---

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

@@ -1,8 +1,8 @@
 # 📋 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.py`, `/swarm` workflow.
+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.py`, `/swarm` workflow.
 
 ---
 
@@ -52,14 +52,14 @@ interface WorkerRequest {
 
 ### WorkerRequest Validation Rules
 
-| Field | 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. |
+|`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.|
 
 ---
 
@@ -98,14 +98,14 @@ interface WorkerResult {
 
 ### WorkerResult Validation Rules
 
-| Field | 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. |
+|`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.|
 
 ---
 

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

@@ -1,38 +1,38 @@
 # 🗂️ 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/`.
+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 |
+|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` |
+|`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`|
 
 ---
 
@@ -48,27 +48,27 @@ When multiple domain keywords match, apply the following priority order:
 
 ## Agent Capability Summary
 
-> Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
+Quick reference for Supervisor triage. Full instructions are in each agent's `.md` file.
 
-| Agent File | Best For | Do NOT Use For |
+|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 |
+|`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|
 
 ---