maintenance-automation.md
1 --- 2 title: 'Maintenance Automation' 3 category: 'operations' 4 last_verified: '2026-02-15' 5 related_files: 6 - 'scripts/validate-commit-msg.js' 7 - 'scripts/maintenance/weekly-check.js' 8 - 'scripts/maintenance/db-health.js' 9 tags: ['maintenance', 'automation', 'cron', 'scheduling', 'testing', 'security', 'database', 'api'] 10 status: 'current' 11 --- 12 13 # Maintenance Automation: Methods Comparison 14 15 This document compares different approaches for automating maintenance tasks during active development and production. 16 17 ## Overview of Methods 18 19 ### 1. Claude Rules (CLAUDE.md Instructions) 20 21 **What:** Instructions in CLAUDE.md that Claude Code follows during development sessions 22 23 ### 2. Git Hooks 24 25 **What:** Scripts that run automatically on git events (commit, push, etc.) 26 27 ### 3. GitHub Actions 28 29 **What:** CI/CD workflows that run on GitHub events (push, PR, schedule) 30 31 ### 4. Specialized Claude Code Agents 32 33 **What:** Purpose-built agents invoked via Task tool for specific maintenance workflows 34 35 ### 5. npm Scripts + Manual Workflow 36 37 **What:** Pre-defined npm scripts that developers run manually 38 39 --- 40 41 ## Detailed Comparison 42 43 ### Claude Rules (CLAUDE.md) 44 45 **How it works:** 46 47 - Add instructions to CLAUDE.md that Claude Code reads at session start 48 - Claude proactively runs tasks based on rules and context 49 - Example: "After making code changes, run quality-check if not run today" 50 51 **Pros:** 52 ✅ No setup required - just edit CLAUDE.md 53 ✅ Context-aware - Claude decides when tasks are relevant 54 ✅ Works immediately in current workflow 55 ✅ Can adapt to conversation context 56 ✅ Great for development-time checks 57 ✅ Natural language instructions (easy to modify) 58 59 **Cons:** 60 ❌ Only runs when Claude Code is active 61 ❌ Depends on Claude remembering and following rules 62 ❌ Not guaranteed to run (if context is unclear) 63 ❌ Won't run outside development sessions 64 ❌ Token usage for running tasks 65 66 **Best for:** 67 68 - Quality checks during active development 69 - Reminders to run tests after code changes 70 - Suggesting maintenance when relevant 71 - Exploratory analysis tasks 72 73 **Example CLAUDE.md rule:** 74 75 ```markdown 76 ## Development Quality Checks 77 78 After making code changes, ensure quality checks run: 79 80 **Mandatory before committing:** 81 82 - Run `npm test` if any .js files modified 83 - Run `npm run lint:fix` to auto-fix formatting issues 84 - Check test coverage if adding new functions 85 86 **Daily (if not already run today):** 87 88 - Run `npm audit` to check for vulnerabilities 89 - Run `npm run quality-check` to ensure code quality 90 91 **Weekly reminder (check with user):** 92 93 - Ask if user wants to review Dependabot PRs 94 - Suggest running documentation audit if docs seem outdated 95 ``` 96 97 --- 98 99 ### Git Hooks 100 101 **How it works:** 102 103 - Scripts in `.git/hooks/` or managed by husky/simple-git-hooks 104 - Automatically execute on git events (pre-commit, pre-push, etc.) 105 - Can block commits/pushes if checks fail 106 107 **Pros:** 108 ✅ Guaranteed execution on git events 109 ✅ Runs locally before pushing to remote 110 ✅ Fast feedback loop 111 ✅ Enforces standards (blocks bad commits) 112 ✅ Works without human memory 113 ✅ No CI/CD costs 114 115 **Cons:** 116 ❌ Can be bypassed with `--no-verify` 117 ❌ Slows down commit/push operations 118 ❌ Only runs on git operations 119 ❌ Can be annoying if slow/strict 120 ❌ Requires setup on each machine 121 ❌ May break developer flow 122 123 **Best for:** 124 125 - Pre-commit: formatting (Prettier), linting (ESLint) 126 - Pre-commit: preventing secrets from being committed 127 - Pre-push: running tests before pushing 128 - Commit-msg: validating commit message format 129 130 **Not recommended for:** 131 132 - Slow operations (>30 seconds) 133 - Operations requiring network access 134 - Optional/advisory checks 135 136 **Example setup (using simple-git-hooks):** 137 138 ```json 139 // package.json 140 { 141 "simple-git-hooks": { 142 "pre-commit": "npm run lint:fix && npm test", 143 "pre-push": "npm run quality-check", 144 "commit-msg": "node scripts/validate-commit-msg.js" 145 } 146 } 147 ``` 148 149 --- 150 151 ### GitHub Actions 152 153 **How it works:** 154 155 - YAML workflows in `.github/workflows/` 156 - Trigger on events: push, PR, schedule, manual dispatch 157 - Runs in GitHub's cloud infrastructure 158 159 **Pros:** 160 ✅ Runs automatically on every push/PR 161 ✅ Platform-independent (not just local dev) 162 ✅ Can schedule periodic tasks (cron) 163 ✅ Great for team collaboration 164 ✅ Prevents bad code from merging 165 ✅ Detailed logs and history 166 ✅ Can deploy/publish artifacts 167 ✅ Free for public repos (generous limits for private) 168 169 **Cons:** 170 ❌ Requires GitHub infrastructure 171 ❌ Slower feedback than local checks 172 ❌ Uses CI/CD minutes (limits on free tier) 173 ❌ More complex setup than git hooks 174 ❌ Network latency delays 175 ❌ Won't catch issues until after push 176 177 **Best for:** 178 179 - Automated testing on PR 180 - Security scanning (CodeQL, dependabot) 181 - Scheduled maintenance tasks 182 - Deployment pipelines 183 - Cross-platform testing 184 - Generating reports/artifacts 185 186 **Example workflow:** 187 188 ```yaml 189 # .github/workflows/maintenance.yml 190 name: Weekly Maintenance 191 192 on: 193 schedule: 194 - cron: '0 9 * * 1' # Every Monday at 9am UTC 195 workflow_dispatch: # Manual trigger 196 197 jobs: 198 maintenance: 199 runs-on: ubuntu-latest 200 steps: 201 - uses: actions/checkout@v4 202 - uses: actions/setup-node@v4 203 with: 204 node-version: '20' 205 - run: npm ci 206 - run: npm audit 207 - run: npm outdated || true 208 - run: npm test 209 - name: Comment on issues if failures 210 if: failure() 211 uses: actions/github-script@v7 212 with: 213 script: | 214 github.rest.issues.create({ 215 owner: context.repo.owner, 216 repo: context.repo.repo, 217 title: 'Weekly maintenance check failed', 218 body: 'Automated maintenance checks failed. Please review.' 219 }) 220 ``` 221 222 --- 223 224 ### Specialized Claude Code Agents 225 226 **How it works:** 227 228 - Create dedicated agents via Task tool for specific maintenance workflows 229 - Example: "maintenance-agent" that runs full health check 230 - Invoked when needed during Claude Code sessions 231 232 **Pros:** 233 ✅ Can handle complex multi-step workflows 234 ✅ Context-aware decisions 235 ✅ Can interact with user for approval 236 ✅ Generates detailed reports 237 ✅ Learns from codebase during execution 238 ✅ Can fix issues autonomously 239 240 **Cons:** 241 ❌ Only runs during Claude Code sessions 242 ❌ Higher token usage 243 ❌ Slower than scripts 244 ❌ Requires user to remember to invoke 245 ❌ Not automatic 246 247 **Best for:** 248 249 - Complex audits requiring analysis 250 - Tasks needing human decisions 251 - Exploratory maintenance tasks 252 - Generating actionable reports 253 - One-off or occasional deep dives 254 255 **Example agent invocation:** 256 257 ```javascript 258 // User asks: "Run the weekly maintenance check" 259 // Claude Code invokes: 260 Task({ 261 subagent_type: 'general-purpose', 262 description: 'Weekly maintenance health check', 263 prompt: ` 264 Run a comprehensive weekly maintenance check: 265 1. Run npm audit and report vulnerabilities 266 2. Check for outdated packages (npm outdated) 267 3. Run full test suite and check coverage 268 4. Check database integrity 269 5. Generate summary report with actionable items 270 6. Flag anything requiring human review 271 `, 272 }); 273 ``` 274 275 --- 276 277 ### npm Scripts + Manual Workflow 278 279 **How it works:** 280 281 - Define scripts in package.json 282 - Developer runs manually: `npm run maintenance` 283 - Can be triggered by other automation 284 285 **Pros:** 286 ✅ Simple to set up 287 ✅ Explicit control (runs when you want) 288 ✅ No surprises during development 289 ✅ Easy to debug 290 ✅ Portable (works anywhere npm works) 291 292 **Cons:** 293 ❌ Requires discipline to remember 294 ❌ Inconsistent execution 295 ❌ Easy to forget 296 ❌ Not automatic 297 298 **Best for:** 299 300 - On-demand checks 301 - Debugging/investigation 302 - Tasks requiring parameters 303 - Complex workflows requiring human judgment 304 305 --- 306 307 ## Recommended Hybrid Approach 308 309 ### For Active Development (Code Changes) 310 311 **Use: Claude Rules + Git Hooks** 312 313 **Claude Rules in CLAUDE.md:** 314 315 ```markdown 316 ## Development Quality Protocol 317 318 **After modifying code files:** 319 320 1. Run `npm test` to verify tests pass 321 2. Run `npm run lint:fix` to auto-fix issues 322 3. Check coverage if adding new functions: `npm test` (review coverage/index.html) 323 324 **Before committing:** 325 326 - Verify you've run tests and they pass 327 - Check that formatting is clean (Prettier) 328 - Ensure no console.logs or debugger statements 329 330 **Daily development checks (if not run today):** 331 332 - `npm audit` - Check for new vulnerabilities 333 - `npm run quality-check` - Full quality check including Sage AI 334 335 **When you notice:** 336 337 - New environment variables → Update .env.example 338 - New npm scripts → Update README.md 339 - New files/directories → Update CLAUDE.md if architectural 340 - API changes → Update relevant documentation 341 ``` 342 343 **Git Hooks (via simple-git-hooks):** 344 345 ```json 346 { 347 "simple-git-hooks": { 348 "pre-commit": "npm run format && npm run lint", 349 "pre-push": "npm test" 350 } 351 } 352 ``` 353 354 ### For Scheduled Maintenance 355 356 **Use: GitHub Actions (preferred) or cron + scripts** 357 358 **GitHub Actions for:** 359 360 - Weekly: Dependency check, security scan, coverage report 361 - On PR: Full test suite, lint check, build verification 362 - Daily: Database backup, health check 363 364 **Local cron for:** 365 366 - Database backup (if not using cloud) 367 - Email event sync (already set up) 368 369 ### For Deep Analysis 370 371 **Use: Specialized Claude Code Agents** 372 373 When you need: 374 375 - "Review codebase for unused code" 376 - "Audit documentation for outdated references" 377 - "Analyze test coverage gaps and suggest additions" 378 - "Security audit for potential vulnerabilities" 379 380 ### For On-Demand Tasks 381 382 **Use: npm Scripts** 383 384 Keep simple, well-named scripts: 385 386 ```json 387 { 388 "scripts": { 389 "maint:weekly": "node scripts/maintenance/weekly-check.js", 390 "maint:db": "node scripts/maintenance/db-health.js", 391 "maint:audit": "npm audit && npm outdated && npm test" 392 } 393 } 394 ``` 395 396 --- 397 398 ## Specific Recommendations for 333 Method 399 400 ### Immediate Setup (Low Effort, High Value) 401 402 **1. Add Git Hooks (5 minutes)** 403 404 ```bash 405 npm install --save-dev simple-git-hooks 406 ``` 407 408 ```json 409 // package.json 410 { 411 "scripts": { 412 "prepare": "simple-git-hooks" 413 }, 414 "simple-git-hooks": { 415 "pre-commit": "npm run format && npm run lint", 416 "pre-push": "npm test" 417 } 418 } 419 ``` 420 421 ```bash 422 npm run prepare 423 ``` 424 425 **2. Update CLAUDE.md with Development Rules (2 minutes)** 426 427 Add the "Development Quality Protocol" section shown above to CLAUDE.md. 428 429 **3. Set up GitHub Action for PR checks (10 minutes)** 430 431 Create `.github/workflows/pr-check.yml`: 432 433 ```yaml 434 name: PR Quality Check 435 436 on: 437 pull_request: 438 branches: [main] 439 push: 440 branches: [main] 441 442 jobs: 443 quality: 444 runs-on: ubuntu-latest 445 steps: 446 - uses: actions/checkout@v4 447 - uses: actions/setup-node@v4 448 with: 449 node-version: '20' 450 - run: npm ci 451 - run: npm run lint 452 - run: npm test 453 - run: npm audit --audit-level=moderate 454 ``` 455 456 ### Progressive Enhancement 457 458 **Phase 2: Weekly Automation (20 minutes)** 459 460 1. Create GitHub Action for scheduled maintenance 461 2. Add database backup script 462 3. Set up Dependabot auto-merge for patches 463 464 **Phase 3: Advanced (1-2 hours)** 465 466 1. Create maintenance dashboard script 467 2. Set up monitoring/alerting 468 3. Create specialized Claude Code agents for audits 469 470 --- 471 472 ## Decision Matrix 473 474 | Task | Method | Frequency | Why | 475 | --------------------- | --------------------- | ------------ | ------------------- | 476 | Format code | Git Hook (pre-commit) | Every commit | Must be consistent | 477 | Lint check | Git Hook (pre-commit) | Every commit | Catch errors early | 478 | Run tests | Git Hook (pre-push) | Every push | Prevent broken code | 479 | Quality reminder | Claude Rule | During dev | Context-aware | 480 | Security scan | GitHub Action | Weekly | Scheduled | 481 | Coverage report | GitHub Action | Weekly | Team visibility | 482 | Unused code detection | Claude Agent | Monthly | Needs analysis | 483 | Documentation audit | Claude Agent | Monthly | Needs analysis | 484 | Database backup | Cron | Daily | Critical data | 485 | Update dependencies | Dependabot + Manual | Weekly | Review PRs | 486 | Emergency fix | npm Script + Manual | As needed | Immediate control | 487 488 --- 489 490 ## Implementation Plan 491 492 ### Step 1: Immediate (This Session) 493 494 1. ✅ Create MAINTENANCE.md with full plan 495 2. ⬜ Add git hooks via simple-git-hooks 496 3. ⬜ Update CLAUDE.md with development quality protocol 497 4. ⬜ Create basic GitHub Action for PR checks 498 499 ### Step 2: This Week 500 501 1. ⬜ Test git hooks workflow 502 2. ⬜ Add weekly maintenance GitHub Action 503 3. ⬜ Create npm script for quick health check 504 4. ⬜ Document workflow in README.md 505 506 ### Step 3: This Month 507 508 1. ⬜ Create maintenance dashboard script 509 2. ⬜ Set up automated database backups 510 3. ⬜ Review and refine automation based on experience 511 512 --- 513 514 ## Conclusion 515 516 **Best approach for your use case:** 517 518 **During Active Development (Multiple times per day):** 519 520 - **Claude Rules** for context-aware reminders and quality checks 521 - **Git Hooks** for mandatory formatting/linting/testing 522 - **npm Scripts** for on-demand deep checks 523 524 **For Regular Maintenance (Weekly/Monthly):** 525 526 - **GitHub Actions** for scheduled automated checks 527 - **Claude Agents** for analysis tasks requiring judgment 528 - **Dependabot** for dependency updates 529 530 **For Production Monitoring:** 531 532 - **GitHub Actions** with cron schedules 533 - **External monitoring** if deploying commercially 534 535 This hybrid approach gives you: 536 537 - ✅ Automatic enforcement of standards (git hooks) 538 - ✅ Context-aware assistance during development (Claude rules) 539 - ✅ Scheduled maintenance without manual effort (GitHub Actions) 540 - ✅ Deep analysis when needed (Claude agents) 541 - ✅ Flexibility for ad-hoc tasks (npm scripts) 542 543 The key is **layering different methods** based on when and how often checks should run, rather than relying on a single approach.