repo-maintainer git:20261023.8192183A

Immutable. This exact content never changes and is served at /api/v1/blob/b7c93a7d5ee10736.

---
name: repo-maintainer
description: 'Use when someone wants a repository cleaned up or checked: "clean up this repo", "audit the repo", "health check before the release". Audits leftover test artifacts, dependencies, CI workflows, docs that have drifted from the code, git hygiene and FAF alignment, then writes a cleanup plan ordered by impact. Changes nothing without approval.'
license: MIT
---

# 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`
- 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 (current LTS lines, e.g. 22/24)
- 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 written from project.faf (`faf sync`, one way)
- .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
*.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)
Sync alignment — .faf → CLAUDE.md (run `faf sync`; one way, writes faf's block only)
MCP server compliance (if applicable)
WJTTC test coverage (for faf-cli, MCP servers)
```

For MCP servers:
```bash
# MCP-specific checks
package.json has "mcpName" + server.json (MCP Registry)
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 + a reviewed `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
*.faf.backup
.faf-dna.tmp
test-*.faf
EOF

# 2. Generate CHANGELOG entry from git log
git log <last-tag>..HEAD --pretty=format:"- %s (%h)" >> CHANGELOG.draft.md   # review, then merge into CHANGELOG.md

# 3. Dependency updates — REVIEW REQUIRED: show the diff and run the tests before committing
npm update --save

# 4. Create cleanup branch
git checkout -b repo-maintenance/$(date +%Y-%m-%d)
git add .gitignore CHANGELOG.draft.md package.json package-lock.json
git commit -m "chore: repo maintenance - cleanup artifacts and update deps

- Add missing .gitignore patterns
- Draft CHANGELOG entry since the last tag
- Dependency updates (patch/minor, reviewed and tested)

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 "mcpName" + server.json (MCP Registry)
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 (supported Node LTS lines only)
- [ ] 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 | ✪ | AI is optimized to 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. [critical] open@10 breaking CI/CD (auto-fixable)
2. [critical] Node 16 in workflows (EOL)
3. [medium] .gitignore missing *.faf.backup
4. [medium] 15 outdated dependencies
5. [medium] 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 the current Node LTS]
[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."*