weekly-maintenance
Skill9 starsChanged 3 months agoMITView on GitHub
Execute comprehensive weekly maintenance routine (1-2 hours, Friday recommended). Includes health checks, quality review, dependency governance, activity insights, and planning.
In this repository56 other files it gives its agents.
- .claude/agents/CLAUDE.mdCLAUDE.md
- .claude/hooks/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .claude/prompts/CLAUDE.mdCLAUDE.md
- .claude/rules/CLAUDE.mdCLAUDE.md
- .claude/skills/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- vision/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- scaffold/llms.txtllms.txt
- architecture-checkSkill
- backlog-reviewSkill
- bootstrapSkill
- brainstormSkill
- buildSkill
- claude-sense-checkSkill
- code-qualitySkill
- commitSkill
- continueSkill
- custom-hooksSkill
- dashboardSkill
- debug-sessionSkill
- deploySkill
- discoverSkill
- doctorSkill
- fix-issueSkill
- framework-upgradeSkill
- handoffSkill
- help-meSkill
- ideateSkill
- lanesSkill
- manual-testSkill
- merge-downSkill
- merge-upSkill
- optimizeSkill
- parallel-workSkill
- performance-checkSkill
- phase-reviewSkill
- pr-statusSkill
- quality-checkSkill
- quickstartSkill
- refine-loopSkill
- researchSkill
- retrospectiveSkill
- security-auditSkill
- skill-createSkill
- skill-evalSkill
- sprint-endSkill
- sprint-startSkill
- story-cycleSkill
- testing-cycleSkill
- test-validatorSkill
- UAT-cycleSkill
- undo-workSkill
- uninstallSkill
- wrap-upSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Run the project's quality/health tools (from CLAUDE.md Commands section):
- Distinctive: line 36
Use the code-quality skill to analyze the entire codebase:
- Distinctive: line 40
Check for pattern consistency violations
- Distinctive: line 44
Check key documentation for accuracy:
- Very specific: line 50
Metrics freshness: If docs/progress.md → ## Sprint History has ≥2 data rows but ## Metrics table still shows "—" values, sprint-end is not …
- Distinctive: line 54
Check for outdated dependencies using the project's package manager:
- Distinctive: line 62
Run dependency auditing tools:
- Very specific: line 93
Read docs/reference/SECRETS_INVENTORY.md and check:
- Very specific: line 99
If docs/reference/SECRETS_INVENTORY.md does not exist but the project uses environment variables or credentials, note this as a gap: "No …
- Distinctive: line 103
Run the project's dependency audit tool (same as section 4, but focused on security):
- Very specific: line 118
Read docs/technical-debt.md and perform the weekly debt review:
- Distinctive: line 128
Check this week's commits and code quality findings for new debt.
- Distinctive: line 147
Run the metrics script to assess rule effectiveness:
- Distinctive: line 174
Check the health of project ground rules:
- Distinctive: line 229
Update @docs/progress.md with:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
weekly-maintenance
Execute comprehensive weekly maintenance routine (1-2 hours, Friday recommended):
1. Codebase Health Check
Run the project's quality/health tools (from CLAUDE.md Commands section):
# Use project-specific commands, e.g.:
# just health, npm run lint, cargo clippy, etc.Report on:
- Complexity trends (should be stable or decreasing)
- Duplication percentage (target: <5%)
- High-churn files that may need attention
- Dead code: unused exports, orphaned functions (run monthly or when codebase > 5K LOC)
2. Code Quality Agent Review
Use the code-quality skill to analyze the entire codebase:
- Flag any functions with CCN >10
- Identify duplication patterns
- Check for pattern consistency violations
3. Documentation Review
Check key documentation for accuracy:
- @CLAUDE.md accuracy (commands, paths, patterns still correct?)
- @docs/progress.md completeness
- Any drift between docs and implementation
- Documentation efficiency: Key context files (CLAUDE.md, progress.md, BACKLOG_INDEX.md) are loaded every session — keep them lean. Archive stale content, deduplicate, condense verbose sections.
- Metrics freshness: If
docs/progress.md→## Sprint Historyhas ≥2 data rows but## Metricstable still shows "—" values, sprint-end is not computing metrics — flag as a measurement gap. The feedback loop is broken: data collected but not surfaced.
4. Dependency Review
Check for outdated dependencies using the project's package manager:
# npm outdated, pip list --outdated, cargo outdated, etc.Dependency Health Check
Run dependency auditing tools:
# npm audit / pip-audit / cargo audit / bundler-auditFlag and report:
- Recently added packages (added since last maintenance) — verify they exist in the registry and are well-established
- Young packages (< 7 days old) — flag as supply chain risk
- Known vulnerabilities — categorize by severity
- Lockfile sync — verify lockfile matches dependency manifest
- Recently deprecated packages — check for deprecation notices
Dependency Report
### Dependency Health
- Total dependencies: [count]
- Outdated: [count]
- Vulnerabilities: [critical/high/medium/low counts]
- Recently added: [list with age and download counts]
- Lockfile in sync: [yes/no]4.3. Security Health Check
Perform a focused security health review:
Secrets Inventory Review
<IF condition="docs/reference/SECRETS_INVENTORY.md exists">
Read `docs/reference/SECRETS_INVENTORY.md` and check:
- **Overdue rotations:** Scan the `Next Due` column for dates in the past. Flag by severity: ≤7 days (warning), 8-30 days (high priority), >30 days (critical — rotate immediately).
- **Missing rotation methods:** Any secrets without a documented `Rotation Method` should be flagged.
- **Critical secrets without automation:** Secrets classified as `critical` that rely on `manual` rotation are high-risk.
</IF>
<ELSE>
If `docs/reference/SECRETS_INVENTORY.md` does not exist but the project uses environment variables or credentials, note this as a gap: "No secrets inventory — consider creating one from the template in the framework scaffold."
</ELSE>Dependency Security Audit
Run the project's dependency audit tool (same as section 4, but focused on security):
# npm audit --audit-level=high / pip-audit / cargo audit / govulncheck / bundler-auditReport Critical and High vulnerabilities. These should be addressed before the next sprint.
Quarterly Full-Repo Secret Scan
On the first weekly-maintenance of each quarter, run a full repository secret scan if Gitleaks or similar is available:
gitleaks detect --source . --no-git --report-format json 2>/dev/nullReport any findings. This catches secrets missed by the per-file post-edit hook.
4.5. Technical Debt Register Review
Read docs/technical-debt.md and perform the weekly debt review:
Triage active items
For each active item:
- Interest rate reassessment — check coupling to determine if interest is Growing or Stable. Run
grep -rnon the debt item's Location files to count how many other files import/reference them. High fan-in (imported by >5 files) + active debt = Growing interest. Isolated files with no dependents = Stable or Shrinking. - Severity check — has the item worsened? (e.g., new incidents, more files affected). Promote if so.
- Resolution progress — is there a linked story? If not and item is >30 days old, consider creating one.
- Accept or resolve — can any items move to "Accepted" (conscious trade-off) or "Resolved" (fixed)?
Detect new debt
Check this week's commits and code quality findings for new debt. Specifically scan for the 5 AI-specific debt types:
- Comprehension debt — grep git log for AI-assisted commits (
Co-Authored-By: Claudeor similar). For files with high AI-commit ratio that haven't been manually modified since, flag as potential comprehension debt. The risk: code ships faster than developers understand it. - Pattern violation debt — compare this week's changes against
docs/reference/CODING_STANDARDS.md(if exists). AI introduces inconsistent patterns at 3x the human rate for formatting, 2x for naming. - Duplication debt — check for near-duplicate code blocks introduced this week. AI regenerates rather than reusing existing functions.
- Phantom dependency debt — verify all imports added this week reference packages that exist in the project's dependency manifest (package.json, requirements.txt, go.mod, Cargo.toml, etc.).
- Verification debt — check if large AI-generated diffs have corresponding test coverage. Code reviewed without full understanding creates hidden risk.
Tag new items with origin: ai-generated when the source commit has AI co-author markers.
Housekeeping
- Review dates — update "Last reviewed" to today, "Next review" to +7 days
- Resolved cleanup — delete resolved items older than 90 days
- AI trends — at quarter boundaries, update the AI Debt Trends table with counts
- Active count — update header:
Active items: X | Resolved this quarter: Y - Sprint candidates — flag items with priority score ≥4.5 or interest "Growing" for next sprint planning.
/sprint-startreads these during its debt health check.
5. Rule Health Review
Run the metrics script to assess rule effectiveness:
bash scripts/pm/metrics.shReview the "Rule Triggers" section. Flag:
- Over-active rules (>20 triggers/week) — may be too broad or indicating a persistent issue
- Silent rules (0 triggers in 30+ days) — may be too narrow or addressing a solved problem
- High-failure skills (success rate <70%) — investigate common failure points
Record findings in the weekly summary below.
Also run the progress dashboard for trend signals and relative changes:
bash scripts/pm/metrics.sh --progressReview the output for:
- Any metrics with Δ3avg >50% (rapid change worth investigating)
- Leading vs Lagging divergences (early warning signals)
- Persistent 3-sprint trends that haven't been addressed
5.5. Ground Rules Health
<IF condition="docs/reference/GROUND_RULES.md exists and has GR-NNN rules">
Check the health of project ground rules:- Expired exceptions — scan the Exception Log table for rows where
Expiresdate has passed. Flag for resolution (remove exception or renew with justification). - Stale rules — if Change History shows no updates in 6+ months, the rules may need a freshness review.
- Compliance trends — read recent sprint specs (
docs/sprints/sprint-N.md) →## Outcome→ Ground rules field. Consistent violations of one rule may mean the rule is unrealistic, or enforcement is missing. - Enforcement gaps — for rules with
Enforced-by: auto:, verify the tool/test still exists and runs in CI. Unconfigured enforcement = paper rule.</IF>
5.7. Architecture Decision Health
<IF condition="docs/adr/ contains ADR files">
Review the health of architecture decision records:- Low-confidence ADRs — scan for
confidence: lowin frontmatter. For each, check whetherReconsider whenconditions have been met by the current codebase state. Flag any that need re-evaluation. - Stale ADRs — if no ADR has been created or reviewed in 90+ days on an actively developed project, the team may be making undocumented decisions. Flag as a process gap.
- Supersession chains — check for
superseded-bychains longer than 2 (A→B→C). These indicate a volatile decision area that may need a ground rule instead. - Ground rule candidates — if 2+ accepted ADRs address the same concern, suggest promoting to
docs/reference/GROUND_RULES.md. - ADR count health — projects with <5 ADRs and >10 major dependencies are likely under-documenting decisions.
</IF>
5.9. Weekly Activity Insights
Parse docs/sessions/.activity-log.jsonl for the past 7 days of activity:
ACTIVITY_LOG="docs/sessions/.activity-log.jsonl"
WEEK_AGO=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d "7 days ago" +%Y-%m-%d 2>/dev/null)
if [ -f "$ACTIVITY_LOG" ] && [ -s "$ACTIVITY_LOG" ]; then
# Filter to last 7 days and analyze
# Top 3 most-edited files this week
# Skill invocation counts
# Test failure patterns (same test failing repeatedly = flaky or fundamental)
# Edit-to-test ratio for the week
fiPresent as a concise summary (5-10 lines max):
### Weekly Activity Insights
- **Hot files:** `src/auth/login.ts` (23 edits), `src/api/users.ts` (15 edits), `tests/auth.test.ts` (12 edits)
- **Skills used:** /story-cycle (8x), /commit (6x), /debug-session (2x), /sprint-end (1x)
- **Test health:** 3 failures this week — `auth.test.ts:login_expired_token` failed 2x (possible flaky test)
- **Edit-to-test ratio:** 3.2 (good TDD discipline)
- **Sessions:** 4 sessions, avg 45 min eachFlag patterns worth investigating:
- Same test failing in multiple sessions → likely flaky or fundamental issue
- High edit-to-test ratio (>5.0) → TDD discipline slipping
- One file getting >30% of all edits → possible hotspot needing refactoring
- Skills with repeated failures → investigate common failure points
6. Weekly Summary
Update @docs/progress.md with:
## Week of [Date]
### Sprints Completed
- [Sprint X]: [Story ID] - [Title]
### Metrics Status
Reference `docs/progress.md` → `## Metrics` table for current sprint metrics.
Additional weekly indicators not tracked per-sprint:
- Complexity trend: [stable/increasing/decreasing]
- Duplication: X%
- Dependency health: [count] vulnerabilities, [count] outdated
### Technical Debt
- New items added: [count] (AI-origin: [count])
- Items resolved: [count]
- Active totals: [N] critical / [N] high / [N] medium / [N] low
- Growing-interest items needing attention: [list or "none"]
### Next Week Focus
- [Story IDs planned]7. Plan Next Week
Review @docs/reference/BACKLOG_INDEX.md and relevant epic files to identify:
- Next 3-5 stories to target
- Any blockers to address first
- Dependencies between stories
Output comprehensive weekly report with actionable items.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

