/automation

Own what spans the boundary you cannot deploy to

Build processes that span systems, schedules, events and human approvals — and make them survive the fact that you cannot deploy a fix into someone else's system, and you cannot un-send. backend owns async work inside a system you control: your queue, your workers, your database, deployable and testable end to end. automation owns the case where most of the steps belong to vendors you cannot deploy to, cannot unit-test, and cannot roll back — where the API changes with no deploy on your side, the quota belongs to someone else, and a person clicking "approve" is a node in the graph. It writes workflow definitions, integration code, connector configuration and functions — it does not author the business rule; when no upstream rule exists, it captures it explicitly rather than inventing one silently.

The default reader is one person, or a small team, with no second pair of eyes. That matters more than it looks: nearly every control this domain teaches assumes a counterparty. Approval assumes an approver who is not the requester. Reconciliation assumes a reconciler who is not the recorder. The functions survive at n=1; the second body does not — the substitute is an independent source, a clock, or a rule committed to in advance (I6).

The faceted router

SKILL.md is a router, not a script. Every request selects the smallest sufficient route: one primary job — the twelve below — combined with at most one base surface that reshapes how the job applies to what's actually running, plus the additive agentic overlay when a model decides which tool to call, in what order, or is the trigger itself. Read the selected references completely; load one or two at most, never the whole pack.

The twelve primary jobs

Each job is one reference, read fully only when its route is selected. Reconciliation is the flagship because every other job either assumes this loop exists somewhere, or has to say plainly that it does not — this is the whole surface, not a headline slice.

Full router table & invariants: SKILL.md.

Four surfaces + one additive overlay

One base surface, at most, reshapes every job for where the workflow actually runs — the same reconciliation job is bounded differently on a hosted builder than on code-first durable execution. The agentic overlay is additive — it stacks on top of whichever base you picked, never replaces it — and carries a distinct violet identity throughout this page, the same convention operate, quality, and data use for their own additive overlay.

Reconciliation — the flagship

Ask an agent to wire Stripe to your CRM and it writes the webhook handler, watches it return 200, and calls the integration done. Nobody checked whether the vendor's side still holds what you think it holds, what a refund actually undoes, or what happens when the approval gate times out at 3am with nobody watching. Closing that gap — proving what actually happened, not what a 200 response or your own "handled" flag claims happened — is reconciliation, and everything else in this pack assumes a reconciliation loop exists somewhere, or states plainly that it does not. I1 is the spine: reconcile against the vendor's authoritative state, never against your own record of what you told it. A 200 response, a queued job, a webhook subscription you believe is active — none of these are evidence the vendor's side actually holds what you think it holds. A webhook that never arrives leaves no trace in your logs at all — nothing failed loudly, so there is nothing to notice.

Cadence is tiered, not uniform — this is three jobs at different altitudes, not one:

The n=1 minimum viable loop: one cron job, calling the provider's "list since timestamp" endpoint, diffing the returned ID set against local IDs — and alerting, never auto-healing, on any gap that survives a grace window. Adding this loop is not a free safety net: it is a second delivery path for the same business event, so the idempotency key must be derived from the event's own identity, not from whichever path delivered it (I4) — trigger-design's job, named here as the obligation the moment reconciliation exists.

What makes this different

Two things set automation apart from a technique library: it names its own wedge as synthesis, not discovery, and it grounds its agentic-overlay claim in filed bug reports and merged fixes, not vendor marketing.

The universal invariants

References cite these by number; the numbering is canonical. These rules govern every route, whichever files it loads.

• I1 — Reconcile against the vendor's stateNever your own record of what you told it. An ack is not evidence; a missed webhook leaves no trace.
• I2 — Your own record isn't proof it happenedLog the raw event and your interpretation as two separate facts, so a completion check can be falsified, not just confirmed.
• I3 — Compensation is forward, not a rollbackA refund is not an un-charge. Where none exists, perform the hardest-to-revert action last.
• I4 — Derive the idempotency key from the eventNot the trigger mechanism. The same event by webhook and by reconciliation poll must collapse to one.
• I5 — Assume your cursor can't see deletesUnless the vendor names a mechanism — then check its retention window.
• I6 — At n=1, independence comes from the sourceThe source, the clock, or a pre-committed rule — never a second person who doesn't exist.
• I7 — Credential health is its own monitored resourceChecked on its own schedule, independent of whether any workflow happened to run.
• I8 — A stopped workflow is not a failed oneNo engine alerts by default; the missing-heartbeat signal is yours to build.
• I9 — Know if your engine resumes or restartsRestart-only plus an irreversible early step is a duplicate generator on every retry.
• I10 — The quota is the vendor'sExhausting it is an availability event you can't fix by paying faster; the blast radius is every flow on the account.
• I11 — Retrying into a 429 makes it worseConverts a transient failure into a sustained ban. Backoff with jitter, honour Retry-After.
• I12 — An agentic step fails by continuingIt fails loudly only where someone bolted a deterministic ceiling onto it.
• I13 — Timeout policy is a decision, not a defaultNo engine ships one. Name deny / allow / escalate before the gate goes live.
• I14 — Prefer the APIWhere there is none, you've bought a maintenance liability with no deprecation notice.
• I15 — Date-stamp every volatile vendor factLimits, retry schedules, retention windows, prices, and licences churn — and name the interest of anyone selling what they measure, including when it makes their own claim stronger.

What a pass produces

automation's core workflow runs against whatever upstream artifacts exist — a business rule from product, a contract from backend, an NFR budget from architecture — and says so explicitly when none were supplied, rather than inventing one.

The handoff seams

automation consumes upstream artifacts without silently overriding them — the business rule from product, a contract from backend, an NFR budget from architecture — and says so explicitly when none exist, rather than inventing a rule or a target to fill the gap. It is rarely terminal: it emits a compact handoff.yaml beside the workflow artifacts whenever downstream work is expected.

objective: <one sentence>
surface: base + agentic?
irreversible_steps: [step, order,
  compensation, resume_or_restart]
reconciliation_loop: exists,
  compares, cadence, on_discrepancy
credentials: [vendor, expires,
  refresh_mechanism]
human_gates: [approvers, timeout,
  on_timeout]

A standalone request with no downstream consumer needs no handoff.yaml at all. Only objective is required — every other field may be empty, and a consumer must tolerate it absent, never treat absence as a schema violation. reconciliation_loop.exists: no is a valid, required answer when there is no loop; leaving the block blank is not the same statement. Never silently invoke a sibling skill — name it in recommended_next.

Start here

Install once. It's a plain SKILL.md router — no flags, no config, no scripts — so it activates on natural-language phrasing ("was the webhook ever sent," "set up nightly reconciliation before we close the books," "the refund double-charged someone, what's the compensating action") rather than a fixed command.

The same install runs on any Agent Skills host. Codex installs to ${CODEX_HOME:-$HOME/.codex}/skills and triggers with $automation; agents remains a separate cross-agent installation target.