tribunal-kit 1.0.0

package/.agent/workflows/generate.md

@@ -0,0 +1,100 @@
+---
+description: Generate code using the full Tribunal Anti-Hallucination pipeline. Maker generates at low temperature → selected reviewers audit in parallel → Human Gate for final approval.
+---
+
+# /generate — Hallucination-Free Code Generation
+
+$ARGUMENTS
+
+---
+
+This command runs code generation through the full Tribunal pipeline. Code reaches you only after being reviewed. Nothing is written to disk without your explicit approval.
+
+---
+
+## Pipeline Flow
+
+```
+Your request
+    │
+    ▼
+Context read — existing files, schema, package.json scanned
+    │
+    ▼
+Maker generates at temperature 0.1
+(grounded in context, never inventing)
+    │
+    ▼
+Selected reviewers run in parallel
+    │
+    ▼
+Human Gate — you see all verdicts and the diff
+Only then: write to disk (Y) or discard (N) or revise (R)
+```
+
+---
+
+## Who Reviews It
+
+Default (always active):
+
+```
+logic-reviewer     → Hallucinated methods, impossible logic, undefined refs
+security-auditor   → OWASP vulnerabilities, SQL injection, hardcoded secrets
+```
+
+Auto-activated by keywords in your request:
+
+| Keyword | Additional Reviewer |
+|---|---|
+| api, route, endpoint | `dependency-reviewer` + `type-safety-reviewer` |
+| sql, query, database | `sql-reviewer` |
+| component, hook, react | `frontend-reviewer` + `type-safety-reviewer` |
+| test, spec, coverage | `test-coverage-reviewer` |
+| slow, memory, optimize | `performance-reviewer` |
+
+---
+
+## What the Maker Is Not Allowed to Do
+
+```
+❌ Import a package not in the project's package.json
+❌ Call a method it hasn't seen documented
+❌ Use `any` in TypeScript without a comment explaining why
+❌ Generate an entire application in one shot
+❌ Guess at a database column name
+```
+
+When unsure about any call: it writes `// VERIFY: [reason]` instead of hallucinating.
+
+---
+
+## Output Format
+
+```
+━━━ Tribunal: [Domain] ━━━━━━━━━━━━━━━━━━
+
+Active reviewers: logic · security · [others]
+
+[Generated code]
+
+━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+logic-reviewer:       ✅ APPROVED
+security-auditor:     ✅ APPROVED
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━
+
+Write to disk?  Y = approve | N = discard | R = revise with feedback
+```
+
+---
+
+## Usage
+
+```
+/generate a JWT middleware for Express with algorithm enforcement
+/generate a Prisma query for users with their posts included
+/generate a debounced search hook in React
+/generate a function to validate and normalize email addresses
+```

package/.agent/workflows/orchestrate.md

@@ -0,0 +1,102 @@
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.
+---
+
+# /orchestrate — Multi-Agent Coordination
+
+$ARGUMENTS
+
+---
+
+This command coordinates multiple specialists to solve a problem that requires more than one domain. One agent is not orchestration.
+
+---
+
+## The Minimum Rule
+
+> **Fewer than 3 agents = not orchestration.**
+>
+> Before marking any orchestration session as complete, count the agents invoked. If the count is less than 3, activate more. A single agent delegated to is just a delegation.
+
+---
+
+## Agent Selection by Task Type
+
+| Task | Required Specialists |
+|---|---|
+| Full-stack feature | `frontend-specialist` + `backend-specialist` + `test-engineer` |
+| API build | `backend-specialist` + `security-auditor` + `test-engineer` |
+| Database-heavy work | `database-architect` + `backend-specialist` + `security-auditor` |
+| Complete product | `project-planner` + `frontend-specialist` + `backend-specialist` + `devops-engineer` |
+| Security investigation | `security-auditor` + `penetration-tester` + `devops-engineer` |
+| Complex bug | `debugger` + `explorer-agent` + `test-engineer` |
+
+---
+
+## Two-Phase Protocol (Strict)
+
+### Phase A — Planning Only
+
+Only two agents are allowed during planning:
+
+```
+project-planner   → writes docs/PLAN-{slug}.md
+explorer-agent    → (if working in existing code) maps the codebase
+```
+
+No other agent runs. No code is produced.
+
+After planning, the plan is shown to the user:
+
+```
+✅ Plan ready: docs/PLAN-{slug}.md
+
+Approve to start implementation? (Y / N)
+```
+
+**Phase B does NOT start without a Y.**
+
+### Phase B — Implementation (Parallel)
+
+After approval, specialists activate:
+
+```
+Foundation tier:  database-architect + security-auditor (run first)
+Core tier:        backend-specialist + frontend-specialist (after foundation)
+Quality tier:     test-engineer + qa-automation-engineer (after core)
+```
+
+Each tier's output goes through its Tribunal gate before the next tier begins.
+
+---
+
+## Cross-Agent Context Handoff
+
+When one agent's output feeds the next:
+
+```
+The context passed to Agent B must include:
+  "Agent A produced: [result]
+   Build on this. Do not re-derive it."
+```
+
+Never let Agent B re-invent what Agent A already established.
+
+---
+
+## Hallucination Guard
+
+- Every agent's output goes through Tribunal before it reaches the user
+- The Human Gate fires before any file is written — the user sees the diff and approves
+- Retry limit: 3 Maker revisions per agent. After 3 failures, stop and report to the user.
+- Per-agent scope is enforced — `frontend-specialist` never writes DB migrations
+
+---
+
+## Usage
+
+```
+/orchestrate build a complete auth system with JWT and refresh tokens
+/orchestrate review the entire API layer for security issues
+/orchestrate build a multi-tenant SaaS onboarding flow
+```

package/.agent/workflows/plan.md

@@ -0,0 +1,108 @@
+---
+description: Create project plan using project-planner agent. No code writing - only plan file generation.
+---
+
+# /plan — Write the Plan First
+
+$ARGUMENTS
+
+---
+
+This command produces one thing: a structured plan file. Nothing is implemented. No code is written. The plan is the output.
+
+---
+
+## Why Plan Before Building
+
+> Tasks without plans get rebuilt three times.
+> Plans expose ambiguity before it becomes broken code.
+
+---
+
+## How It Works
+
+### Gate: Clarify Before You Plan
+
+The `project-planner` agent asks:
+
+```
+What outcome needs to exist that doesn't exist today?
+What are the hard constraints? (stack, existing code, deadline)
+What's explicitly not being built in this version?
+How will we confirm it's done?
+```
+
+If any answer is "I don't know" — those are clarified before the plan is written, not after.
+
+### Plan File Creation
+
+```
+Location: docs/PLAN-{task-slug}.md
+
+Slug naming:
+  Pull 2–3 key words from the request
+  Lowercase + hyphens
+  Max 30 characters
+  "build auth with JWT" → PLAN-auth-jwt.md
+  "shopping cart checkout" → PLAN-cart-checkout.md
+```
+
+### After the File is Written
+
+```
+✅ Plan written: docs/PLAN-{slug}.md
+
+Review it, then:
+  Run /create to begin implementation
+  Or edit the file to refine scope first
+```
+
+---
+
+## Plan File Structure
+
+```markdown
+# Plan: [Feature Name]
+
+## What Done Looks Like
+[Observable outcome — one sentence]
+
+## Won't Include in This Version
+- [Explicit exclusion]
+
+## Unresolved Questions
+- [Thing that needs external confirmation: VERIFY]
+
+## Estimates (Ranges + Confidence)
+All time estimates include: optimistic / realistic / pessimistic + confidence level
+
+## Task Table
+| # | Task | Agent | Depends on | Done when |
+|---|------|-------|-----------|-----------|
+| 1 | ... | database-architect | none | migration runs |
+| 2 | ... | backend-specialist | #1 | returns 201 |
+
+## Review Gates
+| Task | Tribunal |
+|---|---|
+| #1 schema | /tribunal-database |
+| #2 API | /tribunal-backend |
+```
+
+---
+
+## Hallucination Guard
+
+- Every tool/library mentioned in the plan must be real and verified
+- All time estimates are ranges with a confidence label — never single-point guarantees
+- External dependencies that aren't confirmed get a `[VERIFY: check this exists]` tag
+
+---
+
+## Usage
+
+```
+/plan REST API with user auth
+/plan dark mode toggle for the settings page
+/plan multi-tenant account switching
+```

package/.agent/workflows/preview.md

@@ -0,0 +1,81 @@
+---
+description: Preview server start, stop, and status check. Local development server management.
+---
+
+# /preview — Local Server Control
+
+$ARGUMENTS
+
+---
+
+Start, stop, or check the development server so you can verify generated code before approving it for your codebase.
+
+---
+
+## Sub-commands
+
+```
+/preview start     → Launch the dev server
+/preview stop      → Shut down the running server
+/preview status    → Check if server is live and on which URL
+/preview restart   → Stop + start in sequence
+```
+
+---
+
+## On Start
+
+```
+Step 1:  Check if a process is already using the target port (warn if yes)
+Step 2:  Read package.json → scripts.dev or scripts.start to find the actual command
+Step 3:  Launch the server
+Step 4:  Wait for the ready signal (port open or "ready" in output)
+Step 5:  Report back
+
+━━━ Server Started ━━━━━━━━━━━━━━━
+URL:     http://localhost:[port]
+Command: [actual command used]
+
+Run /preview stop to shut down.
+```
+
+---
+
+## On Stop
+
+```
+Step 1: Locate the running process by port or PID
+Step 2: Send graceful shutdown
+Step 3: Confirm port is released
+
+━━━ Server Stopped ━━━━━━━━━━━━━━━
+Port [N] is now free.
+```
+
+---
+
+## On Status
+
+```
+🟢  Running — http://localhost:[port]  (PID [N])
+🔴  Not running — no active process found on this port
+```
+
+---
+
+## Hallucination Guard
+
+- `package.json` is always read before assuming the start command — never assume it's `npm run dev`
+- The actual port is checked from the config — never hardcoded to 3000
+- No invented server flags added to the start command
+
+---
+
+## Usage
+
+```
+/preview start
+/preview stop
+/preview status
+/preview restart
+```

package/.agent/workflows/review.md

@@ -0,0 +1,88 @@
+---
+description: Audit existing code for hallucinations. Runs Logic + Security reviewers on any code without generating anything new.
+---
+
+# /review — Code Audit (No Generation)
+
+$ARGUMENTS
+
+---
+
+This command audits code you already have. Nothing is generated. The reviewers read, analyze, and report — that's it.
+
+Paste code directly after the command, or point to a file.
+
+---
+
+## How to Use It
+
+```
+/review
+
+[paste code here]
+```
+
+Or:
+
+```
+/review src/services/auth.service.ts
+```
+
+---
+
+## What Always Runs
+
+```
+logic-reviewer      → Methods that don't exist, conditions that can't be true,
+                      undefined variables used before assignment
+
+security-auditor    → SQL injection, hardcoded credentials, auth bypass,
+                      unvalidated input, exposed stack traces
+```
+
+## What Also Runs (Based on Code Type)
+
+| Code Contains | Additional Reviewer |
+|---|---|
+| SQL / ORM queries | `sql-reviewer` |
+| React hooks / components | `frontend-reviewer` |
+| TypeScript types / generics | `type-safety-reviewer` |
+| Import statements | `dependency-reviewer` |
+
+---
+
+## Audit Report Format
+
+```
+━━━ Audit: [filename or snippet] ━━━━━━━━━
+
+logic-reviewer:       ✅ No hallucinated APIs found
+security-auditor:     ❌ REJECTED
+
+Findings:
+  ❌ Critical — Line 8
+     Type: SQL injection
+     Code: `db.query(\`SELECT * WHERE id = ${id}\`)`
+     Fix:  Use parameterized: `db.query('SELECT * WHERE id = $1', [id])`
+
+  ⚠️ Warning — Line 22
+     Type: Unguarded optional access
+     Code: `user.profile.name`
+     Fix:  `user?.profile?.name ?? 'Unknown'`
+
+━━━ Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1 Critical issue blocking integration.
+1 Warning — review before shipping.
+```
+
+---
+
+## Usage
+
+```
+/review the auth middleware
+/review this SQL query [paste]
+/review src/routes/user.ts for injection risks
+/review my React component for hooks violations
+```

package/.agent/workflows/status.md

@@ -0,0 +1,69 @@
+---
+description: Display agent and project status. Progress tracking and status board.
+---
+
+# /status — Session View
+
+$ARGUMENTS
+
+---
+
+This command shows the current state of the active Tribunal session — what has run, what passed, what was rejected, and what is waiting at the Human Gate.
+
+---
+
+## Session Dashboard
+
+```
+━━━ Tribunal Session ━━━━━━━━━━━━━━━━━━━━
+
+Mode:     [Generate | Review | Plan | Audit]
+Request:  [original prompt or task name]
+
+━━━ Agent Activity ━━━━━━━━━━━━━━━━━━━━━
+
+  logic-reviewer          ✅ APPROVED
+  security-auditor        ❌ REJECTED — 1 issue
+  dependency-reviewer     ✅ APPROVED
+  type-safety-reviewer    🔄 Running
+  performance-reviewer    ⏸️  Queued
+
+━━━ Blocked Issues ━━━━━━━━━━━━━━━━━━━━━
+
+❌ security-auditor flagged:
+   File: src/routes/user.ts — Line 34
+   Type: SQL injection
+   Fix:  Replace string interpolation with parameterized query
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Status: ⏸️  Awaiting your decision before any file is written.
+
+  Options:
+    ✅ Approve  — write the approved changes to disk
+    🔄 Revise   — send back to the Maker with feedback
+    ❌ Discard  — drop this generation entirely
+```
+
+---
+
+## Status Symbols
+
+| 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 |
+
+---
+
+## Sub-commands
+
+```
+/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
+```

package/.agent/workflows/test.md

@@ -0,0 +1,117 @@
+---
+description: Test generation and test running command. Creates and executes tests for code.
+---
+
+# /test — Test Quality Engine
+
+$ARGUMENTS
+
+---
+
+This command either generates tests that actually test things, or audits existing tests to find ones that don't. A test that always passes isn't protecting anything.
+
+---
+
+## Modes
+
+```
+/test [file or function]     → Generate tests for the target
+/test audit                  → Check existing tests for quality issues
+/test coverage               → Identify code paths with no test coverage
+/test edge [function]        → Generate edge-case tests only (null, empty, boundary)
+```
+
+---
+
+## When Generating Tests
+
+**First, the code is read:**
+- Every execution path is mapped (normal path, error path, edge cases)
+- Direct external dependencies are identified (to mock)
+- Expected inputs and outputs are derived from the function signature and behavior
+
+**Then a test plan is written before code:**
+
+```
+Target: [function or module]
+
+Path inventory:
+  › Normal path with valid input
+  › Null / undefined input
+  › Empty string / empty array
+  › Boundary value (0, -1, MAX)
+  › Async rejection / network failure
+  › Invalid type input
+
+Dependencies to mock: [list — minimal, only direct deps]
+```
+
+**Then tests are written and passed through `test-coverage-reviewer`.**
+
+---
+
+## Test Structure Standard
+
+Every generated test file follows this format:
+
+```typescript
+describe('[Unit under test]', () => {
+
+  describe('[scenario group]', () => {
+    it('[specific behavior]', () => {
+      // Arrange
+      const input = [setup value];
+
+      // Act
+      const result = functionUnderTest(input);
+
+      // Assert — specific value, not .toBeDefined()
+      expect(result).toBe([exact expected value]);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('throws when input is null', () => {
+      expect(() => functionUnderTest(null)).toThrow('[exact message]');
+    });
+
+    it('handles empty string', () => {
+      expect(() => functionUnderTest('')).toThrow('[exact message]');
+    });
+  });
+
+});
+```
+
+---
+
+## When Auditing Existing Tests
+
+The `test-coverage-reviewer` flags:
+
+| Problem | What It Looks Like |
+|---|---|
+| Tautology test | `expect(fn(x)).toBe(fn(x))` — always passes |
+| No assertion | `it('works', () => { fn(); })` — nothing checked |
+| Missing edge cases | Suite has happy path only |
+| Over-mocking | Every dependency mocked — nothing real tested |
+
+---
+
+## Hallucination Guard
+
+- Only documented Vitest/Jest methods are used — never `test.eventually()`, `expect.when()`, or invented matchers
+- Assertions test specific values — `toBe('exact')`, not `toBeDefined()` or `toBeTruthy()`
+- Mocks are **minimal** — only the direct external dependency of the unit, not the whole world
+- After auditing existing tests: all conclusions are backed by reading the actual test code
+
+---
+
+## Usage
+
+```
+/test src/services/auth.service.ts
+/test the validateEmail function
+/test audit — check whether my existing tests actually assert anything
+/test coverage — show branches with no test
+```