481 lines
11 KiB
Markdown
481 lines
11 KiB
Markdown
---
|
||
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.
|