Scheduled automations¶
An automation is a stored recipe invocation with a cron schedule and a kickoff
file. mini-ork records it in the project database, fires it from a tick loop,
and launches each run exactly the way board start would.
mini-ork automations add \
--id nightly-audit \
--name "Nightly bug audit" \
--recipe bug-audit-cmgk \
--schedule "0 2 * * *" \
--kickoff-file ./kickoffs/nightly.md
The model¶
flowchart LR
C[cron expression] --> T[mini-ork automations tick]
T -->|due| L[launch run]
L --> W[worktree workspace]
W --> R[recipe executes]
R --> V[verdict + board card]Scheduling is pull-based: nothing needs to keep a daemon alive in the engine.
Your OS scheduler (launchd, cron, systemd, a container loop) calls
mini-ork automations tick; mini-ork decides what is due and starts those runs
detached. Missed ticks are caught up on the next tick that sees them.
Each fire launches a normal run. It gets a run id, a workspace, checkpoints, a verdict and a board entry, and it consumes your daily budget exactly like a manual run.
automations add¶
| Flag | Required | Meaning |
|---|---|---|
--id |
yes | Stable identifier; also used as the CTA/dedupe key |
--name |
yes | Human label shown on the board |
--recipe |
yes | Recipe directory name under recipes/ |
--schedule |
yes | Standard five-field cron expression |
--kickoff-file |
yes | Path to the kickoff markdown the run receives |
--in-place |
no | Run in the current checkout instead of a fresh worktree |
Without --in-place, every fire gets its own worktree. That is the safe default:
two overlapping fires cannot edit the same tree, and a bad fire cannot leave the
main checkout dirty.
Keep the kickoff next to the automation, not in examples/
The kickoff path is stored as given. A relative path resolves against the directory the tick runs in, so prefer an absolute path or launch the tick from the project root.
automations list¶
Shows each automation's id, name, recipe, schedule, next fire, last run and last status. This is the quickest way to answer "is the nightly thing still wired up?" without opening the database.
automations tick¶
Evaluates every automation once, launches those that are due, and returns.
| Exit code | Meaning |
|---|---|
0 |
Tick completed; whatever was due launched |
1 |
A launch failed |
2 |
Usage error (bad arguments) |
The tick is idempotent per scheduled window: a tick that sees an automation already fired for this window does not fire it again. Running the tick more often than the schedule requires is therefore safe and is the recommended pattern — the OS job becomes a heartbeat, not the source of truth.
Wiring it to the OS¶
The project ships scheduler install for exactly this:
mini-ork automations scheduler install
mini-ork automations scheduler status
mini-ork automations scheduler uninstall
install writes the host scheduler entry (launchd agent on macOS, cron/systemd
elsewhere) that calls tick on an interval; status reports whether it is
present and when it last ran; uninstall removes it. The entry is scoped to the
project, so two projects on one machine keep independent schedules.
If you manage the host scheduler yourself, the whole integration is one line:
When a fire fails¶
A fire is a run, so it fails the way runs fail: at a gate, on a lane, on the budget. The automation record holds the last run id, and the board shows the run like any other.
| Situation | What happens | What to do |
|---|---|---|
| Budget exhausted | Launch is refused with cost_limit; the automation stays scheduled |
Raise MO_DAILY_BUDGET_USD or lower the fire rate |
| Lane dead | Run aborts through the lane-health gate | mini-ork providers status |
| Recipe/plan error | Run fails early with a verdict | Fix the kickoff; the next fire uses the fixed file |
| Overlapping fires | Each fire has its own worktree, so no collision | Use board merge/discard per run |
A failing automation does not disable itself. That is intentional: an automation that silently stops is worse than one that fails loudly on the board every night.
Kickoff design for scheduled work¶
A manual kickoff can be conversational. A scheduled one cannot — nobody is there to answer. Write it to be self-contained:
- state the objective in one sentence and the acceptance check explicitly;
- name the files or directories in scope;
- say what not to touch;
- keep it small. A nightly job that plans ten nodes will drift, cost more, and fail more often than one that does two.
See Writing a kickoff.
Concurrency and workspaces¶
Automations default to worktrees for the same reason interactive runs do: the
run can be merged or discarded on evidence. If an automation is meant to keep a
branch current (a docs sync, say), --in-place is reasonable — but then two
fires must not overlap, so schedule it less often than a run takes.
Inspecting the schedule¶
The board document carries each automation with its schedule, next fire, last run and status — the same data the IDE's automations panel shows.