tribunal-kit 2.4.6 → 3.1.0

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

@@ -1,215 +1,120 @@
 ---
 name: bash-linux
-description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
+description: Bash/Linux terminal mastery. Shell scripting, piping, stream redirection, process substitution, strict mode (set -euo pipefail), AWK, ripgrep parsing, and robust error handling. Use when writing CI scripts, debugging POSIX environments, or manipulating text pipelines.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Bash & Linux Shell Patterns
-
-> The terminal is a tool, not a magic box. Understand what a command does before you run it with elevated privileges.
-
----
-
-## Ground Rules
-
-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`**
+# Bash & Linux — Shell Scripting Mastery
 
 ---
 
-## Essential Patterns
-
-### Safe Script Header
+## 1. Bash Strict Mode (Mandatory)
 
-Every shell script should start with:
+Always start every single bash script with strict compilation flags.
 
 ```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
-
-### Variable Safety
-
-```bash
-# ❌ Unsafe — if DIR is empty, this deletes /
-rm -rf "$DIR/"
-
-# ✅ Safe — guard before destructive operation
-if [[ -z "$DIR" ]]; then
-  echo "Error: DIR is not set" >&2
-  exit 1
-fi
-rm -rf "$DIR/"
-```
-
-### Testing Conditions
-
-```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 ))
-```
 
-### Error Handling
+# ❌ BAD: Default bash execution
+# - Undefined variables evaluate to empty strings
+# - Failed commands are ignored, execution continues blindly
+# - Piped failures are hidden (only last command exit code matters)
 
-```bash
-# Trap errors and print context
-trap 'echo "Error on line $LINENO" >&2' ERR
+# ✅ GOOD: Strict Mode
+set -euo pipefail
+IFS=$'\n\t'
 
-# Run a command and handle failure explicitly
-if ! command_that_might_fail; then
-  echo "Command failed — aborting" >&2
-  exit 1
-fi
+# -e: Exit immediately if a command exits with a non-zero status.
+# -u: Treat unset variables as an error and exit immediately.
+# -o pipefail: Pipeline returns the status of the rightmost command to exit with a non-zero status.
+# IFS: Only split on newlines and tabs, not spaces (prevents terrifying globbing/array bugs).
 
-# Or with ||
-do_something || { echo "Failed"; exit 1; }
+# Example: Catching potential disasters
+unset MY_VAR
+rm -rf "/some/path/${MY_VAR}" # With 'set -u', this throws an error instead of running 'rm -rf /some/path/'
 ```
 
 ---
 
-## Common Operations
+## 2. Advanced Stream Manipulation
 
-### Find Files
+Piping allows passing stdout from one program into stdin of another.
 
 ```bash
-# Files modified in last 24h
-find . -mtime -1 -type f
-
-# Files matching pattern, excluding directories
-find . -name "*.log" -not -path "*/node_modules/*"
-
-# Search contents
-grep -r "pattern" . --include="*.ts" -l   # list files
-grep -r "pattern" . --include="*.ts" -n   # with line numbers
+# ❌ VULNERABLE: Useless Use of Cat (UUOC)
+cat file.txt | grep "error"
+
+# ✅ EFFICIENT: Direct parsing
+grep "error" file.txt
+# Or modern ripgrep for huge repositories:
+rg "error" file.txt
+
+# Process Substitution: Treating tool outputs as if they were files
+# Compare two remote JSON responses without writing to disk
+diff <(curl -s api.com/v1) <(curl -s api.com/v2)
+
+# Redirection Mastery
+# 1> stdout, 2> stderr
+command > output.txt 2> error.txt   # Split streams
+command > all.txt 2>&1              # Combine streams (POSIX)
+command &> all.txt                  # Combine streams (Bash shortcut)
+command >/dev/null 2>&1             # Subdue all output cleanly
 ```
 
-### Process & Resource Management
-
-```bash
-# Find process using a port
-lsof -i :3000
-ss -tlnp | grep :3000   # on Linux
-
-# Kill by port
-kill -9 $(lsof -ti :3000)
+---
 
-# Background + disown
-long_running_command &
-disown $!
-```
+## 3. AWK and Stream Formatting
 
-### Text Processing Pipeline
+AWK is a complete programming language designed for text processing.
 
 ```bash
-# Count occurrences
-cat file.log | grep "ERROR" | wc -l
+# Example: We have a ps aux output and we want the PIDs (column 2) of all Node processes
+ps aux | grep node | awk '{print $2}'
 
-# Extract column from CSV
-cut -d',' -f2 data.csv
+# Example: Summing numbers in column 3 from a CSV
+cat data.csv | awk -F ',' '{sum+=$3} END {print sum}'
 
-# Unique sorted values
-sort file.txt | uniq -c | sort -rn
+# Extracting specific lines (e.g. line 5 to 10)
+sed -n '5,10p' file.txt
 ```
 
 ---
 
-## Script Structure Template
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# ── Config ──────────────────────────────
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TARGET="${1:-}"
+## 4. Modern CLI Alternatives (The 2026 Stack)
 
-# ── Validate ────────────────────────────
-if [[ -z "$TARGET" ]]; then
-  echo "Usage: $(basename "$0") <target>" >&2
-  exit 1
-fi
+Standard POSIX tools are reliable but slow. Use modern Rust-based alternatives when available in CI/CD.
 
-# ── Main ────────────────────────────────
-main() {
-  echo "Processing: $TARGET"
-  # ... logic here
-}
-
-main "$@"
-```
+|Task|Legacy POSIX|Modern Alternative|Why?|
+|:---|:---|:---|:---|
+|Find files|`find . -name "*.ts"`|`fd -e ts`|Context-aware, respects `.gitignore`, 10x faster.|
+|Search text|`grep -r "auth"`|`rg "auth"`|Ripgrep uses multi-threading and SIMD instructions.|
+|Inspect JSON|`grep / awk`|`jq '.users[].id'`|`jq` explicitly parses and filters valid JSON arrays/objects.|
+|Process monitoring|`top`|`htop` / `btm`|Interactive metrics.|
+|Check curl|`curl -i`|`httpie` / `xh`|Colorized, structured JSON networking.|
 
 ---
 
-## Platform Notes
+## 5. File System Traps & Quoting
 
-- `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
+If a filename contains a space and you didn't quote your variable, your script will crash or delete the wrong files.
 
----
+```bash
+# Let FILE="my backup.tar"
 
-## Output Format
+# ❌ BAD: Evaluates as `rm my` AND `backup.tar` -> Two different files!
+rm $FILE
 
-When this skill produces or reviews code, structure your output as follows:
+# ✅ GOOD: Always quote string variables
+rm "$FILE"
 
+# ✅ GOOD: Array iteration (Using quotes specifically formatted with @)
+FILES=("file 1.txt" "file 2.txt")
+for file in "${FILES[@]}"; do
+  echo "Processing: $file"
+done
 ```
-━━━ 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]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
 
 ---
-
-## 🏛️ 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?
-```

package/.agent/skills/behavioral-modes/SKILL.md

@@ -9,9 +9,6 @@ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 
 # Behavioral Modes
 
-> The same task handled carelessly vs. carefully looks identical until it fails.
-> Mode selection is about matching rigor to risk.
-
 ---
 
 ## Overview
@@ -130,15 +127,15 @@ This skill defines how to behave in each context — not just what to produce.
 
 ## Mode Selection Rules
 
-| Signal in Request | Activate |
+|Signal in Request|Activate|
 |---|---|
-| "how does", "explain", "what is" | TEACH |
-| "why is X broken", "error:", traceback | DEBUG |
-| "review this", "audit", "check" | REVIEW |
-| "build", "create", "implement" | PLAN → BUILD |
-| "I'm not sure what I need" | DISCOVER |
-| "deploy", "release", "publish" | SHIP |
-| Multiple domains in one request | ORCHESTRATE |
+|"how does", "explain", "what is"|TEACH|
+|"why is X broken", "error:", traceback|DEBUG|
+|"review this", "audit", "check"|REVIEW|
+|"build", "create", "implement"|PLAN → BUILD|
+|"I'm not sure what I need"|DISCOVER|
+|"deploy", "release", "publish"|SHIP|
+|Multiple domains in one request|ORCHESTRATE|
 
 ---
 
@@ -173,62 +170,4 @@ Pre-Flight:  ✅ All checks passed
              or ❌ [blocking item that must be resolved first]
 ```
 
-
----
-
-## 🏛️ Tribunal Integration 
-
-**Slash command: Contextually applied based on user intent**
-**Active reviewers: `logic-reviewer` (monitors for mode adherence)**
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before sending any response to ensure you are in the correct mode:
-```
-✅ Have I explicitly announced which mode I am operating in?
-✅ If in DISCOVER or TEACH, have I successfully suppressed the urge to write implementation code?
-✅ If in DEBUG, am I proving a hypothesis or just guessing a fix?
-✅ If in REVIEW, am I commenting on the existing code rather than silently rewriting it?
-```
-
-
----
-
-## 🤖 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?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**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.