tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/strengthen-skills.md

@@ -1,99 +1,138 @@
 ---
-description: Strengthen skills by appending Tribunal guardrails (LLM Traps, Pre-Flight checklist, VBC Protocol) to any SKILL.md missing them.
+description: Strengthen skills by appending Tribunal guardrails (LLM Traps, Pre-Flight checklist, VBC Protocol) to any SKILL.md missing them. Reads each skill, checks for guardrails, appends if missing, skips if present.
 ---
 
-# /strengthen-skills Workflow
+# /strengthen-skills — Skill Hardening Pipeline
 
-Use this command to audit and harden all skills in `.agent/skills/` that are missing
-the standard Tribunal guardrails block.
+$ARGUMENTS
 
 ---
 
-## What It Does
+## When to Use /strengthen-skills
 
-Runs `strengthen_skills.py` against all skill files.  
-For each skill it checks:
+|Use `/strengthen-skills` when...||
+|:---|:---|
+|New skills were just created|Append guardrails|
+|Auditing existing skills|Check which are missing guardrails|
+|After adding skills from external sources|Harden before activating|
 
-1. **Tribunal Integration section** — does it have `🏛️ Tribunal Integration`?
-2. **VBC Protocol** — does it have `Verification-Before-Completion`?
+---
+
+## Phase 1 — Skill Inventory
 
-Skills missing either are strengthened by appending the full canonical block:
-- `## 🤖 LLM-Specific Traps`
-- `## 🏛️ Tribunal Integration (Anti-Hallucination)`
-  - Forbidden AI Tropes
-  - Pre-Flight Self-Audit checklist
-  - VBC Protocol
+```bash
+# Find all SKILL.md files
+find .agent/skills/ -name "SKILL.md" | sort
 
-Skills that already have both sections are skipped automatically.
+# Count total
+find .agent/skills/ -name "SKILL.md" | wc -l
+```
 
 ---
 
-## Steps
+## Phase 2 — Guardrail Check
 
-### Step 1 — Dry Run (Always First)
+For each SKILL.md, check if it already has guardrails:
 
-```powershell
-python .agent/scripts/strengthen_skills.py . --dry-run
+```bash
+# Check which skills are MISSING LLM Trap table
+grep -rL "LLM Trap\|LLM Traps\|\*\*Trap\|TRAP TABLE" .agent/skills/*/SKILL.md
+
+# Check which skills are MISSING Pre-Flight checklist
+grep -rL "Pre-Flight\|Pre-flight\|Preflight\|Self-Audit" .agent/skills/*/SKILL.md
+
+# Check which skills are MISSING VBC Protocol
+grep -rL "VBC\|Verify.*Build.*Confirm\|verify.*build.*confirm" .agent/skills/*/SKILL.md
 ```
 
-Review the output. All lines prefixed with `⚠️ [DRY RUN]` are skills that would be strengthened.
+---
 
-> **Human Gate:** If the dry-run output looks correct, continue to Step 2.
-> If unexpected skills are listed, investigate before proceeding.
+## Phase 3 — Append Guardrails (For Missing Skills Only)
 
+For each skill missing guardrails, append the three sections:
+
+```markdown
 ---
 
-### Step 2 — Strengthen All Skills
+## 🚨 LLM Trap Table
 
-```powershell
-python .agent/scripts/strengthen_skills.py .
-```
+|Pattern|What AI Does Wrong|What Is Actually Correct|
+|:---|:---|:---|
+|[domain-specific trap 1]|[hallucination]|[correct behavior]|
+|[domain-specific trap 2]|[hallucination]|[correct behavior]|
+|[domain-specific trap 3]|[hallucination]|[correct behavior]|
 
 ---
 
-### Step 3 — Verify Summary
+## ✅ Pre-Flight Self-Audit
 
-The script prints a final summary:
+Before producing any output, verify:
 ```
-✅ Strengthened: N
-⏭️  Skipped:     N
-❌ Errors:       0
+✅ Did I read the actual files before making claims about them?
+✅ Did I verify all method names against official documentation?
+✅ Did I add // VERIFY: on any uncertain API calls?
+✅ Are all imports from packages that actually exist in package.json?
+✅ Did I test my logic with edge cases (null, empty, 0, max)?
+✅ Did I avoid generating code for more than one module at a time?
+✅ Am I working from evidence, not assumption?
 ```
 
-Errors must be zero before proceeding. If any errors appear, fix them and re-run.
+---
+
+## 🔁 VBC Protocol (Verify → Build → Confirm)
+
+```
+VERIFY:  Read the actual codebase before writing anything
+BUILD:   Generate the smallest meaningful unit of code
+CONFIRM: Verify the output is correct before presenting
+```
+```
 
 ---
 
-### Step 4 — Strengthen a Single Skill (Optional)
+## Phase 4 — Report
 
-To strengthen one specific skill only:
+After processing all skills:
 
-```powershell
-python .agent/scripts/strengthen_skills.py . --skill <skill-name>
 ```
+━━━ Skill Strengthening Report ━━━━━━━━━━━━
+
+Total skills found:     [N]
+Already have guardrails: [N] (skipped)
+Guardrails added:       [N]
+Failed:                  [N]
+
+━━━ Strengthened Skills ━━━━━━━━━━━━━━━━━━
+✅ [skill-name] — LLM Trap + Pre-Flight + VBC added
 
-Example:
-```powershell
-python .agent/scripts/strengthen_skills.py . --skill brainstorming
+━━━ Already Hardened (Skipped) ━━━━━━━━━━━
+⏭️ [skill-name]
+⏭️ [skill-name]
 ```
 
 ---
 
-### Step 5 — Custom Skills Directory (Optional)
+## Guardrail Quality Guidelines
 
-If skills live in a non-standard location:
+LLM Trap tables should be domain-specific — not generic:
 
-```powershell
-python .agent/scripts/strengthen_skills.py . --skills-path /path/to/skills
 ```
+❌ Generic (useless):
+"Don't use wrong method names"
+
+✅ Specific (valuable):
+"React 19: useFormState() was renamed to useActionState(). 
+  AI generates old name — import fails at runtime."
+```
+
+The Pre-Flight checklist should match the skill's specific domain — add domain-specific checks beyond the universal ones.
 
 ---
 
-## Related Commands
+## Usage Examples
 
-| Command | Purpose |
-|---|---|
-| `/audit` | Full project health audit (includes skills review) |
-| `python .agent/scripts/patch_skills_meta.py .` | Inject version/freshness metadata into frontmatter |
-| `python .agent/scripts/patch_skills_output.py .` | Add Output Format sections to skills missing them |
-| `python .agent/scripts/config_validator.py .` | Validate all agent config consistency |
+```
+/strengthen-skills              → Check and harden all skills
+/strengthen-skills nextjs-react-expert → Harden only this skill
+/strengthen-skills --check-only → Audit without modifying
+```

package/.agent/workflows/swarm.md

@@ -1,194 +1,179 @@
 ---
-description: Multi-Agent Swarm Orchestration — Supervisor decomposes a goal into sub-tasks, dispatches to specialist Workers, collects results, and synthesizes a unified response.
+description: Multi-Agent Swarm Orchestration. Supervisor decomposes a complex goal into sub-tasks, dispatches to specialist Workers via structured JSON contracts, collects results via allSettled fan-in, and synthesizes a unified deliverable. Validates payloads via swarm_dispatcher.py before dispatch.
 ---
 
-# /swarm — Multi-Agent Swarm Orchestration
+# /swarm — Multi-Agent Swarm Execution
 
 $ARGUMENTS
 
 ---
 
-## What This Does
+## When to Use /swarm Over /orchestrate
 
-`/swarm` is for goals that are **too large or multi-domain for a single agent**.
-
-Instead of one agent trying to do everything (and hallucinating outside its expertise), the Supervisor:
-
-1. **Decomposes** your goal into independent sub-tasks
-2. **Dispatches** each sub-task to the best specialist Worker
-3. **Collects** all results
-4. **Synthesizes** a unified, coherent response
-
-Use `/swarm` when your request spans **2+ domains** (e.g., backend API + database schema + docs) or when you want specialist-quality output for each component.
+|Use `/swarm` when...|Use `/orchestrate` when...|
+|:---|:---|
+|5+ workers needed simultaneously|2-4 workers in a review|
+|Tasks are explicitly JSON-contracted|Tasks can be described informally|
+|Supervisor/Worker role separation matters|Simple coordination needed|
+|Wave execution needs session persisting across time|Single-session orchestration|
 
 ---
 
-## When to Use /swarm vs Other Commands
+## Phase 1 — Swarm Initialization
 
-| Use `/swarm` when... | Use something else when... |
-|---|---|
-| Goal spans 2+ specialist domains | Single-domain task → `/generate` |
-| You want parallel specialist output | Simple question → just ask |
-| Task needs backend + DB + docs together | Need a plan only → `/plan` |
-| Complex refactor across multiple files | Debugging one bug → `/debug` |
-| Maximum specialist coverage on large feature | Step-by-step incremental work → `/orchestrate` |
+The Supervisor agent activates and:
 
----
+1. Reads the goal and identifies all atomic sub-tasks
+2. Validates that sub-tasks don't share output files
+3. Estimates context budget per worker
+4. Writes initial state to task.md
 
-## Pipeline Flow
+---
 
+## Phase 2 — Worker Dispatch Contracts
+
+Every worker receives a structured JSON contract (not natural language):
+
+```json
+{
+  "task_id": "audit-auth-routes",
+  "worker_type": "backend-specialist",
+  "scope": "Audit all files in src/app/api/auth/ for security and type safety",
+  "files_to_read": [
+    "src/app/api/auth/login/route.ts",
+    "src/app/api/auth/register/route.ts",
+    "src/middleware.ts"
+  ],
+  "files_to_write": [],
+  "context_summary": [
+    "Next.js 15 App Router project",
+    "Auth uses next-auth v5 (auth.ts pattern)",
+    "Database: Prisma 6 on PostgreSQL"
+  ],
+  "constraints": [
+    "Report findings only — do not modify files",
+    "Report BLOCKED if you cannot determine auth pattern from provided files"
+  ],
+  "output_format": {
+    "status": "COMPLETE | BLOCKED | ERROR",
+    "findings": ["list of specific issues found with file+line references"],
+    "summary": "2-3 sentence summary"
+  }
+}
 ```
-/swarm [your goal]
-         │
-         ▼
-  supervisor-agent (triage)
-  → Reads: swarm-worker-registry.md
-  → Validates: swarm-worker-contracts.md
-  → Emits: WorkerRequest JSON (validated) for each sub-task
-         │
-         ├─── Worker 1: [agent-name] ──── WorkerResult 1
-         ├─── Worker 2: [agent-name] ──── WorkerResult 2
-         └─── Worker N: [agent-name] ──── WorkerResult N
-                                │
-                                ▼
-                       supervisor-agent (synthesize)
-                                │
-                                ▼
-                       ━━━ Swarm Complete ━━━
-                       Human Gate → Y / N / R
-```
-
-**Constraints:**
-- Maximum **5 Workers** per swarm invocation
-- Workers are **independent** — no Worker depends on another's pending result
-- Workers that fail are **retried up to 3 times** with targeted feedback
-- Workers that still fail after 3 retries are **escalated** (not silently dropped)
-- Tribunal rules apply **inside each Worker** — no invented libraries, guessed columns, or uncited calls
 
 ---
 
-## Step 1 — Supervisor Triage
+## Phase 3 — Payload Validation
 
-The `supervisor-agent` reads the goal and produces a dispatch plan.
-
-**Format:**
+Before dispatching, validate all worker contracts:
 
+```bash
+python .agent/scripts/swarm_dispatcher.py --file payload.json
 ```
-━━━ Swarm Triage ━━━━━━━━━━━━━━━━━━━━━━━━
 
-Goal: [restate the user's goal in one sentence]
+If validation passes → dispatch workers in parallel.
+If validation fails → fix payload before dispatch.
 
-Workers to dispatch: [N of max 5]
-
-Worker 1
-  task_id: [uuid]
-  type:    [generate_code | research | review_code | write_docs | analyze]
-  agent:   [agent-name from swarm-worker-registry.md]
-  goal:    [single-sentence sub-task]
-  context: [minimal context — only what this worker needs]
+---
 
-Worker 2
-  ...
+## Phase 4 — Fan-Out Execution
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+Wave dispatch: POST all contracts simultaneously
+               ↓
+               Wait for completion via allSettled (not Promise.all)
+               ↓
+               Collect ALL results — COMPLETE + BLOCKED + ERROR
+               ↓
+Fan-In:        Supervisor aggregates, resolves conflicts
+               ↓
+               Human Gate before writing anything to disk
 ```
 
-> ⚠️ Workers that share no dependency can run in parallel. Workers that share output must be serialized.
+**allSettled vs Promise.all:** A single failed worker must NOT cancel all sibling workers. Collect all results, then handle failures.
 
 ---
 
-## Step 2 — Worker Dispatch
-
-Each Worker receives its `WorkerRequest` in **isolation** — no Worker sees another Worker's prompt.
+## Phase 5 — Status Protocol
 
-Workers generate their output against the constraints of their specialist agent file (`.agent/agents/{agent}.md`).
+Workers report exactly one of three terminal statuses:
 
-**All Tribunal anti-hallucination rules apply inside each Worker:**
-- No invented libraries or non-existent methods
-- No guessed database column names
-- `// VERIFY:` tags on any uncertain call
-- Retry limit: 3 per Worker
+```
+COMPLETE: Work done. Include output_format fields.
 
-Validate WorkerRequest JSON before dispatch:
+BLOCKED: Cannot proceed without missing prerequisite.
+  blocked_by: [specific missing information]
+  unblocked_by: [what must happen first]
+  → Supervisor: provide missing input or escalate to human
 
-```bash
-// turbo
-python .agent/scripts/swarm_dispatcher.py --mode swarm --file worker_request.json
+ERROR: Unrecoverable after 3 attempts.
+  error: [specific message]
+  attempts: 3
+  → Supervisor: report to human with ⚠️ Agent Failure Report
 ```
 
-A schema validation failure **halts the swarm** — it is not silently ignored.
-
 ---
 
-## Step 3 — Collect and Validate
+## Phase 6 — Session Persistence
 
-After all Workers return a `WorkerResult`:
+Supervisor writes task.md after each wave:
 
-| Status | Meaning | Action |
-|---|---|---|
-| `status: "success"` | Worker completed | Output included in synthesis |
-| `status: "failure"` | Worker errored | Re-dispatch with failure context (up to 3 retries) |
-| `status: "escalate"` | Worker hit retry limit | Noted as ⚠️ in report, not retried |
+```markdown
+# Swarm Session: [goal-slug]
 
----
+## Wave 1 — [timestamp]
+- [task-id]: COMPLETE — [2-line summary]
+- [task-id]: BLOCKED — [reason] → redispatched with [context added]
 
-## Step 4 — Synthesis and Human Gate
+## Issues Carrying Forward
+- [cross-task issue affecting Wave 2]
 
+## Human Gate Status
+- [ ] Pending review
 ```
-━━━ Swarm Complete ━━━━━━━━━━━━━━━━━━━━━━━━
-
-Workers dispatched: [N]
-Workers succeeded:  [N]
-Workers escalated:  [N]
-
-━━━ [Worker 1 goal] ━━━━━━━━━━━━━━━━━━━━━━
-
-[Worker 1 output — reviewed by Tribunal]
-
-━━━ [Worker 2 goal] ━━━━━━━━━━━━━━━━━━━━━━
 
-[Worker 2 output — reviewed by Tribunal]
-
-━━━ Escalations ━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-⚠️ [task_id] — [agent] — [reason for escalation after 3 retries]
+---
 
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Phase 7 — Human Gate
 
-Write to disk?  Y = approve | N = discard | R = revise with feedback
 ```
+━━━ Swarm Complete ━━━━━━━━━━━━━━━━━━━━━░░░
 
-**Human Gate is never skipped.** No files are written without explicit approval.
+Workers: [N dispatched / N complete / N blocked / N error]
 
----
+━━━ Synthesized Results ━━━━━━━━━━━━━━━━━━
+[Findings by severity — critical → high → medium → low]
 
-## Hallucination Guard
+━━━ Files to Write ━━━━━━━━━━━━━━━━━━━━━━
+[List all files with change summaries]
 
-- Supervisor only routes to agents listed in `swarm-worker-registry.md`
-- Each Worker only uses tools, packages, and methods it has seen documented
-- Every `WorkerRequest` is validated against `swarm-worker-contracts.md` before dispatch
-- `swarm_dispatcher.py` exits `1` on any schema violation — swarm halted, not silently degraded
-- Synthesis only combines verified Worker outputs — the Supervisor does not add new logic during synthesis
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━
+Approve?  Y = write to disk | N = discard | R = revise
+```
 
 ---
 
-## Cross-Workflow Navigation
+## Failure Report Format
 
-| After /swarm reveals... | Go to |
-|---|---|
-| Security issues in Worker output | `/tribunal-full` to re-audit the flagged code |
-| Worker escalated after 3 retries | `/debug` to investigate what the worker failed on |
-| Need a more sequential approach | `/orchestrate` for wave-based multi-agent execution |
-| Want to verify final synthesized code | `/tribunal-full` before writing to disk |
+```
+⚠️ Agent Failure Report
+━━━━━━━━━━━━━━━━━━━━━
+Agent:       backend-specialist (Worker A)
+Task:        audit-auth-routes
+Attempts:    3 of 3
+Last Error:  Could not resolve auth.ts import path — tsconfig paths not in scope
+Context:     Files provided: src/app/api/auth/*.ts — missing: tsconfig.json
+Suggestion:  Include tsconfig.json in files_to_read for next dispatch
+```
 
 ---
 
 ## Usage Examples
 
 ```
-/swarm build a REST API with user auth, a PostgreSQL schema, and API documentation
-/swarm analyze this repo, identify security vulnerabilities, and create a remediation plan
-/swarm create a React dashboard component with a backend data endpoint and unit tests
-/swarm refactor the payment module: review the code, optimize the SQL queries, and update the docs
-/swarm generate a full feature: file upload API + storage service + frontend uploader + tests
+/swarm comprehensive pre-launch audit: security + tests + performance + accessibility
+/swarm analyze all API routes for OWASP vulnerabilities simultaneously
+/swarm generate full test suite for auth, checkout, and user management
+/swarm review and optimize all N+1 query patterns across the codebase
 ```