Org maintenance automation: weekly Claude Code routines (read-only reporting first)

[mmcky]

Summary

This proposes a weekly/monthly automation program for ongoing org maintenance (lecture repos + software projects), built on Claude Code routines for the cross-repo reporting layer and our existing GitHub Actions for everything mechanical. The guiding constraint: our maintainer group is small, so automations must reduce attention load, not add to it — phase 1 is strictly read-only reporting (no PRs, no merges) at a weekly cadence, and we graduate to higher frequency or bounded write actions only after we've learned how routines behave in practice.

This builds on an audit of our current automation (July 2026). Short version: we already run a lot — weekly cache/execution builds on every lecture repo, scheduled linkcheckers on five, daily/weekly cross-platform execution tests, weekly container builds + validation, daily env canaries, weekly+monthly activity reports (reports-activity), and S3 backups (workflow-backups). The gaps are not missing automation but missing visibility: scheduled builds fail silently (only lecture-dp files an issue on failure), config drifts unchecked, security alerts go unwatched since we held the Dependabot PRs to avoid noise, and nothing surfaces triage load (32 open PRs on lecture-python.myst, 149 open issues here).

What are Claude Code routines?

A routine is a saved prompt + a set of GitHub repos, run on a cron schedule as a fully autonomous Claude Code session on Anthropic-managed cloud VMs (research preview since April 2026; docs: https://code.claude.com/docs/en/routines). Relevant properties:

• One routine can sweep the whole org in a single run (multi-repo clone plus gh CLI queries), which is what makes the cross-repo digest pattern cheap — no workflow YAML rollout across 15 repos.
• It can comment on / open issues, and every run persists as a reviewable session transcript. PR-opening is restricted to claude/-prefixed branches by default, and we simply won't use it in phase 1.
• Cost is subscription usage plus $0.08 per runtime hour (preview pricing) — a 10-minute daily digest is roughly $0.01/day plus tokens.
• Caveats: runs under the creating user's GitHub identity, config lives in a personal claude.ai account (no Actions-tab audit trail), the status indicator only reflects infrastructure success (task failures are visible only in the transcript), and it's a research preview so limits/pricing may change. The governance section below addresses each of these.

The division of labor this implies: GitHub Actions keeps everything per-repo, mechanical, or compute-heavy (builds, publishes, linkcheck, containers, backups, translation sync — unchanged). Routines take everything cross-repo and judgment-shaped (triage, diagnosis, digests, audits).

Principles

1. Read-only first. Phase-1 routines produce text only: digests, diagnoses, rankings. No code pushes, no merges, ever, in any phase.
2. One rolling digest per routine, updated each run — not a new issue per run. Issue noise is noise too.
3. Quiet when green. Routines post substantive content only when something needs attention.
4. AI + human collaboration. Reports are structured to focus maintainer attention (classification, ranking, "whose move is it"), not to replace review.
5. Prompts live in a repo, reviewed and versioned, and are pasted into the routine verbatim — this restores the audit trail and makes routines recreatable.

Phase 1 — pilot routines (running under @mmcky for now)

#	Routine	Cadence	Each run
P1	Weekly PR triage digest	Mon 9am AEST	Reviews PRs opened/updated in the last 7 days across core repos: what changed, classification, style-guide compliance, CI state, suggested next action. Updates one rolling issue.
P2	Workflow health + diagnosis	Wed 9am AEST	Sweeps the past week's scheduled-workflow runs across all active repos; for each failure, reads the logs and posts a one-line diagnosis (e.g. "GPU spot reclamation — known, #330, re-run" vs "real execution error in lecture X"). Timed just after the Monday build wave (cache builds Mon 02:00–04:00 UTC, linkcheckers Sun/Mon 23:00 UTC) so results are fresh. Closes the silent-failure gap.
P3	Stale-PR path-to-merge	Mon 9am AEST	Ranks the open-PR backlog by closest-to-mergeable: what blocks each PR, conflict status, whose move it is.

All three are report-only and target the same problem: focusing limited maintainer attention. Weekly cadence is deliberate — enough to judge whether the reports are useful without adding daily noise to the maintainer workload. We run them for ~a month, review cost and signal quality, then decide what graduates (a high-signal digest could move to daily later; a low-signal one gets retired).

Phase 2 candidates (after we learn from the pilots)

More reports: weekly security digest (Dependabot/secret-scanning alert deltas, posted privately); monthly conformance audit (label/workflow/config drift — the qe CLI is the natural engine); monthly backlog gardening (close-candidates with reasoning, humans close); monthly deprecation horizon scan (upcoming breaking changes in the Python/JAX/mystmd stack mapped to exposed lectures); weekly rotating lecture content audit; cross-repo fix propagation checks (does this merged fix apply to translations / sibling series?).

First bounded write actions, in graduation order: applying labels to new issues (reversible, uses our standardized label set — #290/#324); then, much later and only for genuinely unsupervised-safe fixes, PRs on claude/ branches.

Non-goals

No stale-bots auto-closing PRs/issues; no dependency-bump PRs beyond the actions-ecosystem Dependabot we already accept; no auto-format PRs; no routine ever merges anything.

Governance

• Identity: pilots run under @mmcky; team-facing routines should move to the machine account proposed in Move automated commits/PRs to the quantecon-services machine account (dedicated PAT) #319 so notifications are filterable and automation doesn't depend on one person's account.
• Reliability: P2 timestamps its rolling issue every run; a trivial Actions cron verifies the timestamp is less than a week old — a dead-man's switch so a silently-stopped routine is noticed. The two systems watch each other.
• Cost: cents/month of runtime per routine; the real budget is subscription token usage — reviewed at the one-month mark.
• Preview risk: we revisit when routines exit research preview; prompts-in-repo makes any migration cheap.

Evidence the reporting layer is needed: defects found during the audit

One manual sweep of our workflows found all of the following, none of which anything would have caught systematically — this is exactly what the monthly conformance audit would surface:

• lecture-julia.myst cache.yml: the monthly schedule: cron is mis-indented inside push: and never fires
• QuantEcon.py ci_np2.yml: literal $default-branch placeholder, so the PR trigger never matches
• lecture-python-programming: inert _github_actions/ci.yml subdirectory (GitHub ignores subdirectories under workflows/)
• No linkcheck at all on lecture-jax, lecture-datascience.myst, lecture-julia.myst
• Dependabot alert scanning enabled on some repos, disabled on others (e.g. disabled on lecture-python.myst)

These will be fixed with small PRs on the affected repos, separate from this proposal.

Related

#319 (machine account) · #321 (env & config reporting / status-lectures) · #324 / #290 (standardized labels) · #330 (GPU spot reclamation) · QuantEcon/actions#91 (actions working plan — the P0 alerting gap this addresses) · #326 (reader feedback — future routine input)