tribunal-kit 1.0.0

package/.agent/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/.agent/workflows/brainstorm.md

@@ -0,0 +1,100 @@
+---
+description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+---
+
+# /brainstorm — Idea Space
+
+$ARGUMENTS
+
+---
+
+This command puts the AI into **exploration mode** — no implementation, no code. The goal is to map the problem and surface real alternatives before committing to a path.
+
+---
+
+## When to Use This
+
+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
+
+---
+
+## What Happens
+
+**First, the problem is clarified:**
+
+> "What specific outcome should exist that doesn't exist today? Who experiences the problem? What constraints are fixed?"
+
+If those aren't answered, I ask 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
+- Realistic effort level
+
+**Finally, one approach is recommended** — not hedged, not "it depends." A clear pick with a clear reason.
+
+---
+
+## Response Template
+
+```
+## Exploration: [Problem Statement]
+
+Why we're looking at this:
+[What's the actual friction being solved]
+
+────────────────────────────────────────
+
+Approach 1 — [Name]
+[What this is and how it works]
+
+Where it wins:
+› [Specific advantage 1]
+› [Specific advantage 2]
+
+Where it struggles:
+› [Real tradeoff — not a vague concern]
+
+Effort: ◼◼◽◽◽ (Low) | ◼◼◼◽◽ (Medium) | ◼◼◼◼◽ (High)
+
+────────────────────────────────────────
+
+Approach 2 — [Name]
+...
+
+────────────────────────────────────────
+
+Approach 3 — [Name]
+...
+
+────────────────────────────────────────
+
+Verdict:
+Approach [N] — because [specific reason tied to the user's stated constraints].
+
+What direction should we go deeper on?
+```
+
+---
+
+## 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]`
+
+---
+
+## Usage
+
+```
+/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
+```

package/.agent/workflows/create.md

@@ -0,0 +1,86 @@
+---
+description: Create new application command. Triggers App Builder skill and starts interactive dialogue with user.
+---
+
+# /create — Build Something New
+
+$ARGUMENTS
+
+---
+
+This command starts a structured creation process. Code only appears after requirements are clear and a plan is approved.
+
+---
+
+## The Four Stages
+
+### Stage 1 — Understand (not optional)
+
+Before any planning begins, these four things must be established:
+
+```
+1. What is the user's actual goal?     (not the feature — the outcome)
+2. What stack are we working in?       (existing project or greenfield?)
+3. What is explicitly out of scope?    (boundary prevents scope creep)
+4. What's the observable done state?   (how do we know it's finished?)
+```
+
+If anything is unclear → ask. Do not skip to Stage 2 on assumptions.
+
+### Stage 2 — Plan
+
+Engage `project-planner` to write a structured plan:
+
+```
+Location: docs/PLAN-{task-slug}.md
+
+Must contain:
+  - Goal (one sentence)
+  - OOS list (what we won't build)
+  - Task table with: task / agent / dependency / done-condition
+  - Tribunal gate per task
+```
+
+**The plan is shown to the user before any code is written.**
+
+> ⏸️ "Here's the plan: `docs/PLAN-{slug}.md` — proceed?"
+> Do not advance until explicitly confirmed.
+
+### Stage 3 — Build (Parallel agents, after approval)
+
+| Layer | Agent | Review Gate |
+|---|---|---|
+| Data schema | `database-architect` | `/tribunal-database` |
+| API & server | `backend-specialist` | `/tribunal-backend` |
+| UI & components | `frontend-specialist` | `/tribunal-frontend` |
+| Test coverage | `test-engineer` | `logic + test-coverage` |
+
+Each agent's code goes through Tribunal before being shown to the user.
+
+### Stage 4 — Verify
+
+```
+Did the code satisfy every done-condition from Stage 1?   Y / N
+Did all Tribunal reviewers return APPROVED?               Y / N
+Are untested paths labeled // TODO with an explanation?  Y / N
+```
+
+All three must be Y before the task is declared done.
+
+---
+
+## Hallucination Rules
+
+- Every import must exist in the project's `package.json` or carry `// VERIFY: add to deps`
+- No invented framework methods — `// VERIFY: check docs for this method` on any uncertain call
+- No agent touches code outside its domain
+
+---
+
+## Usage
+
+```
+/create a REST API with JWT auth
+/create a React dashboard with real-time chart updates
+/create a complete user onboarding flow (frontend + backend + DB)
+```

package/.agent/workflows/debug.md

@@ -0,0 +1,104 @@
+---
+description: Debugging command. Activates DEBUG mode for systematic problem investigation.
+---
+
+# /debug — Root Cause Investigation
+
+$ARGUMENTS
+
+---
+
+This command switches the AI into **investigation mode**. No fixes are suggested until the root cause is identified. No random changes. No guessing.
+
+---
+
+## The Investigation Contract
+
+> "A fix without a root cause is a patch on a symptom. It will fail again."
+
+The `debugger` agent follows this sequence without skipping steps:
+
+---
+
+## Investigation Sequence
+
+**Collect evidence first:**
+- Exact error text (full stack trace, not a summary)
+- Minimum reproduction steps
+- Last known-good state (commit, date, config)
+- Recent changes (code, dependency updates, env vars, infrastructure)
+
+**Map possible causes — label them honestly:**
+
+```
+Cause A: [what it is] — Likelihood: High / Medium / Low
+Cause B: [what it is] — Likelihood: High / Medium / Low
+Cause C: [what it is] — Likelihood: High / Medium / Low
+```
+
+Every entry labeled as a **hypothesis**, not a diagnosis.
+
+**Test causes one at a time:**
+Check one. Mark resolved or eliminated. Move to next. Never test two simultaneously.
+
+**Find the root cause:**
+The thing that, if changed, prevents the entire failure chain. Fixing a symptom doesn't count.
+
+**Apply a targeted fix + prevent recurrence:**
+One change. Then verify. Then add a regression test.
+
+---
+
+## Report Format
+
+```
+━━━ Debug Report ━━━━━━━━━━━━━━━━━━━━━━━
+
+Symptom:      [what the user sees]
+Error:        [exact message or trace]
+Reproduced:   [Yes | No | Sometimes]
+Last working: [commit / date / known-good state]
+
+━━━ Hypotheses ━━━━━━━━━━━━━━━━━━━━━━━
+
+H1 [High]   — [cause and why it's likely]
+H2 [Medium] — [cause and why it's possible]
+H3 [Low]    — [cause and why it's a stretch]
+
+━━━ Investigation ━━━━━━━━━━━━━━━━━━━
+
+H1: checked [what was examined] → ✅ Confirmed root cause
+H2: ruled out — [evidence against it]
+
+━━━ Root Cause ━━━━━━━━━━━━━━━━━━━━━
+
+[Single sentence explaining WHY this happened]
+
+━━━ Fix ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Before:  [original code]
+After:   [corrected code]
+
+Regression test: [what test was added to prevent this]
+Similar patterns: [anywhere else in the codebase this might exist]
+```
+
+---
+
+## Hallucination Guard
+
+- Every hypothesis is explicitly labeled as a hypothesis — never as confirmed fact
+- Proposed fixes only use real, documented APIs — `// VERIFY: check method exists` on uncertainty
+- One change per fix — multi-file rewrites presented as "a debug session" are a red flag
+- Debug logging added during investigation must be removed before the fix is presented
+
+---
+
+## Usage
+
+```
+/debug TypeError: Cannot read properties of undefined
+/debug API returns 500 only in production
+/debug useEffect runs on every render instead of once
+/debug login works locally but fails in CI
+```

package/.agent/workflows/deploy.md

@@ -0,0 +1,102 @@
+---
+description: Deployment command for production releases. Pre-flight checks and deployment execution.
+---
+
+# /deploy — Production Release
+
+$ARGUMENTS
+
+---
+
+This command runs a structured, gate-enforced deployment sequence. Nothing reaches production without passing all three gates.
+
+---
+
+## The Non-Negotiable Rule
+
+> **The Human Gate is never skipped.**
+> Even if every automated gate passes, a human sees the deployment summary and explicitly approves before anything executes.
+
+---
+
+## Three-Gate Sequence
+
+### Gate 1 — Security Sweep
+
+`security-auditor` scans all files in the deployment diff:
+
+```
+Expected clean state:
+  ✅ No secrets or credentials in any changed file
+  ✅ No unparameterized query added
+  ✅ No new CVE-affected dependency introduced
+  ✅ No debug endpoints left active
+```
+
+**If any Critical or High issue is found → deployment is blocked.**
+The issue must be fixed and re-scanned before proceeding.
+
+### Gate 2 — Tribunal Verification
+
+`/tribunal-full` runs on all changed code:
+
+```
+  ✅ logic-reviewer: APPROVED
+  ✅ security-auditor: APPROVED
+  ✅ dependency-reviewer: APPROVED
+  ✅ type-safety-reviewer: APPROVED
+```
+
+**Any REJECTED verdict → deployment blocked.** Fix and re-review.
+
+### Gate 3 — Human Approval
+
+A deployment summary is shown before execution:
+
+```
+━━━ Release Summary ━━━━━━━━━
+Target:        [staging | production]
+Files changed: [N]
+Security gate: ✅ Passed
+Tribunal gate: ✅ All APPROVED
+Tests:         ✅ N passed
+
+Rollback to:   [previous tag / commit SHA]
+Rollback time: [estimate]
+DB-safe:       [Yes | No — explain]
+
+Proceed with deployment? (Y to execute | N to cancel)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Rollback is a Prerequisite
+
+Before any deployment executes, the rollback plan must be established:
+
+```
+What does this roll back to?          → [tag or SHA]
+How long will rollback take?          → [estimate]
+Is the DB migration reversible?       → Yes | No
+Who gets notified on rollback?        → [name or channel]
+```
+
+No rollback plan = no deployment.
+
+---
+
+## Hallucination Guard
+
+- No invented CLI flags — `# VERIFY: check docs for this flag` on any uncertain command
+- All secrets via environment variables — never hardcoded in deploy configs
+- All images tagged with a specific version — `latest` is forbidden in production configs
+
+---
+
+## Usage
+
+```
+/deploy to staging
+/deploy to production after staging validation
+```

package/.agent/workflows/enhance.md

@@ -0,0 +1,107 @@
+---
+description: Add or update features in existing application. Used for iterative development.
+---
+
+# /enhance — Extend What Exists
+
+$ARGUMENTS
+
+---
+
+This command adds to or improves existing code without breaking what already works. Enhancement is not greenfield — the existing system shapes what can be done and how.
+
+---
+
+## First Rule: Read, Then Write
+
+> Never modify code you haven't read.
+> Never modify a function without checking what calls it.
+
+The first step of every enhancement is a reading pass — not a writing pass.
+
+---
+
+## Enhancement Sequence
+
+### Step 1 — Map the Impact Zone
+
+```
+Files to change:      [list]
+Functions affected:   [list]
+Callers of those:     [list — these must remain unbroken]
+Tests currently covering them: [list]
+```
+
+This map must exist before any file is opened for editing.
+
+### Step 2 — Define What Changes vs What Stays
+
+```
+Adding:      [new capability being added]
+Modifying:   [existing behavior being changed]
+Preserving:  [things that must not change]
+```
+
+Any change to a public interface (function signature, API response shape, exported type) triggers an update of all callers.
+
+### Step 3 — Implement Through Tribunal Gate
+
+| Enhancement Type | Gate |
+|---|---|
+| Backend logic | `/tribunal-backend` |
+| Frontend/UI | `/tribunal-frontend` |
+| DB queries | `/tribunal-database` |
+| Cross-domain | `/tribunal-full` |
+
+The code goes through Tribunal before being shown.
+
+### Step 4 — Regression Safety Check
+
+```
+Existing tests: ✅ still pass (none were broken)
+New tests added: ✅ covering new behavior
+Callers updated: ✅ if any interface changed
+```
+
+All three must be true before the enhancement is considered complete.
+
+---
+
+## Response Template
+
+```
+Enhancement: [What was added/changed]
+
+Impact Zone:
+  Changed: [files]
+  Callers updated: [files, or "none — interface preserved"]
+
+Tribunal result:
+  [reviewer]: [APPROVED | REJECTED — reason]
+
+Regression risk:
+  🟢 Low — new path only, no existing path changed
+  🟡 Medium — shared code modified, callers reviewed
+  🔴 High — interface changed, all callers updated
+
+Changes:
+  [diff]
+```
+
+---
+
+## Hallucination Guard
+
+- **Read existing code before describing it** — never assume what a function does from its name
+- **Preserved interfaces must stay identical** — adding a required parameter breaks every caller silently
+- **Unknown patterns get `// VERIFY`** — never guess at a codebase convention
+
+---
+
+## Usage
+
+```
+/enhance add pagination to the users list API endpoint
+/enhance add rate limiting to all authentication routes
+/enhance upgrade the search component to support filters
+```