From 03601db69cf0f55060f6aaa1ab7ff5db84a626bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Tue, 25 Aug 2026 04:17:14 +0000 Subject: [PATCH] definitions instead of examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit every example is gone from the commander template. what replaces them is an exact definition of each of the four words, because an example is a thing to copy and a definition is a thing to reason from — and a commander copying an example produced a first turn that read like understanding and was recitation. trigger: the condition, on a schedule, answering one question and needing no judgement. action: the work done to ONE item, usually a task the platform already has. classification: which category a produced item belongs to — changes where it IS, never what it is. dispatch: doing something with a result beyond keeping it, off until armed, and the only one of the four that acts outside the commander's own directory. with the line that stops the confusion the first real conversation ran into: storing the result is NOT dispatch. every action keeps what it produced, here, by default. that is the action finishing, not a decision anybody has to make. Co-Authored-By: Claude Opus 5 Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043 --- src/servers/api/command-hq/directory.ts | 47 ++++++++++++++++--------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/src/servers/api/command-hq/directory.ts b/src/servers/api/command-hq/directory.ts index 4e99a216..0cb8ef56 100644 --- a/src/servers/api/command-hq/directory.ts +++ b/src/servers/api/command-hq/directory.ts @@ -110,8 +110,7 @@ export function notifySection(): string[] { ' -d \'{"code":"officer/core:commander","id":"1","title":"","body":""}\'', '```', '', - 'A commander named Ledgers sending "4 invoices filed" arrives as **Commander: Ledgers** / *4 invoices', - 'filed*.', + 'The platform renders that as **Commander: ** followed by your sentence.', '', 'Almost every notification in Officer carries only a code and a number, and the device renders the', 'words itself — so nothing readable leaves the machine. This one is the exception: `title` and `body`', @@ -179,26 +178,42 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string { 'Settled with the owner and true of every commander, not just this one. Read it before designing a', 'watcher; most of it was learned by getting it wrong.', '', - 'A commander is a trigger, then up to three steps: **act**, **classify**, **dispatch**. Only the trigger', - 'and the ledger are compulsory. The rest are chosen per commander, and most need fewer than all three.', + 'A commander is a TRIGGER, a LEDGER, and up to three steps between them: **act**, **classify**,', + '**dispatch**. Only the trigger and the ledger are compulsory. Each step is chosen per commander, and', + 'most need fewer than three — a commander with only an action is complete, not a lesser one. Never', + 'invent a step to fill the shape.', '', - 'The simplest useful one has no classification and no dispatch: fire when something new appears, run one', - 'task on it, keep the result here. At that point the commander is a schedule over a task the platform', - 'already has, which is the right answer rather than a lesser one. Do not invent steps to fill the shape.', + 'The four words have exact meanings here. Use them as defined, with the owner and with yourself:', + '', + '- **Trigger** — the condition that says something has happened, evaluated on a schedule. It answers', + ' one question, always the same one: what has appeared that I have not handled? It decides nothing', + ' else and it never needs judgement.', + '- **Action** — the work done to ONE item because the trigger fired. It produces something. It is', + ' usually a task the platform already has; sometimes a script you write. A commander may have exactly', + ' one, and it may have none, in which case the trigger is the whole job.', + '- **Classification** — deciding which category a produced item belongs to. It changes where the item', + ' IS, never what it is. Optional, and most commanders do not need it: it earns its place only when', + ' there are enough items that finding one matters.', + '- **Dispatch** — doing something with a result beyond keeping it. Telling the owner, handing it to', + ' another agent, sending it somewhere. Optional, off until the owner arms it, and the only one of the', + ' four that acts outside this directory.', + '', + 'Storing the result is NOT dispatch. Every action keeps what it produced, here, by default — that is', + 'the action finishing, not a decision anyone has to make.', '', '**One trigger.** A schedule that asks a single question: what has appeared that I have not handled?', 'The trigger runs constantly, so it must never need judgement. If deciding whether something happened', 'takes thought, the condition is too vague — it will either never fire or fire constantly, and you will', 'find out days later.', '', - '**One action, and it takes ONE item all the way through.** Not a stage at a time across everything.', - 'Transcribe this file, classify it, dispatch it, done — then the next file. The reason is not tidiness:', - 'a half-finished item is a STATE, and a state needs a second watcher to notice it and a second record to', - 'track it. Going end to end per item means that state never exists, so there is nothing to queue.', + '**One action, and it takes ONE item all the way through.** Not a stage at a time across everything: act', + 'on it, classify it, dispatch it, done — then the next item. The reason is not tidiness. A half-finished', + 'item is a STATE, and a state needs a second watcher to notice it and a second record to track it. Going', + 'end to end per item means that state never exists, so there is nothing to queue.', '', 'The cost is real and worth knowing. If the last step fails, the earlier ones are not recorded and get', - 'redone. That is fine for cheap work and not fine for forty minutes of audio — so when a step is', - 'expensive, record which step was reached and resume there.', + 'redone. Fine when the work is cheap; not fine when a single item costs minutes of compute — so when a', + 'step is expensive, record which step was reached and resume there.', '', '**One ledger, appended after the work.** One line per item, written when it is finished, never before.', 'A crash between doing the work and writing the line costs a repeat; the other order loses the item', @@ -247,9 +262,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string { ' unclassified/ handled and recorded, placement still open', '```', '', - 'When there IS classification, `classification/` is named for the SHAPE, not the payload. Transcripts,', - 'extracted invoices, photos — they are all just items being filed, and a commander that calls it', - '`transcripts/` has baked one job into its own directory layout.', + 'When there IS classification, `classification/` is named for the SHAPE, not the payload. Whatever this', + 'commander produces, it is items being filed — so naming the directory after one job bakes that job', + 'into the layout, and the layout has to outlive it.', '', "**A file's directory is its state.** In a category, it is filed. In `unclassified/`, it is finished", 'work waiting on a person — not a failure, and nothing should re-run the action on it. The ledger says',