Filesystem-First Pivot: Routines Become the Cron Entry Point

Routine scheduling exists because a markdown-first filesystem still needs a recurring entrypoint for work.

The answer is the routine. A routine is a durable markdown folder, its spec is frontmatter, its history is readable, and the workflow it runs is resolved from files at runtime. Cron exists, but it is not the source of truth. The routine spec is.

That is the important shift: recurring work becomes inspectable state instead of opaque scheduler configuration.

Routines are folders, not rows

A routine should be represented as a folder such as routines/<handle>/, with its spec living in spec.md and its operational record living in history.md.

That structure matters because it keeps the routine legible. A person can open the folder and see what it is for, when it runs, and what it has done. The routine is not a hidden database row behind a scheduler interface. It is durable filesystem state.

The workflow the routine runs is resolved from files at runtime, which means the routine does not own the workflow definition. It points to it. That keeps the architecture from collapsing into one giant opaque control plane.

Cron is generated, not authoritative

Cron sync should be deterministic and Matic-owned.

The cron block is an effect of the routine spec, not the system of record. If the spec changes, cron should be regenerated to match. If the scheduler disagrees, the spec wins. That is how Matic keeps the source of truth on disk while still producing the operational scheduling surface that external systems require.

This matters because cron is useful, but it is not durable enough to carry organizational meaning by itself. If the scheduler becomes the record, the filesystem-first model is already leaking.

skip-if-running prevents accidental duplication

The routine model also introduces the practical guardrail that keeps a routine from double-firing when it is already active.

skip-if-running matters because recurring work systems fail in boring ways before they fail in clever ones. If a routine can fire twice while it is already active, the org starts generating duplicate work, duplicate state transitions, and avoidable confusion.

The routine spec should be explicit enough that this behavior is obvious, testable, and inspectable. The guardrail belongs in files, not in scheduler folklore.

history.md is the operational memory

The readable history file is not optional decoration.

history.md gives the routine a durable operational record:

• when it fired
• what happened
• whether it skipped
• whether it missed
• whether the run completed cleanly

That history is what turns a schedule into a real organizational primitive. Without it, the system can trigger work but not explain itself later.

Multi-workflow binding is the useful unlock

One org can hold multiple workflow folders, and that is a feature, not a complication.

Multi-workflow binding lets the same org support different recurring processes without turning each one into a separate runtime universe. A routine can choose the right workflow folder at fire time while the underlying workflow remains a durable file-based object.

That sets up later work cleanly:

• Codex integration can consume the selected workflow
• channels can publish outputs from the routine
• runtime execution can stay separate from scheduler state

The routine boundary

This work does not make the scheduler the brain of the system.

It makes the routine the durable entrypoint for recurring work. The scheduler merely wakes it up. The routine spec decides what it means. The workflow folder provides the resolved path. The history file explains what happened.

That keeps Matic faithful to the filesystem-first contract: cron may trigger the work, but the files remain the record.