opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/repo-maintainer/SKILL.md

@@ -0,0 +1,480 @@
+---
+name: repo-maintainer
+description: Championship-grade repository maintenance. Audits for test artifacts, dependency issues, CI/CD health, documentation sync, and FAF alignment. Generates prioritized cleanup plans. Use when repos need deep cleaning or ongoing maintenance.
+risk: unknown
+source: https://github.com/Wolfe-Jam/faf-skills/tree/main/skills/repo-maintainer
+source_repo: Wolfe-Jam/faf-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/Wolfe-Jam/faf-skills/blob/main/LICENSE
+---
+
+# Repo Maintainer - Championship Repository Hygiene
+
+**"When brakes must work flawlessly, so must our repos."**
+
+---
+
+## When to Use This Skill
+
+Activate when:
+- User types `/repo-maintainer` or `/maintain`
+- User says "clean up this repo" or "audit the repo"
+- Starting maintenance on a repository
+- After major refactoring or before releases
+- Monthly/quarterly repo health checks
+- Onboarding to a new codebase
+
+## What This Skill Does
+
+### 🔍 **Phase 1: Comprehensive Audit**
+
+Systematically checks 7 critical areas:
+
+#### 1. **Artifact Detection**
+```bash
+# Find test artifacts
+*.test.js leftovers
+*.spec.ts.snap orphans
+.DS_Store files
+tmp/, temp/, cache/ directories
+coverage/ not in .gitignore
+dist/, build/ committed by accident
+node_modules/ somehow in git
+```
+
+**Detection Strategy:**
+- Check `git status` for untracked patterns
+- Scan for common artifact extensions
+- Compare against .gitignore
+- Find large files (>1MB) in working directory
+
+#### 2. **Dependency Health**
+```bash
+# Check package health
+npm outdated
+npm audit
+npx depcheck (find unused deps)
+Check for pinned versions (inquirer@8.2.5 pattern)
+Verify Dependabot config
+```
+
+**Red Flags:**
+- Packages with security vulnerabilities
+- EOL runtime versions (Node 16, Python 3.7)
+- Duplicate dependencies (lodash + lodash.merge)
+- Unused dependencies (installed but never imported)
+
+#### 3. **CI/CD Alignment**
+```bash
+# Workflow consistency check
+Node versions across all workflows
+Test matrices (should match across ci.yml, release.yml)
+Action versions (@v6 vs @v5)
+Failed/skipped workflow runs
+Secrets/tokens properly configured
+```
+
+**Common Fixes:**
+- Remove EOL runtimes (e.g. Node 16) from release workflows
+- Align Node versions across all workflows (e.g. 18/20/22)
+- Pin packages that break under ESM resolution
+
+#### 4. **Documentation Sync**
+```bash
+# Context alignment check
+README.md ↔ CLAUDE.md ↔ project.faf
+CHANGELOG up to date with git tags
+package.json version matches latest tag
+Examples in README still work
+Links not broken (404 checks)
+```
+
+**FAF-Specific:**
+- project.faf reflects current state
+- CLAUDE.md bi-sync active
+- .faf-dna not churning unnecessarily
+
+#### 5. **Git Hygiene**
+```bash
+# .gitignore audit
+Untracked files that should be ignored
+  *.config.mjs
+  *.faf test artifacts
+  .env.local, .env.development
+Large files in git history (use git-filter-repo)
+Binary files that don't belong
+```
+
+**Pattern Recognition:**
+```gitignore
+# Add to .gitignore based on artifacts found
+*.config.mjs
+*.faf.backup
+.faf-dna.tmp
+test-*.faf
+```
+
+#### 6. **Code Quality Signals**
+```bash
+# Quick health indicators
+Dead code (unused exports via ts-prune or depcheck)
+TODO/FIXME comments (track count, prioritize)
+Commented code blocks (remove or document)
+Console.log statements in production code
+Hardcoded secrets/tokens
+```
+
+#### 7. **FAF Ecosystem Health**
+
+For FAF projects specifically:
+```yaml
+# Check FAF alignment
+.faf score accuracy (run faf score)
+Bi-sync alignment — CLAUDE.md ↔ .faf (run `faf sync`; mtime auto-direction)
+MCP server compliance (if applicable)
+WJTTC test coverage (for faf-cli, MCP servers)
+```
+
+For MCP servers:
+```bash
+# MCP-specific checks
+package.json has "mcp" field
+Server implements required tools
+Tests cover all tool endpoints
+README has MCP installation instructions
+Registry listing accurate (npm + MCP registry)
+```
+
+---
+
+### 🛠️ **Phase 2: Cleanup Plan Generation**
+
+After audit, generate prioritized task list:
+
+```markdown
+# 🏎️ REPO HEALTH REPORT: faf-cli
+
+**Overall Score:** 85% ◇ Bronze
+**Status:** Production-ready with minor cleanup needed
+
+---
+
+## 🚨 CRITICAL (Fix Now)
+
+### 1. Security: `open@10` breaking CI/CD
+- **Impact:** Release pipeline failing
+- **Fix:** Pin to `open@8.4.2` ✅ FIXED
+- **Effort:** 5 minutes
+- **Auto-fix:** Available
+
+---
+
+## ⚠️  MEDIUM (This Week)
+
+### 3. .gitignore Gaps
+- **Issue:** `*.config.mjs`, `*.faf` test files not ignored
+- **Fix:** Add patterns to .gitignore
+- **Effort:** 1 minute
+- **Auto-fix:** Available
+  ```gitignore
+  *.config.mjs
+  test-*.faf
+  ```
+
+---
+
+## ℹ️  LOW (Nice to Have)
+
+### 6. README Links
+- **Issue:** 2 broken links to old docs
+- **Fix:** Update URLs
+- **Effort:** 5 minutes
+
+### 7. Unused Dependencies
+- **Issue:** `depcheck` found unused packages
+- **Fix:** Remove or document why needed
+
+---
+
+## ✅ EXCELLENT
+
+- Test coverage: 799/799 passing
+- TypeScript strict mode: enabled
+- FAF score: 83% (good)
+- CI/CD: All workflows aligned
+- Security: No critical vulnerabilities
+- Documentation: CLAUDE.md in sync
+
+---
+
+## 🎯 RECOMMENDED ACTIONS
+
+**Quick wins:** .gitignore + CHANGELOG entry + README links + safe `npm update`.
+**This week:** triage TODOs, remove unused deps, bump patch.
+**Monthly:** full dependency audit, large-file scan, perf baseline.
+
+---
+
+## 🔧 AUTO-FIX AVAILABLE
+
+I can automatically fix:
+- ✅ .gitignore additions
+- ✅ CHANGELOG draft
+- ✅ Safe dependency updates
+- ✅ Workflow alignment
+
+**Run auto-fix?** (yes/no)
+```
+
+---
+
+### 🤖 **Phase 3: Auto-Fix (Optional)**
+
+For safe, non-breaking fixes:
+
+```bash
+# 1. Update .gitignore
+cat >> .gitignore <<EOF
+
+# Auto-added by repo-maintainer
+*.config.mjs
+*.faf.backup
+.faf-dna.tmp
+test-*.faf
+EOF
+
+# 2. Generate CHANGELOG entry from git log
+git log v4.3.3..v4.4.0 --pretty=format:"- %s (%h)" >> CHANGELOG.draft.md
+
+# 3. Safe dependency updates (non-breaking)
+npm update --save
+
+# 4. Create cleanup branch
+git checkout -b repo-maintenance/$(date +%Y-%m-%d)
+git add .gitignore CHANGELOG.md package.json package-lock.json
+git commit -m "chore: repo maintenance - cleanup artifacts and update deps
+
+- Add missing .gitignore patterns
+- Update CHANGELOG with v4.4.0
+- Safe dependency updates (patch/minor only)
+
+Generated by /repo-maintainer skill"
+```
+
+---
+
+## Workflow
+
+### Step 1: Initial Assessment
+```bash
+# Quick health check
+pwd
+git status
+git log --oneline -5
+ls -la | head -20
+```
+
+### Step 2: Systematic Audit
+
+Run checks in order of priority:
+
+1. **Critical first** - CI/CD failures, security issues
+2. **Medium next** - Dependencies, documentation gaps
+3. **Low priority** - Code quality signals, nice-to-haves
+
+### Step 3: Generate Report
+
+Create structured report with:
+- Overall health score (0-100%)
+- Critical/Medium/Low sections
+- Effort estimates
+- Auto-fix availability
+- Recommended action plan
+
+### Step 4: Execute (with approval)
+
+Ask user:
+- "Run auto-fix for safe items?"
+- "Create cleanup branch?"
+- "Open issues for manual items?"
+
+Never make changes without explicit approval.
+
+---
+
+## MCP Server Maintenance
+
+### Additional MCP Checks:
+
+```bash
+# 1. MCP-specific structure
+package.json has "mcp" field
+Server exports via index.ts
+Tools properly registered
+
+# 2. Registry compliance
+Registry listing accurate (npm + MCP registry)
+README has MCP install instructions
+Works with Claude Desktop config
+
+# 3. Tool coverage
+Each tool has tests
+Each tool has description
+Error handling implemented
+
+# 4. Version alignment
+package.json version
+git tag version
+MCP registry version
+npm published version
+```
+
+### MCP Cleanup Checklist:
+
+- [ ] Remove test artifacts
+- [ ] Update dependencies
+- [ ] Align workflows (Node 18/20/22)
+- [ ] Verify MCP tools still work
+- [ ] Update README examples
+- [ ] Check CHANGELOG current
+- [ ] Verify published to npm
+- [ ] Confirm registry listing accurate
+
+---
+
+## ✪ Tier System (Aligned with FAF)
+
+**CRITICAL: Use Official FAF Tiers for All Scoring**
+
+| Score | Tier | Symbol | Status |
+|-------|------|--------|--------|
+| 100% | Trophy | ✪ | Perfect — Gold Code |
+| 99% | Gold | ★ | Exceptional |
+| 95% | Silver | ◆ | Top tier |
+| 85% | Bronze | ◇ | Production ready |
+| 70% | Green | ● | Solid foundation |
+| 55% | Yellow | ● | Needs improvement |
+| 1% | Red | ○ | Major work needed |
+| 0% | White | ♡ | Empty |
+
+The score is **deterministic** — same input → same score, every time. **FAF doesn't lie.**
+
+**Note:** 🍊 **Big Orange** is an **HONOR**, not a score or a badge. It recognizes sustained excellence across multiple criteria; it is never calculated from a single score.
+
+**Apply These Tiers to:**
+- Overall repo health score
+- Individual category scores (CI/CD, Dependencies, etc.)
+- Summary reports
+- Cleanup recommendations
+
+**Examples:**
+```
+95% Security     → ◆ Silver
+88% Overall      → ◇ Bronze
+78% Dependencies → ● Green
+70% Git Hygiene  → ● Green
+40% CI/CD        → ○ Red
+100% Tests       → ✪ Trophy
+```
+
+---
+
+## Related Skills
+
+- `/wjttc-builder` · `/wjttc-tester` - generate + run championship-grade tests before a release
+- `/faf-expert` - master the `.faf` format + score the repo's AI-readiness
+
+---
+
+## Best Practices
+
+### 1. **Run Regularly**
+- After major refactors
+- Before releases
+- Monthly maintenance
+- When onboarding new devs
+
+### 2. **Prioritize Impact**
+- Fix breaking issues first (CI/CD, security)
+- Document before cleaning (understand why artifacts exist)
+- Test after cleanup (ensure nothing broke)
+
+### 3. **Track Progress**
+- Use TodoWrite for multi-step cleanups
+- Create issues for manual items
+- Document decisions in CLAUDE.md
+
+### 4. **Automate Where Safe**
+- .gitignore additions ✅
+- CHANGELOG drafts ✅
+- Workflow alignment ✅
+- Breaking changes ❌ (need review)
+
+---
+
+## Example Session
+
+```
+User: /repo-maintainer
+
+Claude: 🏎️ Starting championship repo maintenance audit...
+
+[Runs git status]
+[Checks workflows]
+[Scans for artifacts]
+[Runs npm outdated]
+[Checks .gitignore]
+
+📊 AUDIT COMPLETE
+
+Overall Health: 85% ◇ Bronze
+Critical Issues: 2
+Medium Issues: 3
+Low Priority: 5
+
+Top Issues:
+1. 🚨 open@10 breaking CI/CD (auto-fixable)
+2. 🚨 Node 16 in workflows (EOL)
+3. ⚠️  .gitignore missing *.config.mjs
+4. ⚠️  15 outdated dependencies
+5. ⚠️  CHANGELOG missing v4.4.0
+
+I can auto-fix items 1, 2, 3, and draft 5.
+Would you like me to proceed? (yes/no)
+
+User: yes
+
+Claude: ✅ Fixing...
+[Pins open@8.4.2]
+[Updates workflows to Node 20]
+[Adds .gitignore patterns]
+[Drafts CHANGELOG entry]
+
+✅ Auto-fixes complete!
+
+Remaining manual items:
+- Review 15 dependency updates
+- 3 TODO comments need review
+
+Create cleanup branch? (yes/no)
+```
+
+---
+
+## The Championship Promise
+
+> "Pit crews service the car between every race.
+> Your repos deserve the same attention."
+
+---
+
+*Repo Maintainer - Championship Repository Hygiene*
+*"When brakes must work flawlessly, so must our repos."*
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: resolving-merge-conflicts
+description: Use when you need to resolve an in-progress git merge/rebase conflict.
+risk: unknown
+source: https://github.com/mattpocock/skills/tree/main/skills/engineering/resolving-merge-conflicts
+source_repo: mattpocock/skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/mattpocock/skills/blob/main/LICENSE
+---
+
+
+## When to Use
+
+Use when you need to resolve an in-progress git merge/rebase conflict.
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/review-and-simplify-changes/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: review-and-simplify-changes
+description: Review a git diff or explicit file scope for reuse, code quality, efficiency, clarity, and standards issues, then optionally apply safe Codex-driven fixes. Use when the user asks to "simplify code", "review changed code", "check for code reuse", "review code quality", "review...
+risk: unknown
+source: https://github.com/Dimillian/Skills/tree/main/review-and-simplify-changes
+source_repo: Dimillian/Skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/Dimillian/Skills/blob/main/LICENSE
+---
+
+# Review and Simplify Changes
+## When to Use
+
+Use this skill when you need review a git diff or explicit file scope for reuse, code quality, efficiency, clarity, and standards issues, then optionally apply safe Codex-driven fixes. Use when the user asks to "simplify code", "review changed code", "check for code reuse", "review code quality", "review...
+
+
+Review changed code for reuse, quality, efficiency, and clarity issues. Use Codex sub-agents to review in parallel, but keep those sub-agents read-only: they should only inspect code and send findings back to the main agent. Only the main agent may apply high-confidence, behavior-preserving fixes.
+
+## Modes
+
+Choose the mode from the user's request:
+
+- `review-only`: user asks to review, audit, or check the changes
+- `safe-fixes`: user asks to simplify, clean up, or refactor the changes
+- `fix-and-validate`: same as `safe-fixes`, but also run the smallest relevant validation after edits
+
+If the user does not specify, default to:
+
+- `review-only` for "review", "audit", or "check"
+- `safe-fixes` for "simplify", "clean up", or "refactor"
+
+## Step 1: Determine the Scope and Diff Command
+
+Prefer this scope order:
+
+1. Files or paths explicitly named by the user
+2. Current git changes
+3. Files edited earlier in the current Codex turn
+4. Most recently modified tracked files, only if the user asked for a review but there is no diff
+
+If there is no clear scope, stop and say so briefly.
+
+When using git changes, determine the smallest correct diff command based on the repo state:
+
+- unstaged work: `git diff`
+- staged work: `git diff --cached`
+- branch or commit comparison explicitly requested by the user: use that exact diff target
+- mixed staged and unstaged work: review both
+
+Do not assume `git diff HEAD` is the right default when a smaller diff is available.
+
+Before reviewing standards or applying fixes, read the repo's local instruction files and relevant project docs for the touched area. Prefer the closest applicable guidance, such as:
+
+- `AGENTS.md`
+- repo workflow docs
+- architecture or style docs for the touched module
+
+Use those instructions to distinguish real issues from intentional local patterns.
+
+## Step 2: Launch Four Read-Only Review Sub-Agents in Parallel
+
+Use Codex sub-agents when the scope is large enough for parallel review to help. For a tiny diff or one very small file, it is acceptable to review locally instead.
+
+When spawning sub-agents:
+
+- give each sub-agent the same scope
+- tell each sub-agent to inspect only its assigned review role
+- tell each sub-agent it is operating in a read-only review pass
+- do not let sub-agents edit files, run `apply_patch`, stage changes, commit, or perform other state-mutating actions
+- ask for concise, structured findings only
+- ask each sub-agent to report file, line or symbol, problem, recommended fix, and confidence
+- ask each sub-agent to return findings to the main agent only; they must not implement fixes themselves
+
+Use four review roles.
+
+### Sub-Agent 1: Code Reuse Review
+
+Review the changes for reuse opportunities:
+
+1. Search for existing helpers, utilities, or shared abstractions that already solve the same problem.
+2. Flag duplicated functions or near-duplicate logic introduced in the change.
+3. Flag inline logic that should call an existing helper instead of re-implementing it.
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `explorer` for broad codebase lookup, or `reviewer` if a stronger review pass is more useful than wide search.
+
+### Sub-Agent 2: Code Quality Review
+
+Review the same changes for code quality issues:
+
+1. Redundant state, cached values, or derived values stored unnecessarily
+2. Parameter sprawl caused by threading new arguments through existing call chains
+3. Copy-paste with slight variation that should become a shared abstraction
+4. Leaky abstractions or ownership violations across module boundaries
+5. Stringly-typed values where existing typed contracts, enums, or constants already exist
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+### Sub-Agent 3: Efficiency Review
+
+Review the same changes for efficiency issues:
+
+1. Repeated work, duplicate reads, duplicate API calls, or unnecessary recomputation
+2. Sequential work that could safely run concurrently
+3. New work added to startup, render, request, or other hot paths without clear need
+4. Pre-checks for existence when the operation itself can be attempted directly and errors handled
+5. Memory growth, missing cleanup, or listener/subscription leaks
+6. Overly broad reads or scans when the code only needs a subset
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+### Sub-Agent 4: Clarity and Standards Review
+
+Review the same changes for clarity, local standards, and balance:
+
+1. Violations of local project conventions or module patterns
+2. Unnecessary complexity, deep nesting, weak names, or redundant comments
+3. Overly compact or clever code that reduces readability
+4. Over-simplification that collapses separate concerns into one unclear unit
+5. Dead code, dead abstractions, or indirection without value
+
+This sub-agent is read-only. It must not edit files, apply patches, or make any other workspace changes.
+
+Recommended sub-agent role: `reviewer`
+
+Only report issues that materially improve maintainability, correctness, or cost. Do not churn code just to make it look different.
+
+## Step 3: Aggregate Findings
+
+Wait for all review sub-agents to complete, then merge their findings.
+
+The main agent owns this step. Treat sub-agent output as review input only, not as permission to delegate code changes back out.
+
+Normalize findings into this shape:
+
+1. File and line or nearest symbol
+2. Category: reuse, quality, efficiency, or clarity
+3. Why it is a problem
+4. Recommended fix
+5. Confidence: high, medium, or low
+
+Discard weak, duplicative, or instruction-conflicting findings before editing.
+
+## Step 4: Fix Issues Carefully
+
+In `review-only` mode, stop after reporting findings.
+
+In `safe-fixes` or `fix-and-validate` mode:
+
+- Only the main agent applies fixes for this skill
+- Apply only high-confidence, behavior-preserving fixes
+- Skip subjective refactors that need product or architectural judgment
+- Preserve local patterns when they are intentional or instruction-backed
+- Keep edits scoped to the reviewed files unless a small adjacent change is required to complete the fix correctly
+
+Prefer fixes like:
+
+- replacing duplicated code with an existing helper
+- removing redundant state or dead code
+- simplifying control flow without changing behavior
+- narrowing overly broad operations
+- renaming unclear locals when the scope is contained
+
+Do not stage, commit, or push changes as part of this skill.
+
+## Step 5: Validate When Required
+
+In `fix-and-validate` mode, after the main agent finishes edits, run the smallest relevant validation for the touched scope.
+
+Examples:
+
+- targeted tests for the touched module
+- typecheck or compile for the touched target
+- formatter or lint check if that is the project's real safety gate
+
+Prefer fast, scoped validation over full-suite runs unless the change breadth justifies more.
+
+If validation is skipped because the user asked not to run it, say so explicitly.
+
+## Step 6: Summarize Outcome
+
+Close with a brief result:
+
+- what was reviewed
+- what was fixed, if anything
+- what was intentionally left alone
+- whether validation ran
+
+If the code is already clean for this rubric, say that directly instead of manufacturing edits.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.