tribunal-kit 1.0.0 → 2.4.2

package/.agent/workflows/session.md

@@ -0,0 +1,154 @@
+---
+description: Interactive session state tracking for multi-conversation context continuity.
+---
+
+# /session — Interactive Session State Tracker
+
+Use this workflow to maintain context and track overarching goals across multiple single-chat sessions. It acts as a logbook that survives conversation resets.
+
+---
+
+## When to Use This
+
+- Starting a long multi-session task (spanning multiple conversations)
+- Resuming work after a break — load the last checkpoint instantly
+- Tracking parallel workstreams (tag different sessions)
+- Exporting a summary of work for documentation or handoff
+
+---
+
+## Commands
+
+```bash
+# ── Core commands ──────────────────────────────────────────────────
+
+# Save a checkpoint of the current session
+// turbo
+python .agent/scripts/session_manager.py save "working on auth middleware"
+
+# Load the current active session (note + tags)
+// turbo
+python .agent/scripts/session_manager.py load
+
+# Compact status overview: active session + last 3 checkpoints
+// turbo
+python .agent/scripts/session_manager.py status
+
+# View the last 10 session checkpoints
+// turbo
+python .agent/scripts/session_manager.py show
+
+# ── Tagging and filtering ─────────────────────────────────────────
+
+# Add a label/tag to the current session
+python .agent/scripts/session_manager.py tag <label>
+python .agent/scripts/session_manager.py tag v2-feature
+
+# ── History and export ────────────────────────────────────────────
+
+# Paginated list of ALL sessions (most recent first)
+python .agent/scripts/session_manager.py list
+python .agent/scripts/session_manager.py list --all   # show entire history
+
+# Export all sessions to session_export.md (or stdout)
+python .agent/scripts/session_manager.py export
+python .agent/scripts/session_manager.py export --stdout
+
+# Clear the session data entirely to start fresh
+python .agent/scripts/session_manager.py clear
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---|---|
+| `save <note>` | Save a new session checkpoint with a note |
+| `load` | Display the current active session |
+| `status` | Compact 3-session status summary + active session |
+| `show` | Show the last 10 sessions |
+| `tag <label>` | Add a tag to the current session (e.g., `v2-feature`, `auth-sprint`) |
+| `list [--all]` | Paginated full session history |
+| `export [--stdout]` | Export all history to `session_export.md` |
+| `clear` | Delete the session state file entirely |
+
+---
+
+## How It Works
+
+Session state is stored in `.agent_session.json` in the project root.
+
+**Start of a new conversation:** run `status` immediately to re-establish situational awareness:
+
+```
+python .agent/scripts/session_manager.py status
+```
+
+**When reaching a natural waypoint** (completed a task, switching context): run `save` with a descriptive note so the next session starts with full context.
+
+**Tags** group related sessions for filtering and export. Use them for features, sprints, or bugfix tracks.
+
+---
+
+## Workflow Patterns
+
+**Starting a session:**
+```
+User:  /session save "Finished implementing JWT strategy. Next: user endpoints."
+Agent: ✅ Session saved: Finished implementing JWT strategy...
+       Session: #5, tagged: auth-sprint
+```
+
+**Resuming after a break:**
+```
+User:  /session status
+Agent: ━━━ Session Status ━━━━━━━━━━━━━━━━━━━━━━━━
+         Total sessions: 5
+         Active:         #5 — Finished implementing JWT strategy...
+
+         Last 3 sessions:
+           #5  2026-03-03T23:15  [auth-sprint]  Finished JWT strategy...
+           #4  2026-03-03T21:00  [auth-sprint]  Completed DB schema for auth...
+           #3  2026-03-03T18:30  [auth-sprint]  Set up project structure...
+```
+
+**Exporting for handoff or documentation:**
+```
+User:  /session export
+Agent: ✅ Exported 5 sessions to session_export.md
+```
+
+---
+
+## Best Practices
+
+| Practice | Why |
+|---|---|
+| Save at every natural stopping point | Next session starts with accurate context |
+| Use descriptive notes with "Next:" | Gives future sessions a clear direction |
+| Tag sessions by feature or sprint | Makes export and filtering useful |
+| Run `status` at every session start | Reestablishes context without reading the full history |
+
+---
+
+## Cross-Workflow Navigation
+
+| Use /session when... | Then go to... |
+|---|---|
+| Starting a multi-session task | `/plan` to write the formal plan for the work |
+| Resuming work on a feature | Load session, then continue with relevant workflow |
+| Work is complete, documenting it | `/changelog` to record what was built |
+
+---
+
+## Usage
+
+```
+/session save "Finished JWT middleware. Next: protect API routes."
+/session status
+/session tag auth-sprint
+/session list
+/session export
+/session load
+```

package/.agent/workflows/status.md

@@ -12,33 +12,64 @@ This command shows the current state of the active Tribunal session — what has
 
 ---
 
+## When to Use This
+
+- After starting a multi-agent task to see which reviewers finished
+- When a reviewer rejected code and you want details on the finding
+- To check whether anything is currently at the Human Gate awaiting your decision
+- To get a snapshot of the session before resuming after a break
+
+---
+
+## Sub-commands
+
+```
+/status              → Full session view (default)
+/status issues       → Show only REJECTED and WARNING verdicts
+/status gate         → Show what's currently at the Human Gate
+/status agents       → Show only the agent activity table
+/status history      → Show the last 5 completed tribunal sessions
+```
+
+---
+
 ## Session Dashboard
 
 ```
 ━━━ Tribunal Session ━━━━━━━━━━━━━━━━━━━━
 
-Mode:     [Generate | Review | Plan | Audit]
+Mode:     [Generate | Review | Plan | Audit | Swarm]
 Request:  [original prompt or task name]
+Started:  [timestamp]
 
 ━━━ Agent Activity ━━━━━━━━━━━━━━━━━━━━━
 
   logic-reviewer          ✅ APPROVED
-  security-auditor        ❌ REJECTED — 1 issue
+  security-auditor        ❌ REJECTED — 1 CRITICAL issue
   dependency-reviewer     ✅ APPROVED
-  type-safety-reviewer    🔄 Running
-  performance-reviewer    ⏸️  Queued
+  type-safety-reviewer    ⚠️  WARNING — 1 MEDIUM issue
+  performance-reviewer    🔄 Running...
+  sql-reviewer            ⏸️  Queued
 
 ━━━ Blocked Issues ━━━━━━━━━━━━━━━━━━━━━
 
-❌ security-auditor flagged:
-   File: src/routes/user.ts — Line 34
-   Type: SQL injection
-   Fix:  Replace string interpolation with parameterized query
+❌ security-auditor [CRITICAL] — src/routes/user.ts line 34
+   Type: SQL injection via string interpolation
+   Code: db.query(`WHERE id = ${id}`)
+   Fix:  db.query('WHERE id = $1', [id])
+
+⚠️ type-safety-reviewer [MEDIUM] — src/auth/jwt.ts line 12
+   Type: Implicit any in parameter
+   Code: function decodeToken(payload) { ... }
+   Fix:  function decodeToken(payload: JWTPayload) { ... }
 
 ━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━
 
   Status: ⏸️  Awaiting your decision before any file is written.
 
+  Blocked on: security-auditor rejection (CRITICAL)
+  Action required: Fix the issue and resubmit, or discard.
+
   Options:
     ✅ Approve  — write the approved changes to disk
     🔄 Revise   — send back to the Maker with feedback
@@ -51,19 +82,44 @@ Request:  [original prompt or task name]
 
 | Symbol | Meaning |
 |---|---|
-| ✅ | Agent complete — verdict returned |
-| 🔄 | Agent currently running |
-| ⏸️ | Queued — waiting for a prior stage |
-| ❌ | Rejected — issue found, cannot proceed |
-| ⚠️ | Warning — non-blocking, review before approving |
+| `✅ APPROVED` | Agent complete — no blocking issues |
+| `🔄 Running` | Agent currently executing |
+| `⏸️ Queued` | Waiting for a prior stage to complete |
+| `❌ REJECTED` | Blocking finding — code cannot proceed |
+| `⚠️ WARNING` | Non-blocking finding — review before approving |
+| `N/A` | Reviewer ran but this domain not present in code |
 
 ---
 
-## Sub-commands
+## Retry Counter
+
+The status view also shows how many revision attempts have been made:
 
 ```
-/status              → Full session view
-/status issues       → Show only REJECTED and WARNING verdicts
-/status gate         → Show what's currently at the Human Gate awaiting approval
-/status agents       → Show only the agent activity table
+Maker revision: 2 of 3 (1 remaining before escalation)
+```
+
+After 3 revisions without resolving a CRITICAL rejection, the session halts and reports to the user.
+
+---
+
+## Cross-Workflow Navigation
+
+| If /status shows... | Go to |
+|---|---|
+| CRITICAL security rejection | `/review [file]` for focused audit |
+| Multiple rejections across domains | `/tribunal-full` if it hasn't run yet |
+| Session stalled at Human Gate | Review findings and decide: approve/revise/discard |
+| Everything approved, ready to write | Confirm the Human Gate to write to disk |
+
+---
+
+## Usage
+
+```
+/status
+/status issues
+/status gate
+/status agents
+/status history
 ```

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

@@ -0,0 +1,99 @@
+---
+description: Strengthen skills by appending Tribunal guardrails (LLM Traps, Pre-Flight checklist, VBC Protocol) to any SKILL.md missing them.
+---
+
+# /strengthen-skills Workflow
+
+Use this command to audit and harden all skills in `.agent/skills/` that are missing
+the standard Tribunal guardrails block.
+
+---
+
+## What It Does
+
+Runs `strengthen_skills.py` against all skill files.  
+For each skill it checks:
+
+1. **Tribunal Integration section** — does it have `🏛️ Tribunal Integration`?
+2. **VBC Protocol** — does it have `Verification-Before-Completion`?
+
+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
+
+Skills that already have both sections are skipped automatically.
+
+---
+
+## Steps
+
+### Step 1 — Dry Run (Always First)
+
+```powershell
+python .agent/scripts/strengthen_skills.py . --dry-run
+```
+
+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.
+
+---
+
+### Step 2 — Strengthen All Skills
+
+```powershell
+python .agent/scripts/strengthen_skills.py .
+```
+
+---
+
+### Step 3 — Verify Summary
+
+The script prints a final summary:
+```
+✅ Strengthened: N
+⏭️  Skipped:     N
+❌ Errors:       0
+```
+
+Errors must be zero before proceeding. If any errors appear, fix them and re-run.
+
+---
+
+### Step 4 — Strengthen a Single Skill (Optional)
+
+To strengthen one specific skill only:
+
+```powershell
+python .agent/scripts/strengthen_skills.py . --skill <skill-name>
+```
+
+Example:
+```powershell
+python .agent/scripts/strengthen_skills.py . --skill brainstorming
+```
+
+---
+
+### Step 5 — Custom Skills Directory (Optional)
+
+If skills live in a non-standard location:
+
+```powershell
+python .agent/scripts/strengthen_skills.py . --skills-path /path/to/skills
+```
+
+---
+
+## Related Commands
+
+| 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 |

package/.agent/workflows/swarm.md

@@ -0,0 +1,194 @@
+---
+description: Multi-Agent Swarm Orchestration — Supervisor decomposes a goal into sub-tasks, dispatches to specialist Workers, collects results, and synthesizes a unified response.
+---
+
+# /swarm — Multi-Agent Swarm Orchestration
+
+$ARGUMENTS
+
+---
+
+## What This Does
+
+`/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.
+
+---
+
+## When to Use /swarm vs Other Commands
+
+| 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` |
+
+---
+
+## Pipeline Flow
+
+```
+/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
+
+The `supervisor-agent` reads the goal and produces a dispatch plan.
+
+**Format:**
+
+```
+━━━ Swarm Triage ━━━━━━━━━━━━━━━━━━━━━━━━
+
+Goal: [restate the user's goal in one sentence]
+
+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
+  ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+> ⚠️ Workers that share no dependency can run in parallel. Workers that share output must be serialized.
+
+---
+
+## Step 2 — Worker Dispatch
+
+Each Worker receives its `WorkerRequest` in **isolation** — no Worker sees another Worker's prompt.
+
+Workers generate their output against the constraints of their specialist agent file (`.agent/agents/{agent}.md`).
+
+**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
+
+Validate WorkerRequest JSON before dispatch:
+
+```bash
+// turbo
+python .agent/scripts/swarm_dispatcher.py --mode swarm --file worker_request.json
+```
+
+A schema validation failure **halts the swarm** — it is not silently ignored.
+
+---
+
+## Step 3 — Collect and Validate
+
+After all Workers return a `WorkerResult`:
+
+| 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 |
+
+---
+
+## Step 4 — Synthesis and Human Gate
+
+```
+━━━ 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Write to disk?  Y = approve | N = discard | R = revise with feedback
+```
+
+**Human Gate is never skipped.** No files are written without explicit approval.
+
+---
+
+## Hallucination Guard
+
+- 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
+
+---
+
+## Cross-Workflow Navigation
+
+| 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 |
+
+---
+
+## 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
+```