What a line is

A rogerwilco message is one line of text. It starts with the version, then a two-letter word for what kind of message it is, then an id, and then a list of labelled facts. Anything that is not a fact goes after two slashes at the end, as a short note. A program can read every part of it without guessing.

RW1 <TYPE> <id> from=<who> to=<who> item=<what> label=value label=value ... // a short note

RW1 is the version. If it ever changes, old programs know to stop.
TYPE is one of nine two-letter words, listed below.
id is the sender's name and a number: payer-1, payer-2. Every reply names the id it answers with re=, so a thread can be rebuilt from the ids alone.
label=value pairs are the facts. No spaces inside a value. Lists join with +. Dates are YYYYMMDD. Money is digits with two decimals.
// note is free text, at most 300 characters. It is for people and for reasons, never for facts. If a fact has a label, it goes in the label.

The nine kinds of message

Seven of the eight use the payments example from the front page: a scheduler hands a payment to a payer. The status line is from earlier in the same month-end: the agent reading the emails records an invoice.

HO: hand over

"Here is a job. Do this." It names the item, what to do (ask=) and every fact the receiver needs. rb=exec means "read back what you will do, with the values you will use, before you start".

RW1 HO scheduler-1 p=pay from=scheduler to=payer item=inv:MD-2026-057 ask=PAY rb=exec sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929

RB: read back

"Here is what I understood, and what I will do." The receiver gives the values it will act with, the account read from its own master, and adds h=, a fingerprint of the hand-over as it arrived. The sender's program compares the two before letting go of the job. Where the act tool can prepare before it commits, the tool composes this line itself, with the values it has frozen and a token the sender names in its confirmation; the receiver passes it on, or the sender reads it from the tool.

RW1 RB payer-1 re=scheduler-1 from=payer to=scheduler item=inv:MD-2026-057 ask=PAY p=pay h=a7a82de76607 sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929

AQ: ask

"I need to know one thing before I go on." The question comes with the answers allowed, so the reply is one word a program can act on, not a paragraph.

RW1 AQ payer-3 re=scheduler-1 p=pay from=payer to=scheduler item=inv:MD-2026-057 need=ENUM opts=APPROVE+HOLD // the account in the instruction is not the one on file; approve it or hold the payment?

AN: answer

"Here is the answer." One of the allowed words.

RW1 AN scheduler-2 re=payer-3 p=pay from=scheduler to=payer val=HOLD

ST: status

"Here is a fact." No handover, nothing to do; a line of record. When the fact came from a document, src= says where, so a program can check the pointer, and for a clinical note that the quoted words are on the line it names.

RW1 ST extractor-1 p=pay from=extractor to=reconciler item=inv:INV-000491 sup=northfield net=315.50 vat=63.10 amt=378.60 cur=GBP kind=GROSS src=email:8

DN: done

"I did it, and here is exactly what I did." The values as they were actually used, not as they were asked for, so the sender's program can check them against the instruction. This is the second loop. The sixth study found it the one check that catches a tool doing something other than what it was told; the spec has it as check-dn.

RW1 DN payer-2 re=scheduler-1 p=pay from=payer to=scheduler item=inv:MD-2026-057 out=OK sup=marlow amt=5400.00 cur=GBP kind=GROSS acct=40-12-88/61102938 paid=20261002 ref=MD-2026-057 apref=FD-0929

UN: unable

"I will not take this, and here is why." The reason is a word from a list, so a program can route it: not for me, not allowed, no capability, missing context, and so on.

RW1 UN payer-1 re=scheduler-1 p=pay from=payer to=scheduler item=inv:MD-2026-057 why=SCOPE // this message is addressed to auditor, not to me

FL: failed

"I took it and it broke." With a reason, and whether it is worth trying again.

RW1 FL payer-4 re=scheduler-1 p=pay from=payer to=scheduler item=inv:MD-2026-057 why=ERR retry=Y // the bank API timed out; nothing was sent

CX: cancel

"Stop. Don't do that job." The sender withdraws a handoff it sent, with a reason: the approval was withdrawn, a newer job replaces it, or its time ran out. The receiver abandons anything it prepared and answers AN val=Y; if the act already ran, it sends the done report instead, and the sender decides whether to reverse it with a new job, ask=UNDO.

RW1 CX scheduler-2 re=scheduler-1 p=pay from=scheduler to=payer item=inv:MD-2026-057 why=REVOKED // approval FD-0929 withdrawn

Every handoff ends exactly once: done, unable, failed or cancelled. A job can also carry exp=, the latest moment it may be acted on, written 20261002T1700Z; a tool's prepared statement carries its own, and the tool refuses to commit after it. check-thread finds any handoff left open past its time.

What the program checks

Every line, every time:

Every label the message type needs is there. A hand-over without its item or its ask, or a reply without re=, is refused.
Where a label has a list of allowed words, the word must come from it. ask=SEND-MONEY is refused; ask=PAY is on the list. An agent cannot invent a word there and have it quietly accepted. Labels that name things in the world, like a supplier or an account, take any value.
Numbers, dates, money and lists are in the one shape allowed, so 5400.00 and 5,400 cannot both be in play.
The id matches the sender. A readback as payer-1 to a message addressed to auditor is refused: wrong aircraft on the frequency.

And for a readback, five more, in order. Receipt: the reply answers the right message from the right agent. Integrity: the fingerprint matches, so nothing changed on the way. Echo: the facts come back with the same values (the item, the ask and the due date always; every fact when the hand-over said rb=all). Comprehension, when the sender asked for it: the criteria the receiver worked out from the brief, written as acc=, match the ones the sender kept to itself. Execution, before an irreversible act (rb=exec): the values the receiver will act with, including the ones it looked up for itself, are all there and match the instruction. The first two are roger. The last three are wilco. And after the act, one more: the done message carries the values as executed, and they match the plan.

Where the words come from

There is one basic list for any kind of work (the nine message types, the ask words like DRAFT, REVIEW and FIX, the reasons for UN and FL). Then a profile adds the words for one kind of work. The pay profile adds PAY, CHGBANK and SEND, amounts, currencies, accounts and the five answers a finance director may give (approve, decline, hold, reject, call back). The clin profile adds the words for a clinical note. A message using a profile says so with p=pay. A profile can add words; it may not change what a basic one means.

Seven habits that do most of the work

The lines make these checkable, but the habits are worth having even in plain English. In the month-end study, prose written this way cut the chatter between agents to a third and what the human had to read to 40%, before any line was used.

Say each fact once, in a fixed shape.
Point at files instead of restating them; turn a document into lines of fact once, at the edge, each with a pointer back to where it came from.
Say only what changed since last time.
Say what you received before you start.
When a person has to decide, ask a question with a short list of answers.
Ask, answer, finish.
No preamble, no recap.

The spec and the skill

You do not need either to start. The spec is the rulebook: every message type, every label, every list of words, and exactly how the checks work. It is for someone writing their own implementation, in any language. The skill is the file you give to an AI agent, such as Claude Code, so it writes and reads these lines on its own. It is the spec rewritten as instructions to an agent, with the habits above at the top. The legend is the shortest version of all: the whole format in a page, to paste into any agent's prompt.

Start in two minutes.