tribunal-kit 2.4.6 → 3.1.0

package/.agent/workflows/brainstorm.md

@@ -1,146 +1,110 @@
 ---
-description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+description: Structured brainstorming for projects and features. Uses Socratic questioning to explore multiple options before committing to an approach. No implementation during this phase — only exploration.
 ---
 
-# /brainstorm — Idea Space
+# /brainstorm — Structured Idea Exploration
 
 $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 /brainstorm
 
----
-
-## 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
-- Decision between two tools or approaches is unclear
-- The team needs to align on direction before work begins
+|Use `/brainstorm` when...|Move to...|
+|:---|:---|
+|Multiple valid approaches exist|After decision → `/plan`|
+|You're unsure of the best architecture|After plan approval → `/generate`|
+|Exploring tradeoffs before committing|Confirmed approach → `/create`|
+|Looking for second opinions on design||
 
 ---
 
-## 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**
-
----
-
-## 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 (stack, timeline, team size)?"
+## Phase 1 — Question First
 
-If those aren't answered, the session asks before going further.
-
-**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 tied to the user's stated constraints.
-
----
-
-## Response Template
+Before generating ideas, ask 3 clarifying questions:
 
 ```
-## Exploration: [Problem Statement]
-
-Why we're looking at this:
-[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 actually works — mechanism, not just label]
-
-Where it wins:
-› [Specific advantage tied to this use case]
-› [Second specific advantage]
-
-Where it struggles:
-› [Real tradeoff — operational cost, learning curve, limitation]
-
-Effort: ◼◽◽◽◽ Low | ◼◼◼◽◽ Medium | ◼◼◼◼◽ High
+1. What constraint is non-negotiable? (timeline, tech stack, cost, performance)
+2. What has already been tried and ruled out?
+3. What does "success" look like for this decision?
+```
 
-────────────────────────────────────────
+---
 
-Approach 2 — [Name]
-...
+## Phase 2 — Generate 3 Distinct Options
 
-────────────────────────────────────────
+Present minimum 3 meaningfully different approaches:
 
-Approach 3 — [Name]
-...
+```
+Option A: [Conservative approach]
+  Pros: [why this works]
+  Cons: [what it sacrifices]
+  Effort: [Low / Medium / High]
+  Best for: [when this is the right choice]
+
+Option B: [Balanced approach]
+  Pros: [why this works]
+  Cons: [what it sacrifices]
+  Effort: [Low / Medium / High]
+  Best for: [when this is the right choice]
+
+Option C: [Ambitious approach]
+  Pros: [why this works]
+  Cons: [what it sacrifices]
+  Effort: [Low / Medium / High]
+  Best for: [when this is the right choice]
+```
 
-────────────────────────────────────────
+---
 
-Verdict:
-Approach [N] — because [specific reason tied to the stated constraints].
+## Phase 3 — Socratic Analysis
 
-[If it truly depends on one variable]: 
-  → If [condition A]: Approach 1
-  → If [condition B]: Approach 2
+After presenting options, probe with questions that reveal hidden tradeoffs:
 
-What direction should we go deeper on?
+```
+□ What happens when this scales to 10x current load?
+□ What's the maintenance cost 12 months from now?
+□ Which option fails most gracefully under the worst case?
+□ Which option are you most likely to regret?
+□ What's the opportunity cost of each option?
 ```
 
 ---
 
-## Questions That Unlock Better Exploration
+## Phase 4 — Recommendation (Evidence-Based)
 
-The brainstorming agent may ask:
+After exploration, state a recommendation:
 
-| 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 |
-
----
+```
+Recommended: Option [B]
 
-## Hallucination Guard
+Reasoning:
+- [specific reason 1 tied to stated constraints]
+- [specific reason 2]
+- [specific tradeoff you're accepting and why]
 
-- **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
+NOT recommended because [reason Option A/C is worse for this specific context]
+```
 
 ---
 
-## Cross-Workflow Navigation
+## Brainstorm Guard
 
-| 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 |
+```
+❌ Never present a single option as if it's the only choice
+❌ Never recommend without explaining WHY in terms of the stated constraints
+❌ Never skip the Socratic probing — it surfaces assumptions
+❌ Never proceed to implementation in /brainstorm mode — use /plan after
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/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
+/brainstorm real-time collaboration: WebSockets vs Server-Sent Events vs CRDTs
+/brainstorm caching strategy: Redis vs in-memory vs CDN for our API responses
+/brainstorm auth: next-auth vs Clerk vs custom JWT for our SaaS app
+/brainstorm state management: Zustand vs Redux vs TanStack Query
+/brainstorm monolith vs microservices for our current team size
 ```

package/.agent/workflows/changelog.md

@@ -1,144 +1,112 @@
 ---
-description: Auto-generate changelogs from git history. Categorizes changes by type and follows Keep a Changelog format.
+description: Auto-generate changelogs from git history. Categorizes commits by type (feat/fix/chore/breaking) and follows Keep a Changelog format. Requires conventional commit messages for accurate categorization.
 ---
 
-# /changelog — Generate Change History
+# /changelog — Git History to Changelog
 
 $ARGUMENTS
 
 ---
 
-This command generates a structured changelog from git history. It reads real commits and categorizes them — it never invents changes that don't exist.
+## When to Use /changelog
+
+|Use `/changelog` when...||
+|:---|:---|
+|Preparing a release|Generate for specific version range|
+|Documenting recent changes|Generate since last tag|
+|Onboarding someone to codebase history|Generate entire history|
 
 ---
 
-## When to Use This
+## Commit Convention (Required for Accuracy)
 
-- Before a release to document what changed
-- When preparing release notes for stakeholders
-- To create or update `CHANGELOG.md`
-- To summarize work completed in a sprint or between two tags
+```
+Format: <type>(<scope>): <description>
+
+Types:
+  feat:     New functionality (appears in "Added")
+  fix:      Bug fix (appears in "Fixed")
+  chore:    Maintenance, deps (appears in "Changed")
+  docs:     Documentation only
+  perf:     Performance improvement (appears in "Changed")
+  refactor: Internal restructuring (appears in "Changed")
+  test:     Test-only changes
+  BREAKING CHANGE: Footer or body annotation (appears in "Breaking Changes")
+```
 
 ---
 
-## What Happens
-
-### Stage 1 — Determine Range
-
-Default range: commits since the last tag. Override with:
+## Git Log Commands
 
 ```bash
-# Default: since last tag
-// turbo
-git log $(git describe --tags --abbrev=0)..HEAD --oneline --format="%h %ad %s" --date=short
+# Since last tag
+git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
 
-# Last N commits
-git log -n 20 --oneline --format="%h %ad %s" --date=short
+# Since a specific date
+git log --since="2026-01-01" --oneline --no-merges
 
-# Between specific tags
-git log v1.0.0..v2.0.0 --oneline --format="%h %ad %s" --date=short
+# Since specific commit
+git log abc123def..HEAD --oneline --no-merges
 
-# Since a date
-git log --since="2025-01-01" --oneline --format="%h %ad %s" --date=short
+# With full commit message (for BREAKING CHANGE in body)
+git log $(git describe --tags --abbrev=0)..HEAD --format="%H %s%n%b"
 ```
 
-If no tags exist: default to last 20 commits and flag no tags found.
-
-### Stage 2 — Collect and Categorize
-
-Read the git log and categorize each commit by prefix:
-
-| Commit Prefix | Category | Icon |
-|---|---|---|
-| `feat:`, `feature:`, `add:` | Features | ✨ |
-| `fix:`, `bugfix:`, `hotfix:` | Fixes | 🐛 |
-| `refactor:`, `cleanup:` | Refactors | ♻️ |
-| `docs:`, `doc:` | Documentation | 📝 |
-| `test:`, `tests:` | Tests | ✅ |
-| `chore:`, `build:`, `ci:` | Maintenance | 🔧 |
-| `perf:`, `performance:` | Performance | ⚡ |
-| `security:`, `sec:` | Security | 🔒 |
-| `BREAKING:`, `breaking:`, `!` after scope | Breaking Changes | 💥 |
-| (no recognized prefix) | Other | 📦 |
-
-### Stage 3 — Generate Output
+---
 
-Output follows [Keep a Changelog](https://keepachangelog.com/) format:
+## Output Format (Keep a Changelog)
 
 ```markdown
 # Changelog
 
-## [Unreleased] — YYYY-MM-DD
-
-### 💥 Breaking Changes
-- `abc1234` — Description of breaking change
+All notable changes to this project will be documented in this file.
 
-### ✨ Features
-- `def5678` — Description of new feature
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-### 🐛 Fixes
-- `ghi9012` — Description of bug fix
+## [Unreleased]
 
-### ⚡ Performance
-- `jkl3456` — Description of performance improvement
+## [1.2.0] — 2026-04-02
 
-### 🔒 Security
-- `mno7890` — Description of security fix
+### Breaking Changes
+- **auth**: JWT token format changed — clients must re-authenticate ([abc123](link))
 
-### ♻️ Refactors
-- `pqr1234` — Description of refactor
+### Added
+- User notification system with email and in-app alerts ([def456](link))
+- Pagination on /api/users endpoint with meta.total in response ([ghi789](link))
 
-### 📝 Documentation
-- `stu5678` — Description of docs change
+### Fixed
+- JWT verify no longer accepts 'none' algorithm ([jkl012](link))
+- Checkout form no longer loses data on page refresh ([mno345](link))
 
-### 🔧 Maintenance
-- `vwx9012` — Description of chore/dependency bump
-```
-
-### Stage 4 — Review and Save
-
-Present the generated summary before writing:
+### Changed
+- Upgraded Prisma 5 to 6 — findOne calls migrated to findUnique ([pqr678](link))
+- Bundle size reduced 64% via dynamic import for chart library ([stu901](link))
 
-```
-📋 Generated changelog from [range]:
-  💥 1 breaking change
-  ✨ 3 features
-  🐛 5 fixes
-  📦 2 uncategorized commits
+## [1.1.0] — 2026-03-15
+[...]
 
-Save to CHANGELOG.md? [Y = append | N = cancel | S = stdout only]
+[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
 ```
 
-> ⏸️ **Human Gate** — CHANGELOG.md is not written without confirmation.
-
 ---
 
-## Hallucination Guard
-
-- **Only include commits that actually exist** in git history — read from `git log`, never invent
-- **Never summarize or paraphrase** ambiguous commit messages — include verbatim if unclear
-- **Always show the commit hash** for traceability beside each entry
-- **Never infer intent** from a commit message — report what was written, not what it "probably meant"
-- Breaking changes need to be explicitly labeled in the commit — never infer breakage from code
+## Semver Decision Guide
 
----
-
-## Cross-Workflow Navigation
-
-| After /changelog reveals... | Go to |
-|---|---|
-| Many uncategorized commits | Enforce commit conventions in the team |
-| Breaking changes need documentation | Update API docs or migration guides |
-| Ready for release | `/deploy` to complete the release pipeline |
+```
+MAJOR (1.0.0 → 2.0.0): Any BREAKING CHANGE
+MINOR (1.0.0 → 1.1.0): New features, backward-compatible (feat:)  
+PATCH (1.0.0 → 1.0.1): Bug fixes only (fix:)
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/changelog since the last release
-/changelog for the last 50 commits
-/changelog between v1.0 and v2.0
-/changelog generate and save to CHANGELOG.md
-/changelog sprint summary since 2025-03-01
+/changelog since last release tag
+/changelog for version 1.2.0 including all commits since v1.1.0
+/changelog since 2026-01-01
+/changelog what changed in the authentication module this month
 ```

package/.agent/workflows/create.md

@@ -1,139 +1,124 @@
 ---
-description: Create new application command. Triggers App Builder skill and starts interactive dialogue with user.
+description: Create new application command. Triggers full stack creation from requirements gathering → stack selection → scaffolding → Tribunal code generation. Everything through the pipeline before writing a single file.
 ---
 
-# /create — Build Something New
+# /create — Full Application Builder
 
 $ARGUMENTS
 
 ---
 
-This command starts a structured creation process. **Code only appears after requirements are clear and a plan is approved.** Building before understanding is the number one source of wasted work.
+## When to Use /create
 
----
-
-## When to Use /create vs Other Commands
-
-| Use `/create` when... | Use something else when... |
-|---|---|
-| Starting something from scratch | Extending existing code → `/enhance` |
-| Building a complete feature (frontend + backend + DB) | Single function needed → `/generate` |
-| You need a plan before code | Plan only, no code → `/plan` |
-| Multi-domain coordination required | Single domain → `/generate` with right tribunal |
+|Use `/create` when...|Use something else when...|
+|:---|:---|
+|Starting a new project from scratch|Adding to an existing project → `/enhance`|
+|No codebase exists yet|Generating a focused code snippet → `/generate`|
+|You need a working scaffold with structure|Planning and understanding → `/plan`|
 
 ---
 
-## The Four Stages
+## Phase 1 — Requirements Gathering (Socratic Gate)
 
-### Stage 1 — Understand (not optional)
-
-Before any planning begins, these four things must be established:
+Before a single line of code is written, the `app-builder` agent asks these questions:
 
 ```
-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?)
+1. What does this application DO? (one sentence — the core user action)
+2. Who uses it? (end users, internal team, API consumers)
+3. What is the target platform? (web, mobile, server, CLI, desktop)
+4. Are there any tech constraints? (must use X, must run on Y)
+5. What data does it store? (users, products, documents, real-time events)
+6. Is authentication required? (yes/no/type: email, OAuth, API key)
+7. Are there external integrations? (Stripe, OpenAI, Twilio, etc.)
 ```
 
-**If anything is unclear → ask. Do not skip to Stage 2 on assumptions.**
-
-Minimum Socratic gate questions by project type:
-
-| Project type | Questions to ask before planning |
-|---|---|
-| API / backend | Auth strategy? Database? Error format? Rate limiting? |
-| Frontend / UI | Framework? Design system? State management? SSR? |
-| Full-stack | All of the above + deployment target |
-| CLI tool | Target OS? Binary or script? Package manager integration? |
+No scaffolding starts until all questions are answered.
 
 ---
 
-### Stage 2 — Plan
-
-Engage `project-planner` to write a structured plan:
+## Phase 2 — Stack Selection
 
-```
-Location: docs/PLAN-{task-slug}.md
-
-Must contain:
-  - Goal (one sentence)
-  - Out-of-scope list (what we won't build in this version)
-  - Open questions with [VERIFY] tags
-  - Task table: task / agent / dependency / done-condition
-  - Tribunal gate per task
-  - Time estimates: optimistic / realistic / pessimistic + confidence level
-```
+Based on the answers, the agent selects the appropriate stack:
 
-**The plan is shown to the user before any code is written.**
+|App Type|Recommended Stack|
+|:---|:---|
+|Web app (content + interaction)|Next.js 15, TypeScript, Tailwind v4, Prisma|
+|API server only|Hono on Node 22, Zod, TypeScript|
+|Real-time app|Next.js 15 + WebSocket (Socket.io) or SSE|
+|Mobile app|Expo + React Native, Expo Router v4|
+|CLI tool|Node 22, Commander.js, TypeScript|
+|E-commerce|Next.js 15 + Stripe + Prisma|
 
-> ⏸️ "Here's the plan: `docs/PLAN-{slug}.md` — proceed?"
-> Do not advance until explicitly confirmed with **Y**.
+Stack selection is presented to the user for approval before scaffolding begins.
 
 ---
 
-### Stage 3 — Build (Parallel agents, after approval)
+## Phase 3 — Scaffolding Plan
 
-| Layer | Primary Agent | Review Gate |
-|---|---|---|
-| Data schema / migrations | `database-architect` | `/tribunal-database` |
-| API & server logic | `backend-specialist` | `/tribunal-backend` |
-| UI & components | `frontend-specialist` | `/tribunal-frontend` |
-| Test coverage | `test-engineer` | `logic + test-coverage-reviewer` |
-| DevOps / deploy config | `devops-engineer` | `/tribunal-backend` |
-
-Each agent's code goes through Tribunal before being shown to the user.
-
-**Wave execution (if multiple layers):**
+The agent produces an implementation plan showing:
 
 ```
-Wave 1: database-architect → reviewed → Human Gate
-Wave 2: backend-specialist (uses Wave 1 schema) → reviewed → Human Gate
-Wave 3: frontend-specialist + test-engineer (parallel) → reviewed → Human Gate
+Files to create:
+├── Core structure (package.json, tsconfig, config files)
+├── Database schema (prisma/schema.prisma)
+├── Authentication setup (auth.ts, middleware.ts)
+├── Core API routes or Server Actions
+├── Base UI components and layouts
+└── Initial tests and CI pipeline
 ```
 
+**Human Gate:** User approves the plan before any files are written.
+
 ---
 
-### Stage 4 — Verify
+## Phase 4 — Tribunal Generation
+
+All generated code runs through the Tribunal pipeline:
 
 ```
-□ Did the code satisfy every done-condition from Stage 1?
-□ Did all Tribunal reviewers return APPROVED?
-□ Are untested paths labeled // TODO with an explanation?
-□ Does the plan file match what was actually built?
+Maker generates each module individually
+    → logic-reviewer + security-auditor on every module
+    → domain-specific reviewers activated by module type
+    → Human Gate before each major file group is written
 ```
 
-All four must be checked before the task is declared done.
+No module is written without passing Tribunal review.
 
 ---
 
-## Hallucination Rules
+## Phase 5 — Verification
 
-- 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 (frontend agent never writes DB migrations)
-- No full-application generation in one shot — build in layers with Human Gates between waves
+After scaffolding:
+
+```
+□ npm install completes without errors
+□ npx tsc --noEmit passes clean
+□ npm run dev starts successfully
+□ npm test runs and passes (for any generated tests)
+□ Linting passes (if configured)
+```
 
 ---
 
-## Cross-Workflow Navigation
+## Hallucination Guard (Create-Specific)
 
-| If during /create you need to... | Go to |
-|---|---|
-| Understand the existing codebase first | Use `explorer-agent` before Stage 2 |
-| Only write the plan (not build it) | `/plan` |
-| Add to an already built feature | `/enhance` |
-| Debug something during Stage 3 | `/debug` |
-| Run a full safety check before shipping | `/audit` |
+```
+❌ Never generate the entire application as one massive code block
+❌ Never import packages not added to package.json in this session
+❌ Never assume a framework's default file structure — check with --help or docs
+❌ Never hardcode environment variables in generated files
+❌ Never use deprecated Next.js 13/14 patterns (pages/, getServerSideProps)
+❌ Never use React 18 hooks deprecated in React 19
+```
 
 ---
 
-## Usage
+## Usage Examples
 
 ```
-/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)
-/create a CLI tool that validates JSON schemas against a spec
-/create a scheduled background job for sending email digests
+/create a REST API for a todo app with JWT auth and PostgreSQL
+/create a Next.js 15 e-commerce site with Stripe and Prisma
+/create a CLI tool for generating Tribunal-compliant code reviews
+/create an Expo app for tracking workout sessions with offline support
+/create a real-time chat app using Next.js and Server-Sent Events
 ```