tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/seo-fundamentals/SKILL.md

@@ -1,129 +1,181 @@
 ---
 name: seo-fundamentals
 description: SEO fundamentals, E-E-A-T, Core Web Vitals, and Google algorithm principles.
-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
 ---
 
 # SEO Fundamentals
 
-> Principles for search engine visibility.
+> SEO is not a trick. It is the practice of making content genuinely useful
+> for the people searching for it, and technically accessible to the crawlers that index it.
 
 ---
 
-## 1. E-E-A-T Framework
+## What Search Engines Actually Rank
 
-| Principle | Signals |
-|-----------|---------|
-| **Experience** | First-hand knowledge, real examples |
-| **Expertise** | Credentials, depth of knowledge |
-| **Authoritativeness** | Backlinks, mentions, industry recognition |
-| **Trustworthiness** | HTTPS, transparency, accurate info |
+Google's stated ranking factors, simplified:
+
+1. **Relevance** — does the content match the search intent?
+2. **Quality** — is it accurate, original, and valuable?
+3. **Authority** — do other credible sources link to it?
+4. **Experience** — is the page fast and easy to use?
+
+The manipulation era is over. Keyword stuffing gets pages penalized. Thin AI-generated content is actively filtered. The only reliable long-term SEO is making something worth ranking.
 
 ---
 
-## 2. Core Web Vitals
+## E-E-A-T Framework
+
+Google evaluates content on Experience, Expertise, Authoritativeness, and Trustworthiness.
 
-| Metric | Target | Measures |
-|--------|--------|----------|
-| **LCP** | < 2.5s | Loading performance |
-| **INP** | < 200ms | Interactivity |
-| **CLS** | < 0.1 | Visual stability |
+| Signal | What It Means | How to Demonstrate |
+|---|---|---|
+| Experience | First-hand use of the topic | Case studies, screenshots, real examples |
+| Expertise | Deep knowledge of the domain | Accurate detail, citations, author credentials |
+| Authoritativeness | Recognized by others in the field | External links, mentions, speaking/publishing |
+| Trustworthiness | Safe and reliable site | HTTPS, privacy policy, correct contact info |
+
+E-E-A-T matters most for YMYL content (health, finance, legal, safety).
 
 ---
 
-## 3. Technical SEO Principles
+## Technical SEO Checklist
 
-### Site Structure
+### Page-Level Requirements
 
-| Element | Purpose |
-|---------|---------|
-| XML sitemap | Help crawling |
-| robots.txt | Control access |
-| Canonical tags | Prevent duplicates |
-| HTTPS | Security signal |
+```html
+<!-- Title: 50–60 chars, includes primary keyword -->
+<title>Tribunal Agent Kit — Anti-Hallucination AI Tools</title>
 
-### Performance
+<!-- Description: 120–160 chars, actionable, includes keyword -->
+<meta name="description" content="Install the Tribunal Kit with npx tribunal-kit init. 
+27 specialist agents and 17 slash commands for Cursor, Windsurf, and Antigravity.">
 
-| Factor | Impact |
-|--------|--------|
-| Page speed | Core Web Vital |
-| Mobile-friendly | Ranking factor |
-| Clean URLs | Crawlability |
+<!-- One H1 per page — matches the title intent -->
+<h1>Anti-Hallucination Agent Kit for AI IDEs</h1>
 
----
+<!-- Canonical — prevent duplicate content -->
+<link rel="canonical" href="https://yoursite.com/page">
 
-## 4. Content SEO Principles
+<!-- Open Graph (social sharing) -->
+<meta property="og:title" content="...">
+<meta property="og:description" content="...">
+<meta property="og:image" content="https://yoursite.com/og-image.jpg">
+```
 
-### Page Elements
+### Core Web Vitals (2025 Targets)
 
-| Element | Best Practice |
-|---------|---------------|
-| Title tag | 50-60 chars, keyword front |
-| Meta description | 150-160 chars, compelling |
-| H1 | One per page, main keyword |
-| H2-H6 | Logical hierarchy |
-| Alt text | Descriptive, not stuffed |
+| Metric | Good | Needs Work | Poor |
+|---|---|---|---|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
+| INP (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |
 
-### Content Quality
+**Most common LCP fix:** The hero image or heading is the LCP element. Preload it:
+```html
+<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">
+```
 
-| Factor | Importance |
-|--------|------------|
-| Depth | Comprehensive coverage |
-| Freshness | Regular updates |
-| Uniqueness | Original value |
-| Readability | Clear writing |
+**Most common CLS fix:** Images without explicit width/height cause layout shifts:
+```html
+<img src="..." width="800" height="450" alt="...">
+```
 
 ---
 
-## 5. Schema Markup Types
-
-| Type | Use |
-|------|-----|
-| Article | Blog posts, news |
-| Organization | Company info |
-| Person | Author profiles |
-| FAQPage | Q&A content |
-| Product | E-commerce |
-| Review | Ratings |
-| BreadcrumbList | Navigation |
+## Content Structure
+
+```
+Page structure that works:
+  H1: Primary topic (one per page)
+  H2: Major sections
+  H3: Subsections
+  
+Content patterns that help:
+  - Answer the question in the first paragraph
+  - Use tables and lists for comparative or step-by-step info
+  - Add FAQ sections for long-tail queries
+  - Internal links to related content
+  - External links to authoritative sources
+```
 
 ---
 
-## 6. AI Content Guidelines
+## What Not to Do
+
+- **Keyword stuffing** — unreadable text written for bots; penalized
+- **Thin content** — pages with nothing to say; filtered
+- **Duplicate content** — same content on multiple URLs without canonical; splits authority
+- **Hidden text** — same color as background, `display:none` with keywords; penalized
+- **Link schemes** — buying links; can result in manual penalty
 
-### What Google Looks For
+---
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| AI draft + human edit | Publish raw AI content |
-| Add original insights | Copy without value |
-| Expert review | Skip fact-checking |
-| Follow E-E-A-T | Keyword stuffing |
+## Scripts
+
+| Script | Purpose | Run With |
+|---|---|---|
+| `scripts/seo_checker.py` | Audits page-level technical SEO | `python scripts/seo_checker.py <url>` |
 
 ---
 
-## 7. Ranking Factors (Prioritized)
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ Seo Fundamentals 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]
+```
+
 
-| Priority | Factor |
-|----------|--------|
-| 1 | Quality, relevant content |
-| 2 | Backlinks from authority sites |
-| 3 | Page experience (Core Web Vitals) |
-| 4 | Mobile optimization |
-| 5 | Technical SEO fundamentals |
 
 ---
 
-## 8. Measurement
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-| Metric | Tool |
-|--------|------|
-| Rankings | Search Console, Ahrefs |
-| Traffic | Analytics |
-| Core Web Vitals | PageSpeed Insights |
-| Indexing | Search Console |
-| Backlinks | Ahrefs, Semrush |
+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.
 
 ---
 
-> **Remember:** SEO is a long-term game. Quality content + technical excellence + patience = results.
+## 🏛️ 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.

package/.agent/skills/server-management/SKILL.md

@@ -1,161 +1,212 @@
 ---
 name: server-management
 description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
-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
 ---
 
-# Server Management
+# Server Management Principles
 
-> Server management principles for production operations.
-> **Learn to THINK, not memorize commands.**
+> A server you can't observe is a server you can't operate.
+> Monitoring is not optional — it is how you find out about problems before your users do.
 
 ---
 
-## 1. Process Management Principles
+## Process Management
 
-### Tool Selection
+Never run Node.js or Python processes directly in production with `node app.js`. Use a process manager.
 
-| Scenario | Tool |
-|----------|------|
-| **Node.js app** | PM2 (clustering, reload) |
-| **Any app** | systemd (Linux native) |
-| **Containers** | Docker/Podman |
-| **Orchestration** | Kubernetes, Docker Swarm |
+| Tool | Best For | Why |
+|---|---|---|
+| PM2 | Single-server Node.js | Auto-restart, log rotation, cluster mode |
+| systemd | Linux servers, any language | Native to most Linux distros, reliable |
+| Supervisor | Python, Ruby, any language | Simple config, battle-tested |
+| Docker (+restart policy) | Containerized apps | Portable, consistent across environments |
 
-### Process Management Goals
+**Core requirement:** If the process crashes, it restarts automatically. If it can't restart, you are alerted.
 
-| Goal | What It Means |
-|------|---------------|
-| **Restart on crash** | Auto-recovery |
-| **Zero-downtime reload** | No service interruption |
-| **Clustering** | Use all CPU cores |
-| **Persistence** | Survive server reboot |
+```bash
+# PM2 example — stays running, auto-restarts, survives reboots
+pm2 start app.js --name "api" --instances max
+pm2 save
+pm2 startup  # generates the command to run at boot
+```
 
 ---
 
-## 2. Monitoring Principles
+## What to Monitor
 
-### What to Monitor
+The minimum viable monitoring stack:
 
-| Category | Key Metrics |
-|----------|-------------|
-| **Availability** | Uptime, health checks |
-| **Performance** | Response time, throughput |
-| **Errors** | Error rate, types |
-| **Resources** | CPU, memory, disk |
+| Signal | What To Alert On |
+|---|---|
+| Process health | Process is not running |
+| Response time | P95 latency > SLA threshold |
+| Error rate | Error rate > 2x baseline |
+| Disk usage | > 80% full |
+| Memory | Growing without bound (memory leak) |
+| CPU | Sustained > 80% for more than 5 minutes |
 
-### Alert Severity Strategy
+**Alert on symptoms, not just causes.** "Error rate spiked" is a better alert than "CPU is high" — users don't feel CPU, they feel slow responses and errors.
 
-| Level | Response |
-|-------|----------|
-| **Critical** | Immediate action |
-| **Warning** | Investigate soon |
-| **Info** | Review daily |
+---
+
+## Log Management
+
+Logs are useless without structure. Structured logs can be queried and aggregated.
+
+```ts
+// ❌ Unstructured — hard to query
+console.log(`User ${userId} failed to login at ${new Date()}`);
+
+// ✅ Structured — can be filtered, aggregated, alerted on
+logger.warn('login_failed', {
+  userId,
+  ip: req.ip,
+  reason: 'invalid_password',
+  timestamp: new Date().toISOString(),
+});
+```
 
-### Monitoring Tool Selection
+**Log levels, used correctly:**
+- `ERROR` — something failed that requires attention
+- `WARN` — something unexpected but non-fatal happened
+- `INFO` — key business events (user registered, payment processed)
+- `DEBUG` — useful for troubleshooting, never on in production by default
 
-| Need | Options |
-|------|---------|
-| Simple/Free | PM2 metrics, htop |
-| Full observability | Grafana, Datadog |
-| Error tracking | Sentry |
-| Uptime | UptimeRobot, Pingdom |
+**Never log:**
+- Passwords, tokens, or full credit card numbers
+- PII without a documented retention policy
+- Full request bodies on auth endpoints
 
 ---
 
-## 3. Log Management Principles
+## Scaling Decision Framework
 
-### Log Strategy
+Before scaling, answer:
 
-| Log Type | Purpose |
-|----------|---------|
-| **Application logs** | Debug, audit |
-| **Access logs** | Traffic analysis |
-| **Error logs** | Issue detection |
+**Is the bottleneck identified?**
+- Profile first. Is it CPU, memory, database, or network?
+- Scaling horizontally when the bottleneck is a single database query helps nothing.
 
-### Log Principles
+| Bottleneck | Scaling Approach |
+|---|---|
+| CPU-bound app logic | Horizontal scale (more instances) |
+| Memory limit | Vertical scale (more RAM per instance) |
+| I/O-bound (DB, external calls) | Connection pooling, caching, async patterns |
+| Database reads | Read replicas, query optimization, caching |
+| Database writes | Sharding, write queuing, schema redesign |
 
-1. **Rotate logs** to prevent disk fill
-2. **Structured logging** (JSON) for parsing
-3. **Appropriate levels** (error/warn/info/debug)
-4. **No sensitive data** in logs
+**Cached responses don't need scaling.** Add caching before adding instances.
 
 ---
 
-## 4. Scaling Decisions
+## Nginx Configuration Essentials
+
+```nginx
+server {
+  listen 80;
+  server_name example.com;
+  
+  # Redirect HTTP → HTTPS
+  return 301 https://$host$request_uri;
+}
+
+server {
+  listen 443 ssl;
+  server_name example.com;
+
+  # Security headers
+  add_header X-Frame-Options DENY;
+  add_header X-Content-Type-Options nosniff;
+  add_header Strict-Transport-Security "max-age=31536000" always;
+
+  # Proxy to Node.js app
+  location / {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-Proto https;
+  }
+
+  # Serve static files directly (don't proxy to Node)
+  location /static/ {
+    root /var/www/myapp;
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+  }
+}
+```
 
-### When to Scale
+---
 
-| Symptom | Solution |
-|---------|----------|
-| High CPU | Add instances (horizontal) |
-| High memory | Increase RAM or fix leak |
-| Slow response | Profile first, then scale |
-| Traffic spikes | Auto-scaling |
+## Backup Strategy
 
-### Scaling Strategy
+The 3-2-1 rule:
+- **3** copies of data
+- **2** on different storage media
+- **1** offsite (different data center, cloud region)
 
-| Type | When to Use |
-|------|-------------|
-| **Vertical** | Quick fix, single instance |
-| **Horizontal** | Sustainable, distributed |
-| **Auto** | Variable traffic |
+Test restores on a schedule — a backup you've never restored is a backup you don't know works.
 
 ---
 
-## 5. Health Check Principles
+## Output Format
 
-### What Constitutes Healthy
+When this skill produces a recommendation or design decision, structure your output as:
 
-| Check | Meaning |
-|-------|---------|
-| **HTTP 200** | Service responding |
-| **Database connected** | Data accessible |
-| **Dependencies OK** | External services reachable |
-| **Resources OK** | CPU/memory not exhausted |
+```
+━━━ Server Management 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]
+```
 
-### Health Check Implementation
 
-- Simple: Just return 200
-- Deep: Check all dependencies
-- Choose based on load balancer needs
 
 ---
 
-## 6. Security Principles
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-| Area | Principle |
-|------|-----------|
-| **Access** | SSH keys only, no passwords |
-| **Firewall** | Only needed ports open |
-| **Updates** | Regular security patches |
-| **Secrets** | Environment vars, not files |
-| **Audit** | Log access and changes |
+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.
 
 ---
 
-## 7. Troubleshooting Priority
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-When something's wrong:
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
 
-1. **Check if running** (process status)
-2. **Check logs** (error messages)
-3. **Check resources** (disk, memory, CPU)
-4. **Check network** (ports, DNS)
-5. **Check dependencies** (database, APIs)
+### ❌ 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.
 
-## 8. Anti-Patterns
+### ✅ Pre-Flight Self-Audit
 
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Run as root | Use non-root user |
-| Ignore logs | Set up log rotation |
-| Skip monitoring | Monitor from day one |
-| Manual restarts | Auto-restart config |
-| No backups | Regular backup schedule |
+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
 
-> **Remember:** A well-managed server is boring. That's the goal.
+**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.