| name | work-loop |
| type | Skill |
| title | work-loop — operate the durable autonomous task fleet |
| description | Use whenever adding work to, coordinating, or working an Autonomous Work Loop campaign: atomic claims, full in-scope autonomy, routine-blocker repair, evidence-gated closure, and independent verification. |
| tags | ["automation","codex","queue","qa","agents"] |
| timestamp | 2026-08-30T00:00:00.000Z |
Work Loop
Canonical contract:
/Users/armanisadeghi/code/common-docs/systems/improvement/work-loop/STATE.md.
Coordinator
- Call
work_loop(action="status"); database state is truth.
- Reclaiming is automatic on claim. Fill every free slot, up to three workers,
by calling
claim with a unique stable holder and giving each worker the
returned contract unchanged.
When dispatching a known follow-up such as an independent verifier, pass its
exact canonical_key to claim and assert the returned key and role before
dispatch. A mismatch is a coordinator error: release it without work and do
not substitute another pending item.
- Wait for the first worker. Settle through
complete, retry, or defer,
then fill the slot again. Continue while claimable work exists.
- Add newly supplied tasks through
add_items; stable keys make re-adding safe.
When a new contract/rule version replaces an older claimable key, atomically
claim the exact older key and settle it with supersede, naming the existing
replacement key and reason. Never leave both versions claimable, reset the
old attempt count, or disguise supersession as human deferral.
- Never spend a work turn repeating inventory or producing a report while a
claimable item exists. Coordinator success is queue advancement.
Worker
Read the entire claimed contract. Claim ownership is permission to perform all
ordinary reversible work inside its scope: inspect, reproduce, edit, test,
commit, push, deploy where the repo contract allows, authenticate with the
preauthorized test identity, repair fixtures/tooling, and verify live.
Use the isolated in-app Browser for application testing. Never use the user's
browser. Close every tab you create.
On a shared Browser host, Browser ownership is valid only while the same holder
owns an in_progress Work Loop lease. Settling, releasing, losing, or
interrupting that claim releases the Browser lane immediately; a pending,
deferred, failed, or succeeded item can never reserve it. The coordinator must
reconcile durable claim state before every Browser handoff. Record tab ids/URLs
created under each lease. If a worker is interrupted or cannot clean up, the
coordinator closes those recorded campaign tabs before the next grant, without
touching tabs that predated the campaign.
The Browser and the machine-wide managed preview are one exclusive live lane.
The same active claim holder owns both or owns neither. A static/code worker may
prepare a clean worktree but cannot start or retain the managed preview. Before
each grant, stop/release the prior campaign preview, start only the repository's
canonical managed preview from the recorded checkout, and record its checkout
SHA/root beside the tab inventory. Parallel/raw dev servers are not evidence.
There are no routine blockers. Missing login state, stale tokens, broken
preview, missing fixtures, failing tests, server/tool failures, deployment lag,
unfamiliar code, and dirty unrelated files are problems to investigate and
repair or work around. A bug found during QA becomes part of the claimed work:
fix the root cause and retest it. Do not return a diagnosis or admin report as
completion.
Heartbeat before half the lease elapses and around any long test/build/deploy.
If the heartbeat says ownership was lost, stop writing and do not claim success.
Complete only with concrete evidence. The service will create the independent
verifier. A verifier starts from fresh state, assumes the work is wrong, and
returns passed or rejected; rejection automatically creates repair work.
The coordinator claims that verifier by its exact returned follow-up key; queue
priority alone is never identity.
defer is legal only for one named human-only boundary from the contract. It
parks that item; the coordinator immediately continues other work. Never turn a
single deferred item into a stopped campaign.
Adding items
One item is one independently claimable outcome. Include exact target,
objective, source refs, required tools, verification checks, evidence, priority,
and any true dependencies. Put general campaign rules in the campaign default;
put exceptions and special authority in that line item's engagement contract.
Use lower priority numbers for active regressions/retests, 100 for ordinary
backlog, and higher numbers for opportunistic work. Do not create one schedule
per item; one coordinator drains the shared campaign.
