Recurring runs

Synced from outfitter/docs/documentation/recurring-runs.md. The repository is the source of truth.

Recurring agent work — “check this every N minutes”, “review what landed overnight”, “regenerate the weekly report” — runs three ways in the Outfitter ecosystem. All three run the same composition — the agent, its skills, its catalog pins — under the same contract: wake, survey your inputs, work, stop. What differs is the clock and the lifecycle: a loop extension re-invokes a live session on a tick (locally, and inside resident in-cluster agents), while the cron surfaces launch a fresh one-shot process per tick.

Mechanism	Clock	Shape	Use when
Local loop extension	Your own session	The agent ticks inside a session on your machine (/loop 10m), surveying its inputs each tick	Watching something during your workday; developing a recurring behavior before automating it
GitHub Actions cron	The CI scheduler	on: schedule: workflow runs a fresh headless one-shot per tick	Repo-scoped recurrences: nightly commit review, weekly KPI reports, scheduled audits
In-cluster (Link Operator)	Kubernetes	A scheduled recurring CronJob, or a resident Deployment that bootstraps the same /loop extension in-cluster	Always-on agents with channels (email, GitHub, chat) and cluster-local access; recurrences that shouldn’t depend on a repo’s CI

The graduation path mirrors the ladder: prototype the behavior with the local loop extension, move it to an Actions cron when it should run without your laptop, move it in-cluster when it needs to be resident or cluster-local.

Local: the loop extension

The loop extension re-invokes the agent at an interval inside a session. It is not bundled with a default install — select a loop extension in the agent’s loadout (extensions:) and pin it like any other extension. Each tick, a well-shaped looping agent surveys its available inputs, turns new items into tasks, and works or delegates them — rather than carrying a growing transcript of stale context. The in-cluster resident agent runs the same way (see below).

CI: scheduled one-shots

An Actions cron externalizes the clock to GitHub’s scheduler. Each tick is a fresh, stateless headless run — compose, work once, exit — which makes it deterministic and reviewable, with a session transcript uploadable as a workflow artifact. See ai-outfitter/actions — its examples/scheduled-commit-review.yml reviews the last 24 hours of commits each weekday morning and files an issue on findings.

Cluster: CronJobs and residents

Kubernetes contributes both a scheduled recurrence (a CronJob) and a resident one (a Deployment whose /loop tick surveys its channels for new work). The in-cluster execution shapes table is the reference for how the Link Operator provisions each.

Not a loop: event-driven runs

A webhook- or event-triggered run — one investigation Job per firing alert, one post-mortem per failed workflow — is triggered by the world, not a clock. It complements loops rather than replacing them: use a loop when work accumulates and should be swept up on a tick; use an event trigger when each unit of work announces itself. See Grafana alert investigations and Flaky-test post-mortems.