the first turn asks one question, and gets its suggestion from the platform

three corrections, all the owner's, all from watching a real first turn.

it asked too much at once. the section listed five things to settle, so the
commander laid out the trigger, the action AND the destination in its
second message. every question must now be answerable with "yes" or "no, do
this instead" — if the reply needs a paragraph, the question was too big.
turns are cheap; a wrong guess armed for a week is not.

it must not raise the destination at all. output goes in the commander's
own directory, by default and without discussion. i had written "beside the
source is often exactly right", which was wrong and was the thing prompting
the question.

and the suggestion has to come from `GET /api/tasks` and the skills index —
what this platform actually has — not from an example in this file. which
it could not have, because the examples WERE the answer: the first-turn
section spelled out nine .m4a files named memo-<date>-<time>, and the shape
section named "fire on a new recording, transcribe it" as the simplest
commander. it read as a commander that understood the job. it was a
commander reading its own documentation back.

those examples are gone or varied. the template was written from one
commander last night and fitted it perfectly, which proves nothing. the
test is the second one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/api/command-hq/directory.ts

@@ -107,10 +107,11 @@ export function notifySection(): string[] {
     'curl -X POST "$OFFICER_API_URL/api/notify/_officer/notify" \\',
     '  -H "Authorization: Bearer $OFFICER_API_KEY" -H "Host: $OFFICER_API_HOST" \\',
     '  -H "content-type: application/json" \\',
-    '  -d \'{"code":"officer/core:commander","id":"1","title":"Voice Memos","body":"3 memos filed"}\'',
+    '  -d \'{"code":"officer/core:commander","id":"1","title":"<your name>","body":"<one sentence>"}\'',
     '```',
     '',
-    'That arrives as **Commander: Voice Memos** / *3 memos filed*.',
+    'A commander named Ledgers sending "4 invoices filed" arrives as **Commander: Ledgers** / *4 invoices',
+    'filed*.',
     '',
     '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`',
@@ -181,10 +182,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     '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.',
     '',
-    'The simplest useful one has no classification at all: fire on a new recording, transcribe it, write the',
+    'The simplest useful one has no classification and no dispatch: fire when something new appears, run one',
-    'text beside the original. Trigger, act, dispatch — and at that point the commander is a schedule over a',
+    'task on it, keep the result here. At that point the commander is a schedule over a task the platform',
-    'task that already exists, which is the right answer rather than a lesser one. Do not invent steps to',
+    'already has, which is the right answer rather than a lesser one. Do not invent steps to fill the shape.',
-    'fill the shape.',
     '',
     '**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',
@@ -204,9 +204,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'A crash between doing the work and writing the line costs a repeat; the other order loses the item',
     'silently. Append, never rewrite — two writers cannot corrupt an append.',
     '',
-    'Key it on a HASH of the source, not a name. Names change: a recording gets renamed from a phone, a',
+    'Key it on a HASH of the source, not a name. Names change — renamed on the device that made it, moved,',
-    'file is moved, and a name-keyed ledger quietly does all of it again. Do not key it on the OUTPUT',
+    'tidied — and a name-keyed ledger quietly does all of it again. Do not key it on the OUTPUT either:',
-    'either — outputs move, get filed, get renamed. The source is the only thing that holds still.',
+    'outputs move, get filed, get renamed. The source is the only thing that holds still.',
     '',
     'Two consequences to accept deliberately. The same content under two names is one item, done once. And',
     'deleting an output does not bring it back, because the ledger still says done.',
@@ -215,9 +215,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'those live here, in your own directory. The reference path holds its subject and nothing about how you',
     'are getting on with it.',
     '',
-    'Output is a different thing and goes wherever the job says. Beside the source, with the same name, is',
+    'Output goes in THIS directory, by default and without discussion — the layout below. Somewhere else is',
-    'often exactly right — a transcript next to its recording is the most useful place it could be. That is',
+    'a dispatch decision, made later and only if the owner asks for it. Do not raise it on the first turn',
-    'dispatch making a decision, not a rule being broken.',
+    'and do not put anything of yours in the reference path unless you have been told to.',
     '',
     '**A spawned agent follows a FILE, not a prompt.** Put the rules in `procedures/<something>.md` here and',
     'point the agent at it. When the rule changes you edit one document; a prompt baked into a loop is a',
@@ -263,31 +263,38 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     '## The first turn',
     '',
     "Two things were named before anything was said: this commander's name, and the reference path above.",
-    'That is all anybody has decided. Everything else is settled in conversation, on this turn.',
+    'Everything else is settled in conversation, and it is settled ONE QUESTION AT A TIME.',
     '',
-    '**Look before you ask.** Go and read the reference path first — how many items, what kinds, how they',
+    '**Assume the person answering is busy and knows less about this than you do.** Every question should',
-    'are named, how recently they arrive. A first question grounded in what is actually there is worth ten',
+    'be answerable with "yes" or "no, do this instead". If they have to read a paragraph to reply, or choose',
-    'generic ones: "there are nine `.m4a` files, newest twenty minutes ago, all named',
+    'between options you have laid out, the question was too big. Break it up and take more turns. Turns are',
-    '`memo-<date>-<time>` — are those what I am watching for?" tells the owner you understand the subject',
+    'cheap; a wrong guess armed for a week is not.',
-    'and gives them something concrete to correct.',
+    '',
+    '**Look, then look again, then ask.**',
+    '',
+    '1. Read the reference path. What is in there, what kinds of file, how they are named, how recently they',
+    '   arrive.',
+    '2. Ask the platform what it can already do — `GET /api/tasks` lists every task on this machine, and',
+    '   your skills index names the rest. If one of them plainly fits what you just saw, that is your',
+    '   suggestion. It has to come from what this platform actually has, not from a guess about what would',
+    '   be useful.',
+    '3. Then ask ONE question: when a new one of these appears, should I do <that thing>?',
+    '',
+    'That is the whole of the first turn. Nothing else.',
+    '',
+    '**Do not ask where the output goes.** It goes in this directory — see "Where things go" above, which',
+    'is the same for every commander. Putting it somewhere else is a later decision and usually never comes',
+    'up at all.',
+    '',
+    '**Do not ask about categories, dispatching, or how often to look.** Those are separate steps and most',
+    'commanders never need the first two. They come up later, one at a time, once the action is agreed and',
+    'has actually run.',
     '',
     'The name is a clue, not a specification. It says what the subject is. It never says what to do about',
     'it, and guessing that is how a commander ends up doing something nobody asked for.',
     '',
-    '**One question at a time.** This is a conversation, not a form. Ask, listen, and let the answer change',
+    '**Never arm a watcher on this turn.** Arming before the action is agreed is arming a guess, and a wrong',
-    'what you ask next.',
+    'condition either never fires or fires constantly — either way it is found out days later.',
-    '',
-    'What has to be settled before anything is armed:',
-    '',
-    '- **What counts as a new item.** Which extensions, top level or recursive, anything to ignore.',
-    '- **What happens to one.** The action — or that there is none, and the trigger is the whole job.',
-    '- **Where the result goes.** Beside the source, into `classification/`, somewhere else entirely.',
-    '- **Whether there is classification at all.** Most commanders do not need it. Do not invent it.',
-    '- **How often to look**, and say out loud that the number is provisional until it has run a while.',
-    '',
-    '**Never arm a watcher on this turn.** Arming before the above is agreed is arming a guess, and a wrong',
-    'condition either never fires or fires constantly — either way it is found out days later. Ask, agree,',
-    'then arm.',
     '',
     'When it is settled, REPLACE this section with what was agreed: what this commander watches for, what it',
     'does about it, and which numbers were guesses. The next turn should read the answer, not the questions.',