tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/github-operations/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: github-operations
+description: Complete Git and GitHub workflow orchestration. Handles branching, committing, pushing, pull requests, conflict resolution, and repository management. Use when working with Git repositories, GitHub Actions, or any version control operations.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+version: 1.0.0
+last-updated: 2026-03-19
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# GitHub Operations Skill
+
+> Git is a communication tool as much as a version control tool. Commit messages are letters to your future self and your team.
+
+---
+
+## Ground Rules
+
+1. **Never force-push to `main` or `master`** — use feature branches
+2. **Always check `git status` before staging** — know what you are committing
+3. **One logical change per commit** — atomic commits are easier to revert
+4. **Pull before push** — always sync with remote first to avoid conflicts
+5. **Never commit secrets** — use `.gitignore` and environment variables
+
+---
+
+## Core Workflow Patterns
+
+### Standard Feature Branch Workflow
+
+```bash
+# 1. Always start from an up-to-date main
+git checkout main
+git pull origin main
+
+# 2. Create a descriptive feature branch
+git checkout -b feat/your-feature-name
+
+# 3. Make changes, then stage selectively
+git add -p                    # Interactive: review each hunk before staging
+git add path/to/specific/file # Or stage specific files
+
+# 4. Commit with a meaningful message
+git commit -m "feat(scope): short summary of change
+
+- Detail 1: what was added/changed and why
+- Detail 2: any side effects or dependencies"
+
+# 5. Push and create PR
+git push -u origin feat/your-feature-name
+```
+
+### Commit Message Convention (Conventional Commits)
+
+```
+<type>(<scope>): <short summary>
+
+[optional body: explain WHY, not what]
+
+[optional footer: BREAKING CHANGE, closes #issue]
+```
+
+**Types:**
+| Type | Use When |
+|------|----------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code restructure, no behavior change |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+| `chore` | Build, CI, dependency updates |
+| `style` | Formatting, whitespace (no logic) |
+
+**Example commit messages:**
+```
+feat(auth): add JWT refresh token rotation
+fix(api): handle null response from external service
+docs(readme): add installation and usage sections
+chore(deps): upgrade typescript to 5.4
+```
+
+---
+
+## Common Operations
+
+### Fast Git Status Check
+
+```bash
+git status --short        # Compact view
+git diff --stat           # What changed and how much
+git log --oneline -10     # Last 10 commits, one line each
+git log --oneline --graph --all  # Full branch graph
+```
+
+### Staging Strategies
+
+```bash
+# Stage everything (use only when you know all changes are correct)
+git add -A
+
+# Stage interactively — review each change hunk
+git add -p
+
+# Stage a full directory
+git add src/
+
+# Stage individual files
+git add file1.ts file2.ts
+
+# Unstage a file (keep changes, remove from staging)
+git restore --staged file.ts
+```
+
+### Undoing Mistakes
+
+```bash
+# Undo last commit, keep changes staged
+git reset --soft HEAD~1
+
+# Undo last commit, keep changes unstaged
+git reset HEAD~1
+
+# Discard all local changes (DESTRUCTIVE — cannot undo)
+git restore .
+
+# Revert a commit (creates a new "undo" commit — safe for shared branches)
+git revert <commit-hash>
+
+# Remove a file from git tracking but keep it locally
+git rm --cached file.txt
+echo "file.txt" >> .gitignore
+```
+
+### Resolving Merge Conflicts
+
+```bash
+# Pull with rebase (cleaner history than merge)
+git pull --rebase origin main
+
+# If rebase conflicts occur:
+# 1. Fix conflicts in editor (look for <<<<<<, =======, >>>>>>>)
+# 2. Stage resolved files
+git add resolved-file.ts
+# 3. Continue rebase
+git rebase --continue
+
+# If rebase is a mess, abort and start over
+git rebase --abort
+```
+
+### Working with Remotes
+
+```bash
+# Show all remotes
+git remote -v
+
+# Add a remote
+git remote add origin https://github.com/user/repo.git
+
+# Change remote URL
+git remote set-url origin https://github.com/user/new-repo.git
+
+# Fetch all remotes without merging
+git fetch --all
+
+# Push and set upstream tracking
+git push -u origin branch-name
+
+# Delete a remote branch
+git push origin --delete branch-name
+```
+
+### GitHub CLI (gh) Operations
+
+```bash
+# Create a pull request
+gh pr create --title "feat: my feature" --body "Description of changes" --base main
+
+# List open PRs
+gh pr list
+
+# Check PR status + reviews
+gh pr status
+
+# Merge PR (squash recommended for features)
+gh pr merge --squash
+
+# Create a release
+gh release create v1.0.0 --title "v1.0.0 - Initial Release" --notes "Release notes here"
+
+# Clone a repo
+gh repo clone owner/repo-name
+
+# View repo in browser
+gh repo view --web
+```
+
+---
+
+## Advanced Patterns
+
+### Stashing Work in Progress
+
+```bash
+# Stash changes with a label
+git stash push -m "WIP: half-done auth feature"
+
+# List all stashes
+git stash list
+
+# Apply most recent stash (keep it in stash list)
+git stash apply
+
+# Apply a specific stash
+git stash apply stash@{2}
+
+# Apply and drop at once
+git stash pop
+
+# Drop a specific stash
+git stash drop stash@{0}
+```
+
+### Tagging Releases
+
+```bash
+# Create an annotated tag (preferred for releases)
+git tag -a v1.2.0 -m "Release version 1.2.0 — added X, fixed Y"
+
+# Push tags to remote
+git push origin --tags
+
+# List existing tags
+git tag -l
+
+# Delete a tag locally and remotely
+git tag -d v1.2.0
+git push origin --delete v1.2.0
+```
+
+### Squashing Commits Before PR
+
+```bash
+# Interactive rebase to squash last N commits
+git rebase -i HEAD~3
+
+# In the editor: change 'pick' to 'squash' (or 's') for commits to merge
+# Keep the first as 'pick', squash the rest into it
+```
+
+---
+
+## README Generation (Quick Pattern)
+
+When adding or updating a README, use this checklist:
+
+```
+## README Checklist
+- [ ] Project name and one-line description at the top
+- [ ] Badges: build status, version, license
+- [ ] Quick demo or screenshot
+- [ ] Requirements / prerequisites
+- [ ] Installation (copy-paste commands, no ambiguity)
+- [ ] Usage with examples
+- [ ] Configuration / environment variables table
+- [ ] Contributing guidelines link
+- [ ] License declaration
+```
+
+---
+
+## .gitignore Templates
+
+### Node.js / TypeScript
+
+```gitignore
+node_modules/
+dist/
+build/
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+Thumbs.db
+coverage/
+.nyc_output/
+```
+
+### Python
+
+```gitignore
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.log
+.pytest_cache/
+```
+
+---
+
+## Output Format
+
+When this skill produces git operations or reviews them, structure your output as:
+
+```
+━━━ GitHub Operations Report ━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       github-operations
+Scope:       [repo name / branch]
+Operation:   [commit / push / PR / merge / etc.]
+─────────────────────────────────────────────────────
+✅ 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:    [git output / push confirmation / PR link]
+```
+
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence (e.g., push success, PR link) is provided.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/audit`**
+**Active reviewers: `logic` · `security` · `devops`**
+
+### ❌ Forbidden AI Tropes in GitHub Operations
+
+1. **Inventing commit hashes** — never fabricate SHA hashes; always use `git log` to retrieve real ones.
+2. **Assuming branch names** — always confirm the current branch with `git branch --show-current` before operating.
+3. **Silently force-pushing** — never suggest `git push --force` without explicitly warning about history rewrite risks.
+4. **Hallucinating `gh` subcommands** — only use `gh` commands from the official GitHub CLI docs.
+5. **Skipping `git pull` before push** — always sync with remote first, especially on shared branches.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before any git operation:
+
+```
+✅ Did I check `git status` before staging changes?
+✅ Is the commit message following Conventional Commits format?
+✅ Did I verify the correct branch is active with `git branch --show-current`?
+✅ Did I pull from remote before pushing to avoid conflicts?
+✅ Are there any secrets, API keys, or credentials in the staged diff?
+✅ If force-pushing, did I explicitly warn the user about history rewrite?
+```

package/.agent/skills/i18n-localization/SKILL.md

@@ -1,154 +1,216 @@
 ---
 name: i18n-localization
 description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
-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
 ---
 
-# i18n & Localization
+# Internationalization & Localization
 
-> Internationalization (i18n) and Localization (L10n) best practices.
+> Internationalization (i18n) is preparing code to support multiple languages.
+> Localization (l10n) is the work of adapting to a specific locale.
+> Do i18n once, properly. Do l10n for each market.
 
 ---
 
-## 1. Core Concepts
+## The Core Rule: No Hardcoded Strings
 
-| Term | Meaning |
-|------|---------|
-| **i18n** | Internationalization - making app translatable |
-| **L10n** | Localization - actual translations |
-| **Locale** | Language + Region (en-US, tr-TR) |
-| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+Every user-visible string in the source code is a localization problem waiting to happen.
+
+```ts
+// ❌ Hardcoded — untranslatable
+<button>Save Changes</button>
+<p>You have {count} messages</p>
+<p>Error: Invalid email address</p>
+
+// ✅ Key-referenced — translatable
+<button>{t('common.save')}</button>
+<p>{t('inbox.messageCount', { count })}</p>
+<p>{t('errors.invalidEmail')}</p>
+```
 
 ---
 
-## 2. When to Use i18n
+## Translation File Structure
+
+Organize translation keys hierarchically — flat files become unmaintainable past ~50 keys:
+
+```json
+// en.json
+{
+  "common": {
+    "save": "Save Changes",
+    "cancel": "Cancel",
+    "loading": "Loading…",
+    "error": "Something went wrong"
+  },
+  "auth": {
+    "login": "Sign In",
+    "logout": "Sign Out",
+    "register": "Create Account",
+    "errors": {
+      "invalidEmail": "Enter a valid email address",
+      "passwordTooShort": "Password must be at least {{min}} characters"
+    }
+  },
+  "inbox": {
+    "messageCount_one": "{{count}} message",
+    "messageCount_other": "{{count}} messages"
+  }
+}
+```
 
-| Project Type | i18n Needed? |
-|--------------|--------------|
-| Public web app | ✅ Yes |
-| SaaS product | ✅ Yes |
-| Internal tool | ⚠️ Maybe |
-| Single-region app | ⚠️ Consider future |
-| Personal project | ❌ Optional |
+**Key naming conventions:**
+- `feature.element` or `feature.element.state`
+- Error keys under `.errors`
+- Never use the English text as the key (`"Save Changes": "Save Changes"`)
 
 ---
 
-## 3. Implementation Patterns
+## Pluralization
 
-### React (react-i18next)
+Pluralization rules differ per language. Use your i18n library's plural system — never manual `if count > 1`:
 
-```tsx
-import { useTranslation } from 'react-i18next';
+```ts
+// ❌ Only works for English
+const label = count === 1 ? 'message' : 'messages';
 
-function Welcome() {
-  const { t } = useTranslation();
-  return <h1>{t('welcome.title')}</h1>;
-}
+// ✅ i18next handles per-language plural rules
+t('inbox.messageCount', { count })
+
+// Translation files handle the variants:
+// English: { "messageCount_one": "{{count}} message", "messageCount_other": "{{count}} messages" }
+// Arabic:  6 plural forms (zero, one, two, few, many, other)
+// Russian: 3 plural forms with complex rules
 ```
 
-### Next.js (next-intl)
+---
 
-```tsx
-import { useTranslations } from 'next-intl';
+## Date, Number & Currency Formatting
 
-export default function Page() {
-  const t = useTranslations('Home');
-  return <h1>{t('title')}</h1>;
-}
-```
+Never format these manually. Use the browser's `Intl` API:
 
-### Python (gettext)
+```ts
+// Date
+const date = new Date();
+new Intl.DateTimeFormat('en-US').format(date);  // "2/20/2026"
+new Intl.DateTimeFormat('de-DE').format(date);  // "20.2.2026"
 
-```python
-from gettext import gettext as _
+// Number
+new Intl.NumberFormat('en-US').format(1234567.89);  // "1,234,567.89"
+new Intl.NumberFormat('de-DE').format(1234567.89);  // "1.234.567,89"
 
-print(_("Welcome to our app"))
+// Currency
+new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(99.99);
+// "$99.99"
+new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(99.99);
+// "99,99 €"
 ```
 
 ---
 
-## 4. File Structure
+## RTL (Right-to-Left) Support
+
+Arabic, Hebrew, Persian, Urdu are RTL languages. Supporting them requires more than flipping direction.
+
+```html
+<!-- Set direction on html element based on locale -->
+<html lang="ar" dir="rtl">
 
+<!-- Or dynamically -->
+<html lang={locale} dir={isRTL(locale) ? 'rtl' : 'ltr'}>
 ```
-locales/
-├── en/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-├── tr/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-└── ar/          # RTL
-    └── ...
+
+```css
+/* Use logical properties — they flip automatically with direction */
+/* ❌ Physical: only works for LTR */
+padding-left: 1rem;
+margin-right: 2rem;
+border-left: 2px solid;
+
+/* ✅ Logical: works for both LTR and RTL */
+padding-inline-start: 1rem;
+margin-inline-end: 2rem;
+border-inline-start: 2px solid;
 ```
 
 ---
 
-## 5. Best Practices
+## Detecting Hardcoded Strings (Code Audit)
 
-### DO ✅
+Look for:
+- JSX text content directly in tags: `<p>some text</p>` (not `<p>{t(...)}</p>`)
+- Template literals with user-facing copy: `` `Welcome, ${name}!` ``
+- Alert/toast calls with string literals: `toast.success('Saved!')`
+- Error messages: `new Error('Invalid input')` shown to users
+- `placeholder`, `aria-label`, `title` attributes hardcoded
 
-- Use translation keys, not raw text
-- Namespace translations by feature
-- Support pluralization
-- Handle date/number formats per locale
-- Plan for RTL from the start
-- Use ICU message format for complex strings
+---
 
-### DON'T ❌
+## Scripts
 
-- Hardcode strings in components
-- Concatenate translated strings
-- Assume text length (German is 30% longer)
-- Forget about RTL layout
-- Mix languages in same file
+| Script | Purpose | Run With |
+|---|---|---|
+| `scripts/i18n_checker.py` | Scans codebase for hardcoded strings | `python scripts/i18n_checker.py <project_path>` |
 
 ---
 
-## 6. Common Issues
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
+
+```
+━━━ I18N Localization 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]
+```
+
 
-| Issue | Solution |
-|-------|----------|
-| Missing translation | Fallback to default language |
-| Hardcoded strings | Use linter/checker script |
-| Date format | Use Intl.DateTimeFormat |
-| Number format | Use Intl.NumberFormat |
-| Pluralization | Use ICU message format |
 
 ---
 
-## 7. RTL Support
+## 🤖 LLM-Specific Traps
 
-```css
-/* CSS Logical Properties */
-.container {
-  margin-inline-start: 1rem;  /* Not margin-left */
-  padding-inline-end: 1rem;   /* Not padding-right */
-}
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-[dir="rtl"] .icon {
-  transform: scaleX(-1);
-}
-```
+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.
 
 ---
 
-## 8. Checklist
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-Before shipping:
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
 
-- [ ] All user-facing strings use translation keys
-- [ ] Locale files exist for all supported languages
-- [ ] Date/number formatting uses Intl API
-- [ ] RTL layout tested (if applicable)
-- [ ] Fallback language configured
-- [ ] No hardcoded strings in components
+### ❌ 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?
+```
 
-## Script
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |
+**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.