wolfe-jam/faf-skills/repo-maintainer

v: 1
needs: [git, "npx (for depcheck and npm outdated)", "faf-cli, for the FAF alignment check"]
reads: [the repository, dependencies, CI workflows, docs, git history]
writes:
  - "the health report and the cleanup plan"
  - "approved changes only, after an explicit yes"
network: ["registry.npmjs.org (read: depcheck, npm outdated)"]
publishes: false
done_when: "the health report and the cleanup plan, ordered by impact, are written; nothing changed without approval"
project: project.faf

# 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

# Check package health
npm outdated
npm audit
npx depcheck (find unused deps)
Check for pinned versions (inquirer@8.2.5 pattern)
Verify Dependabot config

# 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

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

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

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

# 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

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

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

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

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

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

# 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

95% Security     → ◆ Silver
88% Overall      → ◇ Bronze
78% Dependencies → ● Green
70% Git Hygiene  → ● Green
40% CI/CD        → ○ Red
100% Tests       → ✪ Trophy

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)