tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/architecture/SKILL.md

@@ -1,55 +1,200 @@
 ---
 name: architecture
 description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
-allowed-tools: Read, Glob, Grep
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
 # Architecture Decision Framework
 
-> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
+> An architecture decision is only good until the constraints change.
+> Document the decision AND the reasoning — future teams need both.
 
-## 🎯 Selective Reading Rule
+---
 
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When to Use This Skill
 
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
-| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
-| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
-| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
-| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |
+- A new system, service, or major feature is being designed
+- An existing architecture is being evaluated for scaling, cost, or maintainability problems
+- A team disagrees on technical direction and needs a structured decision process
+- A decision needs to be documented so future engineers understand the "why"
 
 ---
 
-## 🔗 Related Skills
+## The Decision Process
+
+Good architecture decisions follow a sequence. Skipping steps creates decisions that look good in a diagram and fail in production.
+
+### Phase 1 — Understand the Forces
+
+Before proposing anything, map what actually constrains the design:
+
+```
+Requirements:     What must this system do?
+Quality attributes: Speed, reliability, security, cost, maintainability — rank them
+Constraints:      Team size, existing tech, regulatory, budget
+Team context:     What does the team already know? What can they operate?
+```
+
+**The trap:** Jumping to technology before understanding quality attributes.
+If the top priority is "cheap to run" — that's a different answer than "sub-100ms response time."
+
+### Phase 2 — Generate Options
+
+Produce at least 2 real alternates. "We could do X, or we could not" is not a comparison.
+
+For each option document:
+- How it satisfies the top quality attributes
+- Where it falls short
+- Long-term operational cost (not just build cost)
+- Risk to the team given their current knowledge
+
+### Phase 3 — Evaluate Trade-offs
+
+Use a table:
+
+| Quality Attribute | Option A | Option B | Option C |
+|---|---|---|---|
+| Time to first delivery | ★★★ | ★★ | ★★★★ |
+| Operational complexity | Low | High | Medium |
+| Cost at 10x scale | $ | $$$ | $$ |
+
+The option with the most stars doesn't always win. **The one that best fits the top-priority attributes wins.**
 
-| Skill | Use For |
-|-------|---------|
-| `@[skills/database-design]` | Database schema design |
-| `@[skills/api-patterns]` | API design patterns |
-| `@[skills/deployment-procedures]` | Deployment architecture |
+### Phase 4 — Document the Decision (ADR)
+
+Every significant architecture decision gets an ADR (Architecture Decision Record).
+
+```markdown
+# ADR-NNN: [Short title]
+
+## Status
+Accepted / Proposed / Deprecated / Superseded by ADR-NNN
+
+## Context
+[What situation or problem prompted this decision?]
+
+## Options Considered
+[Brief description of each option]
+
+## Decision
+[What was chosen and why]
+
+## Trade-offs Accepted
+[What downsides are being consciously accepted?]
+
+## Consequences
+[What becomes easier? What becomes harder?]
+```
 
 ---
 
-## Core Principle
+## File Index
+
+| File | Covers | When to Load |
+|---|---|---|
+| `context-discovery.md` | Questions to map requirements and constraints | Early in design |
+| `pattern-selection.md` | Monolith vs microservices, event-driven, CQRS, etc. | Choosing structural patterns |
+| `patterns-reference.md` | Reference descriptions of common patterns | Evaluating patterns |
+| `trade-off-analysis.md` | Scoring and comparison frameworks | Decision phase |
+| `examples.md` | Worked architecture examples | Concrete reference |
 
-**"Simplicity is the ultimate sophistication."**
+---
+
+## Anti-Patterns in Architecture Work
 
-- Start simple
-- Add complexity ONLY when proven necessary
-- You can always add patterns later
-- Removing complexity is MUCH harder than adding it
+| Pattern | Problem |
+|---|---|
+| Resume-driven architecture | Choosing tech because it's interesting, not because it fits |
+| Premature microservices | Splitting a monolith before the domain boundaries are known |
+| Ignoring operational cost | Systems that are brilliant to build and terrible to run |
+| No ADR | Decision rationale lost — future engineers repeat the same debates |
+| One option considered | Not an evaluation, just a justification |
 
 ---
 
-## Validation Checklist
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ Architecture 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]
+```
+
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/brainstorm` or `/plan`**
+**Active reviewers: `project-planner` · `logic-reviewer`**
+
+### ❌ Forbidden AI Tropes in Architecture
+
+1. **Defaulting to Microservices** — never recommend Microservices for a new or small project without explicit scale requirements. Monolith first.
+2. **Over-engineering with CQRS/Event Sourcing** — do not suggest complex distributed patterns unless the domain demands it.
+3. **Assuming AWS/Cloud Provider** — ask where the user deploys, do not hallucinate AWS services as the default solution.
+4. **Ignoring Operational Cost** — do not recommend architectures that require dedicated DevOps teams if the user is a solo developer.
+5. **Failing to Document Trade-offs** — every architecture decision has a downside. Never present a "perfect" solution.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before proposing an architecture:
+```
+✅ Did I start with the simplest architecture that satisfies the constraints?
+✅ Did I explicitly document the downsides (cost, complexity, maintainability) of my proposal?
+✅ Is my proposal grounded in the user's actual constraints (team size, budget, timeline)?
+✅ Did I ask about the read/write ratio and data shape before choosing a database?
+✅ Is my solution resilient to partial failures?
+```
+
+
+---
+
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
 
-Before finalizing architecture:
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-- [ ] Requirements clearly understood
-- [ ] Constraints identified
-- [ ] Each decision has trade-off analysis
-- [ ] Simpler alternatives considered
-- [ ] ADRs written for significant decisions
-- [ ] Team expertise matches chosen patterns
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/bash-linux/SKILL.md

@@ -1,199 +1,215 @@
 ---
 name: bash-linux
 description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Bash Linux Patterns
+# Bash & Linux Shell Patterns
 
-> Essential patterns for Bash on Linux/macOS.
+> The terminal is a tool, not a magic box. Understand what a command does before you run it with elevated privileges.
 
 ---
 
-## 1. Operator Syntax
+## Ground Rules
 
-### Chaining Commands
-
-| Operator | Meaning | Example |
-|----------|---------|---------|
-| `;` | Run sequentially | `cmd1; cmd2` |
-| `&&` | Run if previous succeeded | `npm install && npm run dev` |
-| `\|\|` | Run if previous failed | `npm test \|\| echo "Tests failed"` |
-| `\|` | Pipe output | `ls \| grep ".js"` |
+1. **Never suggest `sudo` without explaining why it's necessary**
+2. **Test destructive commands with `--dry-run` or `echo` first**
+3. **`rm -rf` on a variable that might be empty = disaster** — guard it
+4. **Pipe chains fail silently unless you use `set -euo pipefail`**
 
 ---
 
-## 2. File Operations
-
-### Essential Commands
+## Essential Patterns
 
-| Task | Command |
-|------|---------|
-| List all | `ls -la` |
-| Find files | `find . -name "*.js" -type f` |
-| File content | `cat file.txt` |
-| First N lines | `head -n 20 file.txt` |
-| Last N lines | `tail -n 20 file.txt` |
-| Follow log | `tail -f log.txt` |
-| Search in files | `grep -r "pattern" --include="*.js"` |
-| File size | `du -sh *` |
-| Disk usage | `df -h` |
-
----
+### Safe Script Header
 
-## 3. Process Management
+Every shell script should start with:
 
-| Task | Command |
-|------|---------|
-| List processes | `ps aux` |
-| Find by name | `ps aux \| grep node` |
-| Kill by PID | `kill -9 <PID>` |
-| Find port user | `lsof -i :3000` |
-| Kill port | `kill -9 $(lsof -t -i :3000)` |
-| Background | `npm run dev &` |
-| Jobs | `jobs -l` |
-| Bring to front | `fg %1` |
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+```
 
----
+- `set -e` — exit on any error
+- `set -u` — exit on undefined variable
+- `set -o pipefail` — fail if any command in a pipe fails
+- `IFS` — safer word splitting
 
-## 4. Text Processing
+### Variable Safety
 
-### Core Tools
+```bash
+# ❌ Unsafe — if DIR is empty, this deletes /
+rm -rf "$DIR/"
 
-| Tool | Purpose | Example |
-|------|---------|---------|
-| `grep` | Search | `grep -rn "TODO" src/` |
-| `sed` | Replace | `sed -i 's/old/new/g' file.txt` |
-| `awk` | Extract columns | `awk '{print $1}' file.txt` |
-| `cut` | Cut fields | `cut -d',' -f1 data.csv` |
-| `sort` | Sort lines | `sort -u file.txt` |
-| `uniq` | Unique lines | `sort file.txt \| uniq -c` |
-| `wc` | Count | `wc -l file.txt` |
+# ✅ Safe — guard before destructive operation
+if [[ -z "$DIR" ]]; then
+  echo "Error: DIR is not set" >&2
+  exit 1
+fi
+rm -rf "$DIR/"
+```
 
----
+### Testing Conditions
 
-## 5. Environment Variables
+```bash
+# File/directory checks
+[[ -f "$file" ]]    # exists and is a regular file
+[[ -d "$dir" ]]     # exists and is a directory
+[[ -z "$var" ]]     # string is empty
+[[ -n "$var" ]]     # string is not empty
+
+# Numeric comparison (use (( )) for integers)
+(( count > 0 ))
+(( $? == 0 ))
+```
 
-| Task | Command |
-|------|---------|
-| View all | `env` or `printenv` |
-| View one | `echo $PATH` |
-| Set temporary | `export VAR="value"` |
-| Set in script | `VAR="value" command` |
-| Add to PATH | `export PATH="$PATH:/new/path"` |
+### Error Handling
 
----
+```bash
+# Trap errors and print context
+trap 'echo "Error on line $LINENO" >&2' ERR
 
-## 6. Network
+# Run a command and handle failure explicitly
+if ! command_that_might_fail; then
+  echo "Command failed — aborting" >&2
+  exit 1
+fi
 
-| Task | Command |
-|------|---------|
-| Download | `curl -O https://example.com/file` |
-| API request | `curl -X GET https://api.example.com` |
-| POST JSON | `curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL` |
-| Check port | `nc -zv localhost 3000` |
-| Network info | `ifconfig` or `ip addr` |
+# Or with ||
+do_something || { echo "Failed"; exit 1; }
+```
 
 ---
 
-## 7. Script Template
+## Common Operations
+
+### Find Files
 
 ```bash
-#!/bin/bash
-set -euo pipefail  # Exit on error, undefined var, pipe fail
+# Files modified in last 24h
+find . -mtime -1 -type f
 
-# Colors (optional)
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-NC='\033[0m'
+# Files matching pattern, excluding directories
+find . -name "*.log" -not -path "*/node_modules/*"
 
-# Script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Search contents
+grep -r "pattern" . --include="*.ts" -l   # list files
+grep -r "pattern" . --include="*.ts" -n   # with line numbers
+```
 
-# Functions
-log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
-log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+### Process & Resource Management
 
-# Main
-main() {
-    log_info "Starting..."
-    # Your logic here
-    log_info "Done!"
-}
+```bash
+# Find process using a port
+lsof -i :3000
+ss -tlnp | grep :3000   # on Linux
 
-main "$@"
+# Kill by port
+kill -9 $(lsof -ti :3000)
+
+# Background + disown
+long_running_command &
+disown $!
 ```
 
----
+### Text Processing Pipeline
 
-## 8. Common Patterns
+```bash
+# Count occurrences
+cat file.log | grep "ERROR" | wc -l
 
-### Check if command exists
+# Extract column from CSV
+cut -d',' -f2 data.csv
 
-```bash
-if command -v node &> /dev/null; then
-    echo "Node is installed"
-fi
+# Unique sorted values
+sort file.txt | uniq -c | sort -rn
 ```
 
-### Default variable value
+---
+
+## Script Structure Template
 
 ```bash
-NAME=${1:-"default_value"}
-```
+#!/usr/bin/env bash
+set -euo pipefail
 
-### Read file line by line
+# ── Config ──────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET="${1:-}"
 
-```bash
-while IFS= read -r line; do
-    echo "$line"
-done < file.txt
-```
+# ── Validate ────────────────────────────
+if [[ -z "$TARGET" ]]; then
+  echo "Usage: $(basename "$0") <target>" >&2
+  exit 1
+fi
 
-### Loop over files
+# ── Main ────────────────────────────────
+main() {
+  echo "Processing: $TARGET"
+  # ... logic here
+}
 
-```bash
-for file in *.js; do
-    echo "Processing $file"
-done
+main "$@"
 ```
 
 ---
 
-## 9. Differences from PowerShell
+## Platform Notes
 
-| Task | PowerShell | Bash |
-|------|------------|------|
-| List files | `Get-ChildItem` | `ls -la` |
-| Find files | `Get-ChildItem -Recurse` | `find . -type f` |
-| Environment | `$env:VAR` | `$VAR` |
-| String concat | `"$a$b"` | `"$a$b"` (same) |
-| Null check | `if ($x)` | `if [ -n "$x" ]` |
-| Pipeline | Object-based | Text-based |
+- `date` syntax differs between macOS BSD and Linux GNU — use `python3 -c "..."` for portable date math
+- `sed -i` needs an empty string argument on macOS: `sed -i '' 's/old/new/' file`
+- Prefer `#!/usr/bin/env bash` over `#!/bin/bash` for portability
 
 ---
 
-## 10. Error Handling
+## Output Format
 
-### Set options
+When this skill produces or reviews code, structure your output as follows:
 
-```bash
-set -e          # Exit on error
-set -u          # Exit on undefined variable
-set -o pipefail # Exit on pipe failure
-set -x          # Debug: print commands
+```
+━━━ Bash Linux Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Bash Linux
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
 ```
 
-### Trap for cleanup
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
-```bash
-cleanup() {
-    echo "Cleaning up..."
-    rm -f /tmp/tempfile
-}
-trap cleanup EXIT
-```
 
 ---
 
-> **Remember:** Bash is text-based. Use `&&` for success chains, `set -e` for safety, and quote your variables!
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/audit` or `/review`**
+**Active reviewers: `logic` · `security` · `devops`**
+
+### ❌ Forbidden AI Tropes in Bash/Linux
+
+1. **Unjustified `sudo`** — hallucinating `sudo` for scripts or directories owned by the local user.
+2. **Unquoted variables** — using `$CMD` instead of `"$CMD"`, leading to word splitting and globbing disasters.
+3. **Unguarded `rm -rf`** — deleting variables without checking if they are empty first (`[[ -z "$DIR" ]]`).
+4. **Pipe chains without `pipefail`** — writing `cat file | grep X | cut -d` without `set -o pipefail`, hiding failures.
+5. **Parsing `ls`** — scraping `ls` output instead of using `find` or globbing.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating Bash scripts or commands:
+```
+✅ Does the script start with `set -euo pipefail`?
+✅ Are all variable expansions wrapped in double quotes to prevent splitting?
+✅ Did I verify that `sudo` is absolutely required for this operation?
+✅ Are destructive operations (`rm`, `mv`) properly guarded with condition checks?
+✅ Did I use the most robust tool (e.g., `find` instead of `ls`) for the job?
+```