tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/plan.md

@@ -1,151 +1,173 @@
 ---
-description: Create project plan using project-planner agent. No code writing — only plan file generation.
+description: Create project plan using project-planner agent. 4-phase approach: Analyze → Research → Plan Document → Human Gate. NO code writing — only plan file generation. Writing begins only after explicit human approval.
 ---
 
-# /plan — Write the Plan First
+# /plan — Strategic Implementation Planning
 
 $ARGUMENTS
 
 ---
 
-This command produces one thing: **a structured plan file**. Nothing is implemented. No code is written. The plan is the output.
+## When to Use /plan
+
+|Use `/plan` when...|Skip plan and go to...|
+|:---|:---|
+|New feature with unclear scope|Simple, well-defined single file edit → just edit|
+|Multi-file change with dependencies|Generating a snippet → `/generate`|
+|Architecture decisions to make|Fixing a bug → `/debug`|
+|Risk needs to be assessed first|Adding to an existing feature → `/enhance`|
+|Stakeholder requirements → technical spec||
 
 ---
 
-## When to Use /plan vs Other Commands
+## The Plan Contract: No Code Before Approval
 
-| Use `/plan` when... | Use something else when... |
-|---|---|
-| Requirements are unclear or large | You already know what to build → `/create` |
-| Multi-agent work needs coordination | Single function needed → `/generate` |
-| You want written scope agreement before coding | Ready to build immediately → `/create` |
-| Stakeholder review is needed before work starts | Just a quick discussion → ask directly |
+```
+The project-planner agent is the only agent active in /plan mode.
+It does NOT write code.
+It DOES read existing code to inform the plan.
+No other agents activate, no code is generated.
+```
 
 ---
 
-## Why Plan Before Building
+## Phase 1 — Socratic Gate (5 Questions)
 
-> Tasks without plans get rebuilt three times.
-> Plans expose ambiguity before it becomes broken code.
+```
+1. GOAL: What specific outcome defines success? (not "add a feature" — a measurable outcome)
+2. USERS: Who exactly uses this? What do they currently do without this feature?
+3. SCOPE: What is explicitly OUT of scope for this version/sprint?
+4. RISK: What is the highest-risk assumption this plan rests on?
+5. STACK: Is the technology stack decided? Any constraints?
+```
 
----
+If any answer is "I don't know" → **ask before writing the plan document.**
 
-## How It Works
+---
 
-### Gate: Clarify Before You Plan
+## Phase 2 — Research (Read Before Planning)
 
-The `project-planner` agent asks — and gets answers to — these four questions before writing a single line of the plan:
+```bash
+# What currently exists?
+ls -la src/      # Understand directory structure
+cat package.json # Understand actual dependencies
+cat tsconfig.json # Understand TypeScript config and path aliases
+git log --oneline -5 # Recent work context
 
+# Domain-specific reads:
+cat prisma/schema.prisma    # If DB changes planned
+cat src/middleware.ts        # If auth changes planned
+cat src/lib/auth.ts          # If auth changes planned
 ```
-1. What outcome needs to exist that doesn't exist today?
-2. What are the hard constraints? (stack, existing code, deadline)
-3. What's explicitly not being built in this version?
-4. How will we confirm it's done? (observable done condition)
-```
-
-If any answer is "I don't know" — those are clarified **before** the plan is written, not after.
-
-> ⚠️ An unclear "done condition" is the most common cause of scope creep. It must be specific and observable.
 
 ---
 
-### Plan File Creation
+## Phase 3 — Wave Decomposition
+
+Plans execute in topological waves:
 
 ```
-Location: docs/PLAN-{task-slug}.md
-
-Slug naming rules:
-  - Pull 2–3 key words from the request
-  - Lowercase + hyphens
-  - Max 30 characters
-  Examples:
-    "build auth with JWT"       → PLAN-auth-jwt.md
-    "shopping cart checkout"    → PLAN-cart-checkout.md
-    "multi-tenant user roles"   → PLAN-user-roles.md
+Wave 1 — Foundation (always first)
+├── Database schema changes (must precede all code)
+├── Shared types and Zod schemas (must precede callers)
+└── Auth/middleware changes (must precede protected routes)
+
+Wave 2 — Core Implementation
+├── API routes / Server Actions (depends on Wave 1 schema)
+├── Business logic layer
+└── Unit tests for Wave 1
+
+Wave 3 — Integration
+├── Frontend components (depends on Wave 2 API)
+├── Integration tests
+└── E2E tests for critical paths
+
+Wave 4 — Polish
+├── Performance optimization
+├── Accessibility audit
+└── Deploy prep
 ```
 
 ---
 
-## Plan File Structure
+## Phase 4 — Implementation Plan Document
 
 ```markdown
-# Plan: [Feature Name]
-
-## What Done Looks Like
-[Observable outcome — one specific, testable sentence]
-
-## Won't Include in This Version
-- [Explicit exclusion 1]
-- [Explicit exclusion 2]
-
-## Unresolved Questions
-- [Item needing external confirmation: VERIFY]
-
-## Estimates (Ranges + Confidence)
-| Task | Optimistic | Realistic | Pessimistic | Confidence |
-|------|-----------|-----------|-------------|------------|
-| DB schema | 30min | 1h | 2h | High |
-| API layer | 2h | 4h | 8h | Medium |
-| Frontend | 3h | 6h | 12h | Low |
-
-## Task Table
-| # | Task | Agent | Depends on | Done when |
-|---|------|-------|-----------|-----------| 
-| 1 | DB schema | database-architect | none | migration runs |
-| 2 | API routes | backend-specialist | #1 | returns 201 |
-| 3 | Frontend component | frontend-specialist | #2 | renders without errors |
-| 4 | Tests | test-engineer | #2 | all specs pass |
-
-## Review Gates
-| Task | Tribunal |
-|---|---|
-| #1 schema | /tribunal-database |
-| #2 API | /tribunal-backend |
-| #3 UI | /tribunal-frontend |
-| #4 tests | test-coverage-reviewer |
+# Implementation Plan: [Feature Name]
+
+## Goal
+[Single sentence: what is true when this is complete]
+
+## User Review Required
+> [!IMPORTANT]
+[Breaking changes, architectural choices needing approval]
+
+## Research Findings
+- [what currently exists that's relevant]
+- [constraints discovered]
+
+## Proposed Changes
+
+### Wave 1 — Foundation
+#### [MODIFY] prisma/schema.prisma
+[What changes and why]
+
+#### [NEW] src/lib/validators/newFeature.ts
+[What this creates]
+
+### Wave 2 — Core
+#### [NEW] src/app/api/new-feature/route.ts
+[What this creates]
+
+## Out of Scope (This Version)
+- [explicit exclusion]
+
+## Verification Plan
+- [ ] npx tsc --noEmit passes
+- [ ] npm test passes
+- [ ] [specific behavioral assertion]
 ```
 
 ---
 
-### After the File is Written
+## Human Gate — Mandatory Before Execution
 
-```
-✅ Plan written: docs/PLAN-{slug}.md
+After the plan document is written:
 
-Review it, then:
-  /create    → Begin full implementation (uses this plan)
-  /generate  → Implement a single task from the table
-  /orchestrate → Coordinate all agents across the full plan
 ```
+━━━ Plan Ready for Review ━━━━━━━━━━━━━━━━━
 
----
+[summary of what will change across N files in N waves]
 
-## Hallucination Guard
+Approve?
+Y = begin execution (proceed to /generate or /enhance)
+N = discard plan
+R = revise with feedback
+```
 
-- Every tool, library, or API mentioned in the plan must be **real and verified** before being listed
-- Time estimates are **ranges with confidence labels** — never single-point guarantees
-- External dependencies that aren't confirmed get a `[VERIFY: check this exists]` tag
-- The done condition is **observable and specific** — "it works" is not a done condition
+**Zero code is written until "Y" is received.**
 
 ---
 
-## Cross-Workflow Navigation
+## Anti-Pattern Guard
 
-| After /plan produces the file... | Go to |
-|---|---|
-| Ready to build the full plan | `/create` reads the plan and starts building |
-| Need a single task implemented | `/generate [task description]` |
-| Multi-agent coordination needed | `/orchestrate` to run the plan as a managed build |
-| Need to review existing code first | `explorer-agent` before committing to the plan |
+```
+❌ Never write code during /plan mode
+❌ Never assume what the user wants — ask if unclear
+❌ Never plan without reading the existing codebase first
+❌ Never omit the Out of Scope section (it's how scope creep is prevented)
+❌ Never skip the Socratic Gate — even for "simple" features
+❌ Never write a plan that requires understanding unexplored files
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/plan REST API with user auth
-/plan dark mode toggle for the settings page
-/plan multi-tenant account switching
-/plan event-driven notification system with queues
-/plan admin dashboard with user management and analytics
+/plan a user notification system with email + in-app notifications
+/plan migrate the authentication from next-auth v4 to v5
+/plan add Stripe subscription billing to the existing user model
+/plan refactor the monolithic api.ts into domain-specific route files
+/plan implement real-time collaborative editing using CRDTs
 ```

package/.agent/workflows/preview.md

@@ -1,137 +1,80 @@
 ---
-description: Preview server start, stop, and status check. Local development server management.
+description: Preview server start, stop, and status check. Local development server management. Uses auto_preview.py for automated lifecycle control. Shows current URL and hot-reload status.
 ---
 
-# /preview — Local Server Control
+# /preview — Local Development Server
 
 $ARGUMENTS
 
 ---
 
-Start, stop, or check the development server so you can verify generated code before approving it for your codebase. Always verify in a running local environment before approving the Human Gate.
-
----
-
-## Sub-commands
+## 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
-/preview logs      → Show recent dev server output
+/preview start    → Start the local dev server
+/preview stop     → Stop the local dev server
+/preview restart  → Restart the dev server (after config changes)
+/preview status   → Show current server status and URL
 ```
 
 ---
 
-## On Start
+## Execution
 
 ```bash
-# Step 1: Check if port is already in use (warn if yes — don't kill blindly)
-netstat -an | grep :[port]
-
-# Step 2: Read package.json to find the correct dev command
-# Check: scripts.dev → scripts.start → scripts.serve (in priority order)
-
-# Step 3: Launch via auto_preview.py wrapper
-// turbo
+# Start
 python .agent/scripts/auto_preview.py start
 
-# Step 4: Wait for ready signal (port open or "ready"/"listening" in output)
-# Timeout: 30 seconds — report failure if not ready
-```
-
-**Output after start:**
-
-```
-━━━ Server Started ━━━━━━━━━━━━━━━━━━━━
-URL:     http://localhost:[port]
-Command: [actual command used]
-PID:     [process id]
-
-Run /preview stop to shut down.
-```
-
----
-
-## On Stop
-
-```bash
-// turbo
+# Stop
 python .agent/scripts/auto_preview.py stop
-```
 
-```
-Step 1: Locate running process by port or PID file
-Step 2: Send graceful shutdown signal (SIGTERM)
-Step 3: Wait up to 10 seconds — force kill (SIGKILL) if needed
-Step 4: Confirm port is released
+# Restart
+python .agent/scripts/auto_preview.py restart
 
-━━━ Server Stopped ━━━━━━━━━━━━━━━━━━━━
-Port [N] is now free.
+# Status
+python .agent/scripts/auto_preview.py status
 ```
 
 ---
 
-## On Status
+## Server Start Output
 
-```bash
-// turbo
-python .agent/scripts/auto_preview.py status
 ```
+━━━ Dev Server Starting ━━━━━━━━━━━━━━━━━━
 
-```
-🟢  Running — http://localhost:[port]  (PID [N], uptime: [duration])
-🔴  Not running — no active process found on port [N]
-```
-
----
-
-## On Logs
+Command:   npm run dev
+URL:       http://localhost:3000
+Status:    ✅ Running
 
-```
-/preview logs      → Show last 50 lines of dev server output
-/preview logs --error → Show only error lines
+Hot reload: ✅ Enabled
+TypeScript: ✅ Type checking active
 ```
 
 ---
 
 ## Common Issues
 
-| Problem | What to check |
-|---|---|
-| Port already in use | Run `/preview status` — another process may be running |
-| Server starts but page is blank | Check for build errors in logs with `/preview logs --error` |
-| Server crashes immediately | Check `package.json` for the correct script name |
-| Slow start | Normal for Next.js first compile — wait for "ready" message |
-
----
-
-## 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 config** — never hardcoded to 3000
-- **No invented server flags** added to the start command
-- If the server fails to start: report the actual error output, not a guessed reason
-
----
+```
+Port 3000 in use:
+  → Kill: taskkill /F /IM node.exe  (Windows)
+  → OR:   lsof -i:3000 && kill -9 [PID]  (Mac/Linux)
+  → OR:   Run on different port: PORT=3001 npm run dev
 
-## Cross-Workflow Navigation
+Build error on start:
+  → Run: npx tsc --noEmit to see TypeScript errors
+  → Fix errors first, then /preview start
 
-| After /preview start... | Do this |
-|---|---|
-| Verify generated code visually | Open the URL, interact, then approve the Human Gate |
-| Something looks wrong visually | `/debug` the rendering issue |
-| Server won't start | Check `/preview logs --error` for the actual failure |
+Config change not reflected:
+  → /preview restart (hot reload doesn't pick up next.config.js changes)
+```
 
 ---
 
-## Usage
+## When to Use /preview
 
-```bash
-/preview start
-/preview stop
-/preview status
-/preview restart
-/preview logs
-```
+|Use `/preview` when...||
+|:---|:---|
+|After code generation to visually verify|Start: `/preview start`|
+|Config file was changed|Restart: `/preview restart`|
+|Done working for the session|Stop: `/preview stop`|
+|Checking if server is active|Status: `/preview status`|