tribunal-kit 2.4.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/readme-builder/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: readme-builder
+description: Interactive README.md generation specialist. Creates professional, structured README files with badges, installation guides, usage examples, screenshots, and contribution guidelines. Use when asked to create, update, or improve a README file.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-19
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# README Builder Skill
+
+> A great README is a product pitch, a user manual, and a contributor's welcome — all in one document.
+
+---
+
+## Ground Rules
+
+1. **Always scan the project first** — read `package.json`, `pyproject.toml`, source files before writing a single line
+2. **No placeholder content** — every section must have real, specific information
+3. **Lead with value** — the first 3 lines must communicate what the project does and who it's for
+4. **Runnable examples** — every code block must be copy-paste ready and tested against the actual project
+
+---
+
+## Discovery Phase (Mandatory Before Writing)
+
+Before generating any README content, answer these questions by scanning the project:
+
+```
+1. What does this project do? (single sentence)
+2. Who is the target user? (developer / end-user / enterprise)
+3. What problem does it solve?
+4. What are the installation prerequisites?
+5. What is the primary command or API entry point?
+6. Does it have a license file?
+7. Are there screenshots, demos, or GIFs available?
+8. Is there a CONTRIBUTING.md or CODE_OF_CONDUCT.md?
+9. What CI/CD badges are relevant? (GitHub Actions, npm, PyPI, etc.)
+10. What is the current version?
+```
+
+---
+
+## README Structure Template
+
+```markdown
+# [Project Name]
+
+> [One-line tagline: what it does and for whom]
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name)
+[![Build Status](https://github.com/user/repo/workflows/CI/badge.svg)](https://github.com/user/repo/actions)
+
+[Optional: Screenshot or GIF Demo]
+
+---
+
+## ✨ Features
+
+- **Feature 1** — specific, concrete description
+- **Feature 2** — specific, concrete description
+- **Feature 3** — specific, concrete description
+
+---
+
+## 📋 Prerequisites
+
+- Node.js 18+ / Python 3.11+ / etc.
+- [Any specific tool or account required]
+
+---
+
+## 🚀 Installation
+
+```bash
+# npm
+npm install package-name
+
+# or yarn
+yarn add package-name
+
+# or global CLI install
+npm install -g package-name
+```
+
+---
+
+## 💻 Usage
+
+### Basic Example
+
+```bash
+# One-liner that shows the most common use case
+package-name --flag value
+```
+
+### Advanced Example
+
+```bash
+# More complex real-world usage
+package-name init --config ./config.json --output ./dist
+```
+
+---
+
+## ⚙️ Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `"default"` | What it controls |
+| `option2` | `boolean` | `false` | What it controls |
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Commit changes: `git commit -m "feat: add your feature"`
+4. Push to branch: `git push origin feat/your-feature`
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © [Author Name]
+```
+
+---
+
+## Badge Reference
+
+### Common Badges (GitHub-hosted project)
+
+```markdown
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/PACKAGE-NAME.svg)](https://badge.fury.io/js/PACKAGE-NAME)
+[![npm downloads](https://img.shields.io/npm/dm/PACKAGE-NAME.svg)](https://www.npmjs.com/package/PACKAGE-NAME)
+[![GitHub stars](https://img.shields.io/github/stars/USER/REPO.svg?style=social)](https://github.com/USER/REPO)
+[![GitHub issues](https://img.shields.io/github/issues/USER/REPO.svg)](https://github.com/USER/REPO/issues)
+[![CI](https://github.com/USER/REPO/workflows/CI/badge.svg)](https://github.com/USER/REPO/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/USER/REPO)](https://codecov.io/gh/USER/REPO)
+```
+
+---
+
+## Section Writing Guidelines
+
+### Hero Section (Lines 1–5)
+- Project name as `# H1` — only one per README
+- Tagline in a `> blockquote` — punchy, one sentence
+- Badges immediately after — visual trust signals
+
+### Features Section
+- Use emoji bullets for scannability
+- Each bullet = one concrete capability, not a vague claim
+- ❌ "Powerful and flexible" → ✅ "Processes 10k records/sec with zero config"
+
+### Installation Section
+- Always show the most direct path first (e.g., `npm install`)
+- Show alternatives (yarn, pnpm, brew) as secondary options
+- If there are post-install steps (env vars, migrations), list them explicitly
+
+### Usage Section
+- Start with the simplest 1-line example
+- Progress to realistic examples with real flag names
+- If it's a library, show import + function call pattern
+
+### Configuration Table
+- Every environment variable or config key goes here
+- Include: name, type, default, description
+- Mark required fields with `*` in the Description column
+
+---
+
+## Project-Type Specific Additions
+
+### CLI Tools
+Add a dedicated `## Commands` section:
+
+```markdown
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tool init` | Initialize a new project |
+| `tool build` | Compile and bundle |
+| `tool deploy` | Deploy to production |
+| `tool --help` | Show all available options |
+```
+
+### Libraries / SDKs
+Add a `## API Reference` section with function signatures:
+
+```markdown
+## API Reference
+
+### `functionName(param1, param2)`
+
+Returns: `ReturnType`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `param1` | `string` | Description |
+| `param2` | `options` | Optional config |
+```
+
+### Monorepos
+Add a `## Packages` table:
+
+```markdown
+## Packages
+
+| Package | Version | Description |
+|---------|---------|-------------|
+| [`@org/core`](packages/core) | [![npm](https://img.shields.io/npm/v/@org/core)](https://npm.im/@org/core) | Core engine |
+| [`@org/cli`](packages/cli) | [![npm](https://img.shields.io/npm/v/@org/cli)](https://npm.im/@org/cli) | CLI interface |
+```
+
+---
+
+## Output Format
+
+When this skill generates or reviews a README, structure your response as:
+
+```
+━━━ README Builder Report ━━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       readme-builder
+Project:     [project name / type detected]
+Sections:    [list of sections generated]
+─────────────────────────────────────────────────────
+✅ Included: [sections that are complete]
+⚠️  Missing:  [sections that should be added]
+❌ Blocked:  [issues preventing completion]
+─────────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [file written at path / content reviewed]
+```
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/generate`**
+**Active reviewers: `logic` · `frontend` · `documentation`**
+
+### ❌ Forbidden AI Tropes in README Generation
+
+1. **Placeholder content** — "Add your description here", "TODO", "Coming soon" are never acceptable.
+2. **Fabricated badges** — never create badge URLs with invented package names or repo paths.
+3. **Untested code blocks** — never write installation or usage commands without verifying them against the actual `package.json` or project config.
+4. **Version number invention** — always read the actual version from `package.json`, `pyproject.toml`, or `Cargo.toml`.
+5. **Generic feature claims** — "fast", "powerful", "easy to use" without concrete evidence or metrics.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before generating README content:
+
+```
+✅ Did I read the actual project files first (package.json, source)?
+✅ Is the project name correct (not a guess)?
+✅ Are all code block commands runnable against this actual project?
+✅ Are badge URLs pointing to the real repo/package?
+✅ Is the version number read from actual project files, not guessed?
+✅ Does every feature bullet describe a concrete, provable capability?
+```