Automation Schema

Automations are recurring agent tasks with a markdown contract, optional cloud adaptation, output directory, wiki targets, and freshness state.

Automations are how the no-one-off rule becomes real. If Kevin will ask for the same class of work repeatedly, it should become a skill or automation rather than a memory of a past request. Source: AGENTS.md Automations; No One-Off Work

Files

Frontmatter Contract

title: Human-readable name
slug: kebab-case
schedule: hourly | every-4-hours | daily | weekly | monthly | on-demand
agents: [codex, cursor, claude-code]
wiki_targets: ["wiki/page.md"]
sources: ["urls", "directories"]
output_format: markdown | json | diff
tags: [lowercase, hyphenated]

Execution Modes

Durable Run Contract

A scheduled thread is not a completed automation until it does all of the following:

1. Reads AGENTS.md, wiki/HEARTBEAT.md, automations/<slug>.md, and directly referenced task files.
2. Writes outputs/<date>/<slug>/<agent>.md.
3. Applies wiki_targets only when the automation's promotion criteria pass.
4. Writes "No durable wiki update needed" in the output when nothing should be promoted.
5. Updates state.json under automations.<slug> when the scheduled check completes.
6. Appends wiki/log.md with the summary, changed files, and durable/no-op status.
7. Runs npx tsx scripts/build-index.ts and qmd update && qmd embed when wiki pages changed.
8. Follows Generated Surface Contract when the run changes generated packs, skill registry output, redirects, qmd retrieval, or stateful ledgers.

Codex scheduler prompts should be thin wrappers around the canonical automation file. They should not duplicate the full scan logic because those copies drift.

Automation Quality Bar

An automation should be:

• idempotent where practical
• explicit about sources and credentials
• clear about which wiki pages it may mutate
• able to write output before editing durable pages
• logged in wiki/log.md
• reflected in state.json through script or manual update
• listed in AGENTS.md and freshness checks if recurring
• audited against the live scheduler when it is supposed to run in Codex

When To Create One

Create or propose an automation when:

• Kevin asks for the same task twice
• the task depends on a schedule
• the task monitors external changes
• outputs should be compared across agents
• maintenance would otherwise rely on memory

Use a skill instead when the workflow is event-driven and needs human-triggered execution.

---

Timeline

• 2026-07-01 | Added generated-surface closeout to the durable run contract for automations that mutate packs, registry output, redirects, qmd, or ledgers. Source: User request, 2026-07-01
• 2026-07-01 | Aligned schema docs with the refreshed heartbeat proof contract and added the every-four-hours schedule value used by Slack, Gmail, and source compile. Source: User request, 2026-07-01; Automation Proof Contract
• 2026-06-28 | Added the durable run contract for Codex/Cursor/manual schedules, including output artifacts, wiki-target promotion, state updates, and log writes. Source: User request, 2026-06-28; Scheduling Operating Model
• 2026-06-18 | Expanded automation schema with file roles, execution modes, quality bar, and skill-vs-automation decision rule. Source: User request, 2026-06-18; automations/_schema.md
• 2026-05-31 | Meta page formalized from automations/_schema.md. Source: automations/_schema.md