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 (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

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

# Quick health check
pwd
git status
git log --oneline -5
ls -la | head -20

Step 2: Systematic Audit

Run checks in order of priority:

Critical first - CI/CD failures, security issues
Medium next - Dependencies, documentation gaps
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:

✪ 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.

Repo Maintainer - Championship Repository Hygiene

AI Summary

Repo Maintainer - Championship Repository Hygiene

When to Use This Skill

What This Skill Does

🔍 Phase 1: Comprehensive Audit

1. Artifact Detection

2. Dependency Health

3. CI/CD Alignment

4. Documentation Sync

5. Git Hygiene

6. Code Quality Signals

7. FAF Ecosystem Health

🛠️ Phase 2: Cleanup Plan Generation

ℹ️ LOW (Nice to Have)

6. README Links

7. Unused Dependencies

✅ EXCELLENT

🎯 RECOMMENDED ACTIONS

🔧 AUTO-FIX AVAILABLE

Workflow

Step 1: Initial Assessment

Step 2: Systematic Audit

Step 3: Generate Report

Step 4: Execute (with approval)

MCP Server Maintenance

Additional MCP Checks:

MCP Cleanup Checklist:

✪ Tier System (Aligned with FAF)

Related Skills

Best Practices

1. Run Regularly

2. Prioritize Impact

3. Track Progress

4. Automate Where Safe

Example Session

The Championship Promise

Limitations

Related skills