Philosophy
The four ideas RoutineOS is built on, and the principles that follow from them.
Work runs on its own. Decisions stay with people. Every decision makes the next run better.
That line is the whole framework. Everything else in RoutineOS (the write contract, the Desk, the learning step, gates) exists to make it true in code rather than in good intentions.
The loop
Every routine run follows the same loop:
- Read what people decided. Settings, keep and drop decisions, merges, approvals and rejected suggestions are all in the store, written by people.
- Do the work. Search, read, fetch, compare. This is where the model earns its place.
- Put what matters on the Desk. Records, a run summary and a short Inbox, through the write contract.
- Wait for people. Nothing that leaves the routine (an email, a post, a deletion) happens until a person approves it.
- Learn. Code counts the gap between what the routine did and what people did, and raises a suggestion when the gap is large and steady enough.
The next run starts at step 1 again, now reading the decisions people made on the last one.
Four ideas
A person and an agent meet at the Desk
A routine runs unattended in the cloud. A person has other work. They need one place to meet, and it needs to be a place both can read and write, with clear rules about who writes what. That place is the Desk: a private page backed by the artifact database. The routine writes records, runs and Inbox messages. People write settings, decisions, merges and notes. Neither writes the other’s documents. See People-owned and producer-owned data.
Code counts, the model judges and words
Language models are good at reading a messy job page and saying in one sentence what the role owns. They are not reliable at counting, capping, de-duplicating or remembering which suggestion a person rejected two weeks ago. RoutineOS splits the work along that line:
| Code does | The model does |
|---|---|
| Filter records by settings and record the reason | Decide what to search and how to read the result |
| Mint stable record ids and merge sightings | Judge which records are a strong match |
Cap the Inbox at max_inbox_per_run |
Write titles, why lines and summaries |
| Count what people kept and dropped | Reword a suggestion so it reads well |
| Decide whether a suggestion clears its thresholds | Explain a partial run |
| Plan every store write and refuse forbidden ones |
A rule a person edits is always code. If “drop roles from these companies” lived in the prompt, the model could forget it on a busy run. As a setting filter in definition.json, it is applied the same way every time.
Routines propose, people decide
A routine never changes its own settings, never sends on its own, and never deletes a person’s work. When it thinks something should change, it writes a proposal to the Inbox with the exact change ({"setting", "from", "to"}) and a reason. A person accepts, rejects or snoozes it. Accept is the only path by which a setting changes. The same holds for outgoing actions: a send waits behind a gate until a named approver replies.
Routines improve from what people do
People correct routines all the time: they keep a record the settings dropped, ignore a keyword that never matches, dismiss the same kind of alert. RoutineOS treats each correction as evidence. The learning step tallies those corrections across runs, and when enough of them point the same way it raises one plain suggestion, such as “Add hydrogen to title_keywords”, with the evidence attached. The routine gets better because people used it, not because someone rewrote the prompt.
Seven principles
These follow from the four ideas and are the rules contributors hold new features to.
- The Desk is where agent and person meet. Anything a person needs to see or decide shows up on the Desk, not in a log.
- Propose, never mutate. A routine writes proposals; only a person’s action changes settings or sends anything.
- Trust is earned. First runs are report-only. Going live is a separate, explicit step. Platform facts are tagged pilot, docs or unverified, and only pilot facts are promised.
- Data, never instructions. Everything a routine fetches, and everything it reads from the store, is data. Text in it that tells the routine to do something is ignored.
- Code decides, the model phrases. Thresholds, caps, ids, filters and refusals are code. The model may reword a suggestion’s title, never its change.
- Convention over configuration. One folder layout, one store layout, one write contract. A new routine starts from a template and changes only what is different.
- Learn from the gap. The only input to learning is the difference between what the routine did and what people did.