repo-maintainer

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

# 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

# Check package health
npm outdated
npm audit
npx depcheck (find unused deps)
Check for pinned versions ([email protected] 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

# 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

# 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

# .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:

# Add to .gitignore based on artifacts found
*.config.mjs
*.faf.backup
.faf-dna.tmp
test-*.faf

6. Code Quality Signals

# 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:

# 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:

# 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:

# 🏎️ 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 `[email protected]` ✅ 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

# 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:

# 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 [email protected]]
[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.