tribunal-kit 1.0.0 → 2.4.2

package/.agent/workflows/api-tester.md

@@ -0,0 +1,279 @@
+---
+description: Automated multi-stage API endpoint testing. Generates and runs auth-aware request sequences.
+---
+
+# /api-tester — Automated API Test Flows
+
+$ARGUMENTS
+
+---
+
+This command generates and runs multi-stage API test sequences. It goes beyond single-endpoint testing by simulating realistic user sessions with chained requests, variable capture, and assertion verification.
+
+---
+
+## When to Use This vs Other Commands
+
+| Use `/api-tester` when... | Use something else when... |
+|---|---|
+| Testing multi-step flows (auth + resource lifecycle) | Unit tests → `/test` |
+| Verifying endpoint contracts before deploy | Logic review → `/review` |
+| Debugging a specific flow returning wrong data | Root cause → `/debug` |
+| Security testing for injection/rate limits | Full security audit → `/audit` |
+
+---
+
+## When to Use
+
+- After creating or modifying API routes.
+- Before deployment to validate endpoint contracts.
+- When debugging a multi-step flow (e.g., Register → Login → Create Resource → Verify).
+- When the user says "test api", "endpoint test", or "api flow".
+
+---
+
+## Pipeline Flow
+
+```
+Your request (endpoint or flow description)
+    │
+    ▼
+Context read — route files, middleware, schema, auth config, package.json
+    │
+    ▼
+Route discovery — scan for all registered endpoints and methods
+    │
+    ▼
+Test Plan generated (sequence of requests with dependencies & captures)
+    │
+    ▼
+Environment check — server running? Base URL resolved? Auth available?
+    │
+    ▼
+Execution — each step runs, captures response, feeds next step
+    │
+    ▼
+Report — pass/fail per step, response times, payload diffs, coverage map
+```
+
+---
+
+## Step 1: Route Discovery
+
+Before generating tests, scan the codebase for route definitions:
+
+| Framework | Scan Pattern | What to Extract |
+|---|---|---|
+| Express | `app.get/post/put/delete/patch` or `router.*` | Method, path, middleware |
+| Fastify | `fastify.route` or `fastify.get/post/...` | Method, path, schema |
+| Next.js API | `app/api/**/route.ts` | Exported functions (GET, POST) |
+| Django/DRF | `urlpatterns`, `@api_view` | Method, path, viewset |
+| FastAPI | `@app.get/post/put/delete` | Method, path, response model |
+| Go (Chi/Gin) | `r.Get/Post/Put/Delete` | Method, path, handler |
+
+**Output a route map before generating tests:**
+```
+━━━ Route Map ━━━━━━━━━━━━━━━━━━━━━━━━━━
+GET    /api/users          → UserController.list    [auth: required]
+POST   /api/users          → UserController.create  [auth: admin]
+GET    /api/users/:id      → UserController.get     [auth: required]
+PUT    /api/users/:id      → UserController.update  [auth: owner]
+DELETE /api/users/:id      → UserController.delete  [auth: admin]
+POST   /api/auth/login     → AuthController.login   [auth: none]
+POST   /api/auth/register  → AuthController.register [auth: none]
+```
+
+---
+
+## Step 2: Test Pattern Selection
+
+### Pattern 1: CRUD Lifecycle
+Full create-read-update-read-delete-verify cycle:
+```
+Step 1: POST   /api/resource        → Create (capture: response.id → $RESOURCE_ID)
+Step 2: GET    /api/resource/$RESOURCE_ID  → Read (assert: 200, body matches creation)
+Step 3: PUT    /api/resource/$RESOURCE_ID  → Update (send modified fields)
+Step 4: GET    /api/resource/$RESOURCE_ID  → Read (assert: updated fields match)
+Step 5: DELETE /api/resource/$RESOURCE_ID  → Delete (assert: 204 or 200)
+Step 6: GET    /api/resource/$RESOURCE_ID  → Read (assert: 404)
+```
+
+### Pattern 2: Auth Flow
+Full authentication lifecycle:
+```
+Step 1: POST   /api/auth/register   → Register (capture: $TOKEN)
+Step 2: POST   /api/auth/login      → Login (capture: $JWT, $REFRESH_TOKEN)
+Step 3: GET    /api/protected       → With JWT header (assert: 200)
+Step 4: GET    /api/protected       → Without JWT (assert: 401)
+Step 5: POST   /api/auth/refresh    → With $REFRESH_TOKEN (capture: $NEW_JWT)
+Step 6: GET    /api/protected       → With $NEW_JWT (assert: 200)
+Step 7: POST   /api/auth/logout     → Invalidate session
+Step 8: GET    /api/protected       → With invalidated JWT (assert: 401)
+```
+
+### Pattern 3: Edge Cases & Error Handling
+```
+Step 1: POST   /api/resource        → Missing required fields (assert: 400 + error message)
+Step 2: POST   /api/resource        → Invalid field types (assert: 400 + validation detail)
+Step 3: POST   /api/resource        → Duplicate unique field (assert: 409)
+Step 4: GET    /api/resource/99999  → Non-existent ID (assert: 404)
+Step 5: PUT    /api/resource/:id    → Unauthorized user (assert: 403)
+Step 6: DELETE /api/resource/:id    → Without auth (assert: 401)
+Step 7: GET    /api/resource?page=-1 → Invalid pagination (assert: 400)
+Step 8: POST   /api/resource        → Payload too large (assert: 413 or 400)
+```
+
+### Pattern 4: Pagination & Filtering
+```
+Step 1: POST   /api/resource  → Create 5 records (loop)
+Step 2: GET    /api/resource?page=1&limit=2   → (assert: 2 items, hasMore: true)
+Step 3: GET    /api/resource?page=2&limit=2   → (assert: 2 items, hasMore: true)
+Step 4: GET    /api/resource?page=3&limit=2   → (assert: 1 item, hasMore: false)
+Step 5: GET    /api/resource?sort=createdAt&order=desc → (assert: items in descending order)
+Step 6: GET    /api/resource?filter=name:test  → (assert: only matching items returned)
+```
+
+### Pattern 5: Rate Limiting & Security
+```
+Step 1: POST   /api/auth/login × 10  → Rapid-fire login attempts
+Step 2: POST   /api/auth/login        → (assert: 429 Too Many Requests or similar)
+Step 3: Wait   [cooldown period]
+Step 4: POST   /api/auth/login        → (assert: allowed again)
+Step 5: POST   /api/resource           → With SQL injection in body (assert: 400, no SQL error exposed)
+Step 6: GET    /api/resource?id=1 OR 1=1 → (assert: 400 or filtered, no data leak)
+```
+
+---
+
+## Step 3: Variable Capture & Chaining
+
+Tests are chained via captured variables:
+
+```
+$VAR_NAME = response.body.fieldPath
+
+Examples:
+$USER_ID     = response.body.data.id
+$JWT         = response.body.token
+$CSRF_TOKEN  = response.headers['x-csrf-token']
+$TOTAL_COUNT = response.body.meta.total
+```
+
+Variables are passed forward:
+- **Headers**: `Authorization: Bearer $JWT`
+- **URL params**: `/api/users/$USER_ID`
+- **Body fields**: `{ "userId": "$USER_ID" }`
+
+---
+
+## Step 4: Assertion Engine
+
+Each step can assert on:
+
+| Assertion Type | Example | Description |
+|---|---|---|
+| Status code | `assert: 200` | HTTP status |
+| Body field exists | `assert: body.id exists` | Field presence |
+| Body field value | `assert: body.name === "test"` | Exact match |
+| Body field type | `assert: body.items is Array` | Type check |
+| Header present | `assert: headers.content-type contains "json"` | Header check |
+| Response time | `assert: time < 500ms` | Performance gate |
+| Array length | `assert: body.items.length === 3` | Count check |
+| Negative match | `assert: body.password === undefined` | Field NOT present |
+
+---
+
+## Output Format
+
+```
+━━━ API Test Report ━━━━━━━━━━━━━━━━━━━━━━
+
+Flow:    [Name of the flow tested]
+Base:    [base URL]
+Steps:   6 total | 5 passed | 1 failed
+Time:    1.2s total
+
+━━━ Execution ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 1: POST /api/auth/login           ✅ 200  (142ms)
+        ↳ Captured: $JWT
+Step 2: GET  /api/users/me              ✅ 200  (89ms)
+        ↳ Asserted: body.email === "test@example.com"
+Step 3: PUT  /api/users/me              ✅ 200  (112ms)
+        ↳ Sent: { name: "Updated Name" }
+Step 4: GET  /api/users/me              ✅ 200  (78ms)
+        ↳ Asserted: body.name === "Updated Name"
+Step 5: DELETE /api/users/me            ✅ 204  (95ms)
+Step 6: GET  /api/users/me              ❌ FAIL (67ms)
+        ↳ Expected: 404
+        ↳ Received: 200 { name: "Updated Name", deletedAt: "2026-03-05T..." }
+
+━━━ Failure Analysis ━━━━━━━━━━━━━━━━━━━━
+
+Step 6: Soft-delete returning 200 instead of 404.
+  Root cause: GET route doesn't filter `deletedAt IS NOT NULL`.
+  File to check: controllers/user.controller.ts → findOne method
+  Suggested fix: Add `WHERE deletedAt IS NULL` condition to query.
+
+━━━ Coverage ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Endpoints tested: 4 of 7 (57%)
+Methods tested:   GET ✅  POST ✅  PUT ✅  DELETE ✅  PATCH ❌
+Auth scenarios:  authenticated ✅  unauthenticated ❌  admin ❌
+```
+
+---
+
+## Security Constraints
+
+- **Never hardcode** API keys, tokens, or passwords in generated test scripts.
+- **Use env vars**: `process.env.TEST_API_KEY`, `process.env.API_BASE_URL`.
+- **Sanitize test payloads** — no actual SQL injection payloads that could damage data.
+- **Never run destructive tests** against production URLs without explicit user confirmation.
+- **Clean up created resources** at the end of every test flow (DELETE what was POSTed).
+
+---
+
+## Abort Conditions
+
+| Condition | Action |
+|---|---|
+| Server is not running | Prompt to run `/preview start` before continuing |
+| Destructive test (DELETE) on a production URL | Stop and confirm explicitly before executing |
+| Test step fails with 5xx | Halt the flow — server error is not a test assertion failure |
+| Auth step fails | Halt and report — remaining steps are invalid without a token |
+
+---
+
+## Cross-Workflow Navigation
+
+| After /api-tester reveals... | Go to |
+|---|---|
+| Soft-delete returning 200, should be 404 | `/fix` or `/debug` the query filter |
+| Endpoint returns 500 on valid input | `/debug` for root cause |
+| Security test: SQL injection returns 500 with DB error | ❌ CRITICAL → `/audit` immediately |
+| Rate limiting is missing | `/enhance` to add rate-limiting middleware |
+| All tests pass, ready for deploy | `/deploy` following pre-flight checklist |
+
+---
+
+## Hallucination Guard
+
+- **Scan route files first** — only test endpoints that exist in the codebase.
+- **Verify HTTP methods** — only use methods the route actually supports.
+- **Never invent response fields** — verify against schema, types, or actual response.
+- **Flag assumptions**: `// ASSUMPTION: this endpoint requires JWT auth based on middleware scan`.
+- **Never fabricate response times** — only report measured values.
+
+---
+
+## Usage
+
+```
+/api-tester CRUD flow for /api/posts
+/api-tester auth flow with JWT refresh
+/api-tester edge cases for /api/users
+/api-tester full lifecycle for /api/orders including payment
+/api-tester pagination for /api/products
+/api-tester rate limiting on /api/auth/login
+```

package/.agent/workflows/audit.md

@@ -0,0 +1,168 @@
+---
+description: Full project audit combining security, lint, schema, tests, dependencies, and bundle analysis
+---
+
+# /audit — Comprehensive Project Health Check
+
+$ARGUMENTS
+
+---
+
+This command runs a full audit of the project, combining all available analysis scripts in priority order. Use it before major releases, after onboarding to a new codebase, or whenever you need a complete health check.
+
+---
+
+## When to Use /audit
+
+| Situation | Recommended |
+|---|---|
+| Before a production deploy | `/audit` (full) |
+| After a dependency upgrade | `/audit` — focus on deps + security |
+| When onboarding to a new codebase | `/audit` — full scan first |
+| Single file just changed | `/review [file]` is faster |
+| Suspected security issue | `/audit` — security runs first |
+
+---
+
+## What Happens
+
+The audit runs in strict priority order. Critical issues block further checks:
+
+```
+Priority 1 → Security Scan         (CRITICAL: halts on failure)
+Priority 2 → Lint & Type Check     (BLOCKING for deploy on error)
+Priority 3 → Schema Validation     (advisory)
+Priority 4 → Test Suite            (advisory, marks task incomplete)
+Priority 5 → Dependency Analysis   (advisory)
+Priority 6 → Bundle Size Analysis  (advisory)
+```
+
+### Execution Commands
+
+Each priority maps to a script:
+
+```bash
+# Priority 1 — Security
+// turbo
+python .agent/scripts/security_scan.py .
+
+# Priority 2 — Lint
+// turbo
+python .agent/scripts/lint_runner.py .
+
+# Priority 3 — Schema
+// turbo
+python .agent/scripts/schema_validator.py .
+
+# Priority 4 — Tests
+// turbo
+python .agent/scripts/test_runner.py .
+
+# Priority 5 — Dependencies
+// turbo
+python .agent/scripts/dependency_analyzer.py . --audit
+
+# Priority 6 — Bundle
+// turbo
+python .agent/scripts/bundle_analyzer.py .
+```
+
+### Abort Conditions
+
+| Priority | Condition | Action |
+|---|---|---|
+| Security (P1) | CRITICAL findings | **HALT** — report and stop. Do not proceed until resolved. |
+| Lint (P2) | Errors (not warnings) | Continue but flag as **deploy-blocking** |
+| Schema (P3) | Any failure | Continue, report as advisory |
+| Tests (P4) | Failures | Continue, mark task as **incomplete** |
+| Deps (P5) | Vulnerabilities | Continue, flag severity level |
+| Bundle (P6) | Oversized assets | Continue, note thresholds exceeded |
+
+### Script Failure Handling
+
+```
+Script exits 0     → Success, continue pipeline
+Script exits 1     → Failure, report and decide: retry or skip?
+Script not found   → Skip with ⚠️ warning, do not block pipeline
+Script times out   → Kill process, report timeout, continue with next check
+```
+
+---
+
+## Scoped Audit (Optional)
+
+To audit a specific concern only, pass a flag:
+
+```bash
+/audit security only          → runs Priority 1 only
+/audit deps                   → runs Priority 5 only
+/audit lint                   → runs Priority 2 only
+/audit before deploy          → runs P1 + P2 + P4 (blocking gates only)
+/audit fresh codebase         → runs full suite and flags all advisory items
+```
+
+---
+
+## Audit Report Format
+
+After running all checks, produce a structured report:
+
+```markdown
+## 🔍 Project Audit Report — [date]
+
+### Security: [PASS ✅ / FAIL ❌]
+- [findings summary with severity: CRITICAL / HIGH / MEDIUM / LOW]
+
+### Lint & Types: [PASS ✅ / FAIL ❌]
+- [findings summary — errors vs. warnings distinguished]
+
+### Schema: [PASS ✅ / WARN ⚠️ / N/A]
+- [findings summary]
+
+### Tests: [PASS ✅ / FAIL ❌ / N/A]
+- [pass/fail counts + names of failing tests]
+
+### Dependencies: [CLEAN ✅ / ISSUES ⚠️]
+- [phantom imports, unused deps, known vulnerabilities with CVE IDs]
+
+### Bundle: [OK ✅ / LARGE ⚠️ / N/A]
+- [total size, heavy deps, suggested optimizations]
+
+### Verdict:
+[DEPLOY-READY ✅ / BLOCKED ❌ — reason]
+[Next recommended action]
+```
+
+---
+
+## Quick Audit
+
+For a faster check that skips bundle and schema:
+
+```bash
+// turbo
+python .agent/scripts/checklist.py .
+```
+
+---
+
+## Cross-Workflow Navigation
+
+| If the audit reveals... | Go to |
+|---|---|
+| Security CRITICAL findings | `/review [file]` for targeted analysis, then fix with `/generate` |
+| Many lint errors | `/fix` to auto-resolve lint and formatting issues |
+| Test failures | `/debug` to find root cause, then `/test` to add coverage |
+| Outdated or vulnerable dependencies | `/migrate` for framework/dependency upgrades |
+| Bundle size too large | `/tribunal-performance` for optimization review |
+
+---
+
+## Usage
+
+```
+/audit
+/audit this project before we deploy
+/audit focus on security and dependencies only
+/audit after upgrading to Next.js 15
+```

package/.agent/workflows/brainstorm.md

@@ -18,6 +18,18 @@ Before any `/create` or `/enhance` command when:
 - The problem is not yet well-defined
 - You want to evaluate multiple architectural paths
 - You need an honest assessment of tradeoffs before starting
+- Decision between two tools or approaches is unclear
+- The team needs to align on direction before work begins
+
+---
+
+## The Brainstorming Contract
+
+- Minimum **3 distinct approaches** will be surfaced — not variations of one idea, but genuinely different paths
+- Every approach is assessed on **specific tradeoffs**, not vague pros/cons
+- A **clear verdict** is given at the end — not "it depends" as a final answer
+- No code is written during brainstorming
+- Every tool or library named must be **real and documented**
 
 ---
 
@@ -25,18 +37,17 @@ Before any `/create` or `/enhance` command when:
 
 **First, the problem is clarified:**
 
-> "What specific outcome should exist that doesn't exist today? Who experiences the problem? What constraints are fixed?"
+> "What specific outcome should exist that doesn't exist today? Who experiences the problem? What constraints are fixed (stack, timeline, team size)?"
 
-If those aren't answered, I ask before going further.
+If those aren't answered, the session asks before going further.
 
-**Then, at least 3 distinct approaches are surfaced.** Not variations — genuinely different paths with different tradeoffs.
-
-**Each approach is assessed on:**
-- What problem it solves well
-- Where it creates friction
+**Then, at least 3 distinct approaches are surfaced**, each with:
+- How it works (mechanism, not just name)
+- Where it wins (specific advantage)
+- Where it struggles (real tradeoff — not "it can be complex")
 - Realistic effort level
 
-**Finally, one approach is recommended** — not hedged, not "it depends." A clear pick with a clear reason.
+**Finally, one approach is recommended** — not hedged, not "it depends." A clear pick with a clear reason tied to the user's stated constraints.
 
 ---
 
@@ -46,21 +57,24 @@ If those aren't answered, I ask before going further.
 ## Exploration: [Problem Statement]
 
 Why we're looking at this:
-[What's the actual friction being solved]
+[What's the actual friction or outcome gap being solved]
+
+User context:
+[Stack, constraints, team size, timeline — if known]
 
 ────────────────────────────────────────
 
 Approach 1 — [Name]
-[What this is and how it works]
+[What this is and how it actually works — mechanism, not just label]
 
 Where it wins:
-› [Specific advantage 1]
-› [Specific advantage 2]
+› [Specific advantage tied to this use case]
+› [Second specific advantage]
 
 Where it struggles:
-› [Real tradeoff — not a vague concern]
+› [Real tradeoff — operational cost, learning curve, limitation]
 
-Effort: ◼◼◽◽◽ (Low) | ◼◼◼◽◽ (Medium) | ◼◼◼◼◽ (High)
+Effort: ◼◽◽◽◽ Low | ◼◼◼◽◽ Medium | ◼◼◼◼◽ High
 
 ────────────────────────────────────────
 
@@ -75,19 +89,49 @@ Approach 3 — [Name]
 ────────────────────────────────────────
 
 Verdict:
-Approach [N] — because [specific reason tied to the user's stated constraints].
+Approach [N] — because [specific reason tied to the stated constraints].
+
+[If it truly depends on one variable]: 
+  → If [condition A]: Approach 1
+  → If [condition B]: Approach 2
 
 What direction should we go deeper on?
 ```
 
 ---
 
+## Questions That Unlock Better Exploration
+
+The brainstorming agent may ask:
+
+| Question | Why it matters |
+|---|---|
+| What's the scale? (RPS, users, data volume) | Changes which approaches are viable |
+| Is the team familiar with X? | Affects "effort" rating significantly |
+| What's the failure cost? | Changes risk tolerance and complexity budget |
+| Is this greenfield or adding to existing? | Existing constraints eliminate some options |
+| What's the time horizon? (prototype vs 5-year system) | Short-term vs long-term tradeoffs differ |
+
+---
+
 ## Hallucination Guard
 
-- No invented libraries or tools — every named option must be a real, documented choice
-- No performance claims without a cited benchmark
-- Every "pro" must be grounded in how this approach actually works — not wishful thinking
-- Assumptions about the user's codebase are always labeled: `[ASSUMPTION — verify first]`
+- **No invented libraries or tools** — every named option must be a real, documented choice
+- **No performance claims without a cited benchmark** — "X is faster" requires a source
+- **Every "pro" must be mechanically grounded** — how does this approach actually achieve the advantage?
+- **Assumptions about the user's codebase** are labeled: `[ASSUMPTION — verify before committing to this approach]`
+- **Effort estimates** are ranges, not single values, with a confidence label
+
+---
+
+## Cross-Workflow Navigation
+
+| After /brainstorm, the next step is... |
+|---|
+| Decision made → `/plan` to write the formal plan |
+| Decision made, simple task → `/generate` directly |
+| Decision made, large build → `/create` with known approach |
+| Still unclear → ask more Socratic questions before proceeding |
 
 ---
 
@@ -97,4 +141,6 @@ What direction should we go deeper on?
 /brainstorm caching layer for a high-traffic API
 /brainstorm auth approach for a multi-tenant SaaS
 /brainstorm how to structure shared state in a large React app
+/brainstorm whether to use a message queue or direct API calls for notifications
+/brainstorm database: PostgreSQL vs MongoDB for our event sourcing system
 ```