tribunal-kit 3.0.0 → 4.0.0

package/.agent/skills/app-builder/SKILL.md

@@ -2,15 +2,20 @@
 name: app-builder
 description: Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 3.1.0
+last-updated: 2026-04-06
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# App Builder — Application Orchestrator
+## Hallucination Traps (Read First)
+- ❌ Generating entire applications in one shot -> ✅ Build one module at a time, verify each
+- ❌ Choosing a tech stack without asking the user -> ✅ Always ask about existing preferences, team skills, and deployment target
+- ❌ Hardcoding API keys or secrets during scaffolding -> ✅ Use .env.example with placeholder values from day one
+
+---
+
 
-> Building a full application is a coordination problem, not a coding problem.
-> Coordinate the experts. Keep the boundaries clean.
+# App Builder — Application Orchestrator
 
 ---
 
@@ -53,16 +58,15 @@ Wait for answers. Stack decisions depend on these answers.
 
 ## Phase 2 — Stack Selection
 
-| App Type | Frontend | Backend | Database |
-|---|---|---|---|
-| Content / marketing site | Next.js | Next.js API routes | PostgreSQL (if dynamic) |
-| SaaS web app | Next.js | Next.js API routes / Fastify | PostgreSQL + Redis |
-| Mobile app (cross-platform) | React Native (Expo) | Node.js API | PostgreSQL |
-| Internal dashboard / admin | Next.js | Next.js API routes | Existing |
-| Real-time (chat, collaboration) | Next.js | Fastify + WebSockets | PostgreSQL + Redis |
-| Data-heavy API | — | FastAPI (Python) | PostgreSQL |
-| AI assistant / RAG app | Next.js (streaming) | Fastify + LLM SDK | PostgreSQL + pgvector |
-| Edge-global, latency-critical | Next.js | Hono (Cloudflare Workers) | Turso / Cloudflare KV |
+|App Type|Frontend|Backend|Database|
+|Content / marketing site|Next.js|Next.js API routes|PostgreSQL (if dynamic)|
+|SaaS web app|Next.js|Next.js API routes / Fastify|PostgreSQL + Redis|
+|Mobile app (cross-platform)|React Native (Expo)|Node.js API|PostgreSQL|
+|Internal dashboard / admin|Next.js|Next.js API routes|Existing|
+|Real-time (chat, collaboration)|Next.js|Fastify + WebSockets|PostgreSQL + Redis|
+|Data-heavy API|—|FastAPI (Python)|PostgreSQL|
+|AI assistant / RAG app|Next.js (streaming)|Fastify + LLM SDK|PostgreSQL + pgvector|
+|Edge-global, latency-critical|Next.js|Hono (Cloudflare Workers)|Turso / Cloudflare KV|
 
 **If unclear:** Next.js + PostgreSQL covers 80% of use cases and is the safest default for web apps.
 
@@ -181,58 +185,338 @@ Report the URL to the user.
 
 ## Template Index
 
-| Template | Path | When to Use |
-|---|---|---|
-| Next.js Full-Stack | `templates/nextjs-app/` | Web app with API routes |
-| React Native | `templates/react-native-app/` | Cross-platform mobile |
-| API Only | `templates/api-only/` | Backend service, no UI |
+|Template|Path|When to Use|
+|Next.js Full-Stack|`templates/nextjs-app/`|Web app with API routes|
+|React Native|`templates/react-native-app/`|Cross-platform mobile|
+|API Only|`templates/api-only/`|Backend service, no UI|
+
+---
+
+---
+
+## Agent Coordination
+
+How App Builder orchestrates specialist agents.
+
+### Agent Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   APP BUILDER (Orchestrator)                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     PROJECT PLANNER                          │
+│  • Task breakdown                                            │
+│  • Dependency graph                                          │
+│  • File structure planning                                   │
+│  • Create {task-slug}.md in project root (MANDATORY)             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              CHECKPOINT: PLAN VERIFICATION                   │
+│  🔴 VERIFY: Does {task-slug}.md exist in project root?       │
+│  🔴 If NO → STOP → Create plan file first                    │
+│  🔴 If YES → Proceed to specialist agents                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┼───────────────────┐
+          ▼                   ▼                   ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ DATABASE        │ │ BACKEND         │ │ FRONTEND        │
+│ ARCHITECT       │ │ SPECIALIST      │ │ SPECIALIST      │
+│                 │ │                 │ │                 │
+│ • Schema design │ │ • API routes    │ │ • Components    │
+│ • Migrations    │ │ • Controllers   │ │ • Pages         │
+│ • Seed data     │ │ • Middleware    │ │ • Styling       │
+└─────────────────┘ └─────────────────┘ └─────────────────┘
+          │                   │                   │
+          └───────────────────┼───────────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 PARALLEL PHASE (Optional)                    │
+│  • Security Auditor → Vulnerability check                   │
+│  • Test Engineer → Unit tests                               │
+│  • Performance Optimizer → Bundle analysis                  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     DEVOPS ENGINEER                          │
+│  • Environment setup                                         │
+│  • Preview deployment                                        │
+│  • Health check                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Execution Order
+
+|Phase|Agent(s)|Parallel?|Prerequisite|CHECKPOINT|
+|-------|----------|-----------|--------------|------------|
+|0|Socratic Gate|❌|-|✅ Ask 3 questions|
+|1|Project Planner|❌|Questions answered|✅ **PLAN.md created**|
+|1.5|**PLAN VERIFICATION**|❌|PLAN.md exists|✅ **File exists in root**|
+|2|Database Architect|❌|Plan ready|Schema defined|
+|3|Backend Specialist|❌|Schema ready|API routes created|
+|4|Frontend Specialist|✅|API ready (partial)|UI components ready|
+|5|Security Auditor, Test Engineer|✅|Code ready|Tests & audit pass|
+|6|DevOps Engineer|❌|All code ready|Deployment ready|
+
+> 🔴 **CRITICAL:** Phase 1.5 is MANDATORY. No specialist agents proceed without PLAN.md verification.
 
 ---
 
-## Output Format
+## Feature Building
+
+How to analyze and implement new features.
+
+### Feature Analysis
+
+```
+Request: "add payment system"
+
+Analysis:
+├── Required Changes:
+│   ├── Database: orders, payments tables
+│   ├── Backend: /api/checkout, /api/webhooks/stripe
+│   ├── Frontend: CheckoutForm, PaymentSuccess
+│   └── Config: Stripe API keys
+│
+├── Dependencies:
+│   ├── stripe package
+│   └── Existing user authentication
+│
+└── Estimated Time: 15-20 minutes
+```
+
+### Iterative Enhancement Process
+
+```
+1. Analyze existing project
+2. Create change plan
+3. Present plan to user
+4. Get approval
+5. Apply changes
+6. Test
+7. Show preview
+```
+
+### Error Handling
+
+|Error Type|Solution Strategy|
+|------------|-------------------|
+|TypeScript Error|Fix type, add missing import|
+|Missing Dependency|Run npm install|
+|Port Conflict|Suggest alternative port|
+|Database Error|Check migration, validate connection|
+
+### Recovery Strategy
 
-When this skill produces a recommendation or design decision, structure your output as:
+```
+1. Detect error
+2. Try automatic fix
+3. If failed, report to user
+4. Suggest alternative
+5. Rollback if necessary
+```
+
+---
+
+## Project Type Detection
+
+Analyze user requests to determine project type and template.
+
+### Keyword Matrix
+
+|Keywords|Project Type|Template|
+|----------|--------------|----------|
+|blog, post, article|Blog|astro-static|
+|e-commerce, product, cart, payment|E-commerce|nextjs-saas|
+|dashboard, panel, management|Admin Dashboard|nextjs-fullstack|
+|api, backend, service, rest|API Service|express-api|
+|python, fastapi, django|Python API|python-fastapi|
+|mobile, android, ios, react native|Mobile App (RN)|react-native-app|
+|flutter, dart|Mobile App (Flutter)|flutter-app|
+|portfolio, personal, cv|Portfolio|nextjs-static|
+|crm, customer, sales|CRM|nextjs-fullstack|
+|saas, subscription, stripe|SaaS|nextjs-saas|
+|landing, promotional, marketing|Landing Page|nextjs-static|
+|docs, documentation|Documentation|astro-static|
+|extension, plugin, chrome|Browser Extension|chrome-extension|
+|desktop, electron|Desktop App|electron-desktop|
+|cli, command line, terminal|CLI Tool|cli-tool|
+|monorepo, workspace|Monorepo|monorepo-turborepo|
+
+### Detection Process
 
 ```
-━━━ App Builder Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
+1. Tokenize user request
+2. Extract keywords
+3. Determine project type
+4. Detect missing information → forward to conversation-manager
+5. Suggest tech stack
 ```
 
+---
+
+## Project Scaffolding
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+### Next.js Full-Stack Structure (2025 Optimized)
 
-**Slash command: `/create`**
-**Active reviewers: `orchestrator` · `project-planner`**
+```
+project-name/
+├── src/
+│   ├── app/                        # Routes only (thin layer)
+│   │   ├── layout.tsx
+│   │   ├── page.tsx
+│   │   ├── globals.css
+│   │   ├── (auth)/                 # Route group - auth pages
+│   │   │   ├── login/page.tsx
+│   │   │   └── register/page.tsx
+│   │   ├── (dashboard)/            # Route group - dashboard layout
+│   │   │   ├── layout.tsx
+│   │   │   └── page.tsx
+│   │   └── api/
+│   │       └── [resource]/route.ts
+│   │
+│   ├── features/                   # Feature-based modules
+│   │   ├── auth/
+│   │   │   ├── components/
+│   │   │   ├── hooks/
+│   │   │   ├── actions.ts          # Server Actions
+│   │   │   ├── queries.ts          # Data fetching
+│   │   │   └── types.ts
+│   │   ├── products/
+│   │   │   ├── components/
+│   │   │   ├── actions.ts
+│   │   │   └── queries.ts
+│   │   └── cart/
+│   │       └── ...
+│   │
+│   ├── shared/                     # Shared utilities
+│   │   ├── components/ui/          # Reusable UI components
+│   │   ├── lib/                    # Utils, helpers
+│   │   └── hooks/                  # Global hooks
+│   │
+│   └── server/                     # Server-only code
+│       ├── db/                     # Database client (Prisma)
+│       ├── auth/                   # Auth config
+│       └── services/               # External API integrations
+│
+├── prisma/
+│   ├── schema.prisma
+│   ├── migrations/
+│   └── seed.ts
+│
+├── public/
+├── .env.example
+├── .env.local
+├── package.json
+├── tailwind.config.ts
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+### Structure Principles
+
+|Principle|Implementation|
+|-----------|----------------|
+|**Feature isolation**|Each feature in `features/` with its own components, hooks, actions|
+|**Server/Client separation**|Server-only code in `server/`, prevents accidental client imports|
+|**Thin routes**|`app/` only for routing, logic lives in `features/`|
+|**Route groups**|`(groupName)/` for layout sharing without URL impact|
+|**Shared code**|`shared/` for truly reusable UI and utilities|
+
+---
 
-### ❌ Forbidden AI Tropes in App Building
+### Core Files
 
-1. **Skipping Constraints** — immediately starting to generate code without asking the user about their constraints and audience.
-2. **Building the Whole App at Once** — attempting to generate 50 files in a single turn.
-3. **Out-of-Order Execution** — writing frontend components before the API or DB schema is actually designed.
-4. **Magic Dependencies** — assuming packages are installed without updating `package.json`.
-5. **Ignoring Boundaries** — mismatching the API response format between the server and the frontend client.
+|File|Purpose|
+|------|---------|
+|`package.json`|Dependencies|
+|`tsconfig.json`|TypeScript + path aliases (`@/features/*`)|
+|`tailwind.config.ts`|Tailwind config|
+|`.env.example`|Environment template|
+|`README.md`|Project documentation|
+|`.gitignore`|Git ignore rules|
+|`prisma/schema.prisma`|Database schema|
 
-### ✅ Pre-Flight Self-Audit
+---
 
-Review these questions before orchestrating a full app build:
+### Path Aliases (tsconfig.json)
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/features/*": ["./src/features/*"],
+      "@/shared/*": ["./src/shared/*"],
+      "@/server/*": ["./src/server/*"]
+    }
+  }
+}
 ```
-✅ Did I ask the clarifying questions regarding constraints and target audience?
-✅ Is my generated plan broken into modular, sequenced steps (DB -> API -> UI)?
-✅ Have I explicitly defined the API contracts so the frontend and backend match?
-✅ Did I correctly track which dependencies need to be installed?
-✅ Am I verifying integration at each boundary before moving to the next layer?
+
+---
+
+### When to Use What
+
+|Need|Location|
+|------|----------|
+|New page/route|`app/(group)/page.tsx`|
+|Feature component|`features/[name]/components/`|
+|Server action|`features/[name]/actions.ts`|
+|Data fetching|`features/[name]/queries.ts`|
+|Reusable button/input|`shared/components/ui/`|
+|Database query|`server/db/`|
+|External API call|`server/services/`|
+
+---
+
+## Tech Stack Selection (2026)
+
+Default and alternative technology choices for web applications.
+
+### Default Stack (Web App - 2026)
+
+```yaml
+Frontend:
+  framework: Next.js 16 (Stable)
+  language: TypeScript 5.7+
+  styling: Tailwind CSS v4
+  state: React 19 Actions / Server Components
+  bundler: Turbopack (Stable for Dev)
+
+Backend:
+  runtime: Node.js 23
+  framework: Next.js API Routes / Hono (for Edge)
+  validation: Zod / TypeBox
+
+Database:
+  primary: PostgreSQL
+  orm: Prisma / Drizzle
+  hosting: Supabase / Neon
+
+Auth:
+  provider: Auth.js (v5) / Clerk
+
+Monorepo:
+  tool: Turborepo 2.0
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+### Alternative Options
 
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring an application architecture or full-stack integration complete without verifying the seams.
-- ✅ **Required:** You are explicitly forbidden from completing an app build or integration phase without providing **concrete terminal evidence** (e.g., successful local dev server start logs, passing build logs, or successful API local test results).
+|Need|Default|Alternative|
+|------|---------|-------------|
+|Real-time|-|Supabase Realtime, Socket.io|
+|File storage|-|Cloudinary, S3|
+|Payment|Stripe|LemonSqueezy, Paddle|
+|Email|-|Resend, SendGrid|
+|Search|-|Algolia, Typesense|

package/.agent/skills/app-builder/templates/SKILL.md

@@ -6,28 +6,26 @@ allowed-tools: Read, Glob, Grep
 
 # Project Templates
 
-> Quick-start templates for scaffolding new projects.
-
 ---
 
 ## 🎯 Selective Reading Rule
 
 **Read ONLY the template matching user's project type!**
 
-| Template | Tech Stack | When to Use |
+|Template|Tech Stack|When to Use|
 |----------|------------|-------------|
-| [nextjs-fullstack](nextjs-fullstack/TEMPLATE.md) | Next.js + Prisma | Full-stack web app |
-| [nextjs-saas](nextjs-saas/TEMPLATE.md) | Next.js + Stripe | SaaS product |
-| [nextjs-static](nextjs-static/TEMPLATE.md) | Next.js + Framer | Landing page |
-| [express-api](express-api/TEMPLATE.md) | Express + JWT | REST API |
-| [python-fastapi](python-fastapi/TEMPLATE.md) | FastAPI | Python API |
-| [react-native-app](react-native-app/TEMPLATE.md) | Expo + Zustand | Mobile app |
-| [flutter-app](flutter-app/TEMPLATE.md) | Flutter + Riverpod | Cross-platform |
-| [electron-desktop](electron-desktop/TEMPLATE.md) | Electron + React | Desktop app |
-| [chrome-extension](chrome-extension/TEMPLATE.md) | Chrome MV3 | Browser extension |
-| [cli-tool](cli-tool/TEMPLATE.md) | Node.js + Commander | CLI app |
-| [monorepo-turborepo](monorepo-turborepo/TEMPLATE.md) | Turborepo + pnpm | Monorepo |
-| [astro-static](astro-static/TEMPLATE.md) | Astro + MDX | Blog / Docs |
+|[nextjs-fullstack](nextjs-fullstack/TEMPLATE.md)|Next.js + Prisma|Full-stack web app|
+|[nextjs-saas](nextjs-saas/TEMPLATE.md)|Next.js + Stripe|SaaS product|
+|[nextjs-static](nextjs-static/TEMPLATE.md)|Next.js + Framer|Landing page|
+|[express-api](express-api/TEMPLATE.md)|Express + JWT|REST API|
+|[python-fastapi](python-fastapi/TEMPLATE.md)|FastAPI|Python API|
+|[react-native-app](react-native-app/TEMPLATE.md)|Expo + Zustand|Mobile app|
+|[flutter-app](flutter-app/TEMPLATE.md)|Flutter + Riverpod|Cross-platform|
+|[electron-desktop](electron-desktop/TEMPLATE.md)|Electron + React|Desktop app|
+|[chrome-extension](chrome-extension/TEMPLATE.md)|Chrome MV3|Browser extension|
+|[cli-tool](cli-tool/TEMPLATE.md)|Node.js + Commander|CLI app|
+|[monorepo-turborepo](monorepo-turborepo/TEMPLATE.md)|Turborepo + pnpm|Monorepo|
+|[astro-static](astro-static/TEMPLATE.md)|Astro + MDX|Blog / Docs|
 
 ---
 

package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md

@@ -7,13 +7,13 @@ description: Astro static site template principles. Content-focused websites, bl
 
 ## Tech Stack
 
-| Component | Technology |
+|Component|Technology|
 |-----------|------------|
-| Framework | Astro 4.x |
-| Content | MDX + Content Collections |
-| Styling | Tailwind CSS |
-| Integrations | Sitemap, RSS, SEO |
-| Output | Static/SSG |
+|Framework|Astro 4.x|
+|Content|MDX + Content Collections|
+|Styling|Tailwind CSS|
+|Integrations|Sitemap, RSS, SEO|
+|Output|Static/SSG|
 
 ---
 
@@ -38,12 +38,12 @@ project-name/
 
 ## Key Concepts
 
-| Concept | Description |
+|Concept|Description|
 |---------|-------------|
-| Content Collections | Type-safe content with Zod schemas |
-| Islands Architecture | Partial hydration for interactivity |
-| Zero JS by default | Static HTML unless needed |
-| MDX Support | Markdown with components |
+|Content Collections|Type-safe content with Zod schemas|
+|Islands Architecture|Partial hydration for interactivity|
+|Zero JS by default|Static HTML unless needed|
+|MDX Support|Markdown with components|
 
 ---
 
@@ -59,12 +59,12 @@ project-name/
 
 ## Deployment
 
-| Platform | Method |
+|Platform|Method|
 |----------|--------|
-| Vercel | Auto-detected |
-| Netlify | Auto-detected |
-| Cloudflare Pages | Auto-detected |
-| GitHub Pages | Build + deploy action |
+|Vercel|Auto-detected|
+|Netlify|Auto-detected|
+|Cloudflare Pages|Auto-detected|
+|GitHub Pages|Build + deploy action|
 
 ---
 

package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md

@@ -7,14 +7,14 @@ description: Chrome Extension template principles. Manifest V3, React, TypeScrip
 
 ## Tech Stack
 
-| Component | Technology |
+|Component|Technology|
 |-----------|------------|
-| Manifest | V3 |
-| UI | React 19 |
-| Language | TypeScript |
-| Styling | Tailwind CSS |
-| Bundler | Vite |
-| Storage | Chrome Storage API |
+|Manifest|V3|
+|UI|React 19|
+|Language|TypeScript|
+|Styling|Tailwind CSS|
+|Bundler|Vite|
+|Storage|Chrome Storage API|
 
 ---
 
@@ -42,23 +42,23 @@ project-name/
 
 ## Manifest V3 Concepts
 
-| Component | Purpose |
+|Component|Purpose|
 |-----------|---------|
-| Service Worker | Background processing |
-| Content Scripts | Page injection |
-| Popup | User interface |
-| Options Page | Settings |
+|Service Worker|Background processing|
+|Content Scripts|Page injection|
+|Popup|User interface|
+|Options Page|Settings|
 
 ---
 
 ## Permissions
 
-| Permission | Use |
+|Permission|Use|
 |------------|-----|
-| storage | Save user data |
-| activeTab | Current tab access |
-| scripting | Inject scripts |
-| host_permissions | Site access |
+|storage|Save user data|
+|activeTab|Current tab access|
+|scripting|Inject scripts|
+|host_permissions|Site access|
 
 ---
 
@@ -75,12 +75,12 @@ project-name/
 
 ## Development Tips
 
-| Task | Method |
+|Task|Method|
 |------|--------|
-| Debug Popup | Right-click icon → Inspect |
-| Debug Background | Extensions page → Service worker |
-| Debug Content | DevTools console on page |
-| Hot Reload | `npm run dev` with watch |
+|Debug Popup|Right-click icon → Inspect|
+|Debug Background|Extensions page → Service worker|
+|Debug Content|DevTools console on page|
+|Hot Reload|`npm run dev` with watch|
 
 ---
 

package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md

@@ -7,14 +7,14 @@ description: Node.js CLI tool template principles. Commander.js, interactive pro
 
 ## Tech Stack
 
-| Component | Technology |
+|Component|Technology|
 |-----------|------------|
-| Runtime | Node.js 20+ |
-| Language | TypeScript |
-| CLI Framework | Commander.js |
-| Prompts | Inquirer.js |
-| Output | chalk + ora |
-| Config | cosmiconfig |
+|Runtime|Node.js 20+|
+|Language|TypeScript|
+|CLI Framework|Commander.js|
+|Prompts|Inquirer.js|
+|Output|chalk + ora|
+|Config|cosmiconfig|
 
 ---
 
@@ -39,24 +39,24 @@ project-name/
 
 ## CLI Design Principles
 
-| Principle | Description |
+|Principle|Description|
 |-----------|-------------|
-| Subcommands | Group related actions |
-| Options | Flags with defaults |
-| Interactive | Prompts when needed |
-| Non-interactive | Support --yes flags |
+|Subcommands|Group related actions|
+|Options|Flags with defaults|
+|Interactive|Prompts when needed|
+|Non-interactive|Support --yes flags|
 
 ---
 
 ## Key Components
 
-| Component | Purpose |
+|Component|Purpose|
 |-----------|---------|
-| Commander | Command parsing |
-| Inquirer | Interactive prompts |
-| Chalk | Colored output |
-| Ora | Spinners/loading |
-| Cosmiconfig | Config file discovery |
+|Commander|Command parsing|
+|Inquirer|Interactive prompts|
+|Chalk|Colored output|
+|Ora|Spinners/loading|
+|Cosmiconfig|Config file discovery|
 
 ---