Draft 0.1, October 31, 2026

The loop spec format

Each loop is one Markdown file. The YAML front matter holds what the scheduler needs. Nine sections below it hold the instructions the agent follows.

Draft. I use this format for my own loops. Field names may change before 1.0.

The file
Front matter fields
The nine sections
Rules for self-rewrites
Example: nightly fix loop

The file

Name the file after the loop, such as weekly-site-audit.loop.md. One loop per file. Keep the files in one folder. That folder is your bank.

---
front matter fields
---

## Objective
## Evals
## Sources and instructions
## Quality control
## Macros and recursion
## Learning
## Schedule
## Roadmap
## OKRs

Front matter fields

The first 4 fields are required. The rest are optional.

Field	Required	What it holds
`id`	Yes	Short, stable slug. Never changes, even when the name does.
`name`	Yes	Human name shown in the bank.
`status`	Yes	One of `draft`, `active`, `paused`, `retired`.
`schedule`	Yes	Cron line, or `manual`.
`timezone`	No	IANA zone for the schedule, such as `America/Los_Angeles`.
`owner`	No	Who approves changes the loop can't make alone.
`version`	No	Spec version. The loop bumps it each time it rewrites itself.
`max_items`	No	Most work items the loop may take per run.
`stop_when`	No	Conditions that end a run early.
`needs_owner`	No	Kinds of change that always wait for the owner.
`evals`	No	Paths or names of the eval sets this loop scores against.
`log`	No	Where the loop writes its run log and learning notes.

The nine sections

Objective

One or two lines on what a good run changes. If it needs a paragraph, split the loop.

Evals

How each run is scored, and on what scale. Use a number you can chart. Mark which checks are scripted and which a judge scores.

Sources and instructions

What the loop reads, such as files, sites or inboxes, and the steps it follows in order.

Quality control

Checks against outside standards. For example: "Find current guidance on landing page copy and check each change against it."

Macros and recursion

Named steps the loop repeats, and other loops it may call. Say how deep it may go.

Learning

Where the loop records what raised or lowered its score. The next run reads these notes before it starts.

Schedule

When it runs, in plain words. Add stop rules and what to do when a run fails.

Roadmap

What the loop works on next, in order. The loop may reorder the list. Only the owner adds large items.

OKRs

The objectives and key results the scores roll up to. Keep it to 1 to 3 key results.

Rules for self-rewrites

A loop may edit its own Sources, Macros, Learning and Roadmap sections after a scored run.
It may not edit its Objective, Evals, OKRs or needs_owner list. Those belong to the owner.
Every rewrite bumps version and adds a line to the learning log saying why.
If a rewrite lowers the score on the next run, the loop rolls back to the last version.

Example: nightly fix loop

This is a trimmed copy of a loop I run each night to fix small issues on my sites. Product names, repo names and private details are removed.

---
id: nightly-fix-loop
name: Nightly fix loop
status: active
schedule: "0 23 * * *"
timezone: America/Los_Angeles
owner: rex
version: 1
max_items: 3            # per product, per night
stop_when:
  - a live site is down before the run starts
  - two items fail on the same product
needs_owner:
  - copy, brand and visual design
  - pricing, payments and credits
  - logins and sessions
  - database schema, migrations, deleting content
  - API keys and secrets
  - major package upgrades
evals: [copy-eval, quality-eval]
log: runs/nightly-fix/
---

## Objective
Ship up to 3 small, low risk fixes per product each night.
Each fix must pass its check on the live site.

## Evals
- Build and tests pass in every PR, with the output pasted in.
- The fix passes its own acceptance check on the live URL.
- Screenshots at 1440 and 375 wide look right.
- Weekly: copy eval and quality eval, each scored 0 to 100.

## Sources and instructions
1. Read the product file for each product in the inventory.
2. Take the top backlog items that are low or medium risk and
   do not need the owner. At most 3 per product.
3. One item, one pull request. Small diffs. Never bundle.
4. Run the build and tests. No passing output, no merge.
5. Merge, deploy, then run the acceptance check live.
6. Tick the item done (PR number, date) or mark it blocked.

## Quality control
- Follow the design guardrails file for every visual change.
- Check copy changes against the copy eval rules, which come
  from published landing page guidance.

## Macros and recursion
- per_product: pick items -> open PR -> gate -> merge -> verify
- On failure: revert, log, mark blocked. Do not retry tonight.

## Learning
After each run, append to the log: what shipped, what failed,
and why. Items that fail twice go to the owner list.

## Schedule
Nightly at 11 PM Pacific. A morning report loop reads the log.

## Roadmap
- Add a minimal CI check to each repo (needs owner).
- Add tests where a repo has none.

## OKRs
O1: Every product page passes the copy and quality evals.
  KR1: Every page scores 85 or more on the copy eval.
  KR2: Every page scores 85 or more on the quality eval.
  KR3: No failed fix stays live past the morning report.

To try it, copy the skeleton into a file and fill it in for one job you already run. Run it by hand once before you put it on a schedule.

See the bank view