The platform changed underneath this. A commander is no longer recognised by
sharing one folder with every other — it has its own directory, created before
its first turn, holding a CLAUDE.md written at creation and a state/ for what it
has done. isCommandersDir is gone.
Three things in here were wrong in ways that change what a commander does on
turn one, which is the turn that matters.
Orientation said to read where you are. Under the new shape that is your own
directory, which holds your CLAUDE.md and an empty state/ — nothing to learn, and
listing it teaches you nothing. The thing you were pointed at is the REFERENCE
PATH, named in your CLAUDE.md, and it is deliberately not where you live.
The first-turn interlock is gone and the skill claimed it as a mechanism. The
paths a commander records itself at could not be resolved on turn one, so their
absence WAS the signal; they are written before the first turn now. The rule is
the whole guard rather than a backstop to it, and saying so is better than
letting somebody discover the interlock no longer bites.
And the button gives a name and a reference path, not a working directory.
Adds what the old text had no way to say: everything a commander knows is on
disk, so a session that dies can be replaced in the same directory and it carries
on. And that its CLAUDE.md is its own file to extend — read at the start of every
session, so what it writes there is what the next conversation knows.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
Follows the permission registry, which lost an entry when Minesweeper became a
plugin. Regenerated by `bun run skills:platform`; docs:check compares the two
and was red until this landed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
A loop writes to its job panel and nobody reads a job panel, so a watcher that
fires overnight has done the work and told no one — which from the owner's side
looks the same as not firing.
Two messages, no more: what appeared and that it is being handled, then a short
report when the work ends. A progress commentary in chat is a notification per
step, which is how somebody turns notifications off.
The mechanism needs nothing new and no authentication. The child writes its report
to a file on the same machine as the same user; the loop inserts a nudge row for
its own transcript id over the local Postgres socket; the nudger wakes the
conversation within the minute and the commander reads the file and writes the
report itself. Facts in a file, judgement in the chat — which is what buys a
summary instead of a pasted log tail.
Notes the three things that bite: one nudge row per session so overwrite rather
than queue, the nudge message is a prompt to yourself and not what the owner
reads, and up to a minute late because the nudger polls on a minute.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ANTHROPIC_BASE_URL points at a local proxy that holds the real credential, so
ANTHROPIC_API_KEY is a token for that proxy — and the CLI sees a key set, assumes
the worst, and warns on every spawn. Nothing is wrong and nothing uses connectors.
But a loop that narrates stderr whenever it is non-empty then narrates this every
single time, which teaches whoever reads the job panel to skim the one channel
that carries real failures. So: filter that known line and report what is left.
Never suppress stderr wholesale — the reason to keep it is the failure nobody has
seen yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A fixed "two sentences and one question" only worked because the directory it was
tested in already documented the job. Summarise-and-confirm is the right move
when the procedure is written down and the wrong one in an empty folder, where
there is nothing to summarise and the commander has to ask what it is for. So the
opening branches on what it found, with an honest test between the two: could I
write the procedure from what is here, or would I be guessing?
Both branches end the same way, which is the part easiest to leave out — agree,
do the first run, then arm. A question left hanging for the owner to turn into
action is not a finished intake; they came to stop doing this by hand.
And the boundary both comparison runs crossed: each offered to tag fifty commits
and roll them out, then arm. Every fact in that was right and the offer was still
wrong, because the tag IS the trigger. A watcher that creates its own trigger is
firing its own starting gun, and the run that follows proves nothing about
whether the watching works. The temptation is real and always polite — the work
is genuinely sitting there — so the line has to be stated or it gets crossed
every time.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The third intake offered "Ship the 28 commits now (Recommended)" and it was
exactly what the owner wanted — and it was a task, not an arrangement. Pick it,
the work happens well, and nothing is armed at the end. The option said nothing
about that, so the way you find out is a tag going unnoticed the next day.
A commander exists to end up watching something, so a one-off is never an option
by itself: it is the first half of one, and the second half is what it leaves
running. "Ship these now, then arm the watcher" against "just arm it, they go
with the next tag" offers the same work and makes the difference visible.
Wanting only the one-off is still a fine answer. It just has to be chosen
knowingly — "then I am not a commander, just an agent that did a job" — rather
than by accident.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Third intake was on-subject and still opened with a five-bullet audit — tags,
hashes, file paths, whether db:push is a step — under a heading that said "all
verified just now", which the previous rule had banned in those words.
The rule was inviting it. It said "open with what you found", so it opened with
everything it found. It now says one sentence, and the sentence is the single
fact that makes the question worth asking rather than a summary of the work.
The real message is quoted in full as the example of what is too long, with the
two-line version beside it. An abstract rule about brevity loses to the pull of
having just done a lot of work; a before-and-after in the agent's own voice does
not.
And the placement rule that was missing: when offering choices, the OPTIONS carry
the specifics and the question carries none. The options in that message were the
good part — it was the preamble that needed deleting.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Started in the platform checkout and named "Platform Deploys", the second intake
read TODO.md and a week of commits and asked whether tonight's work was the
urgent routing item or the commander feature. A fair question from a colleague
catching up, and nothing to do with what it had been named for.
Two things were missing. The name never reached it — chosen before anything else,
usually the only thing the owner has said, and it went nowhere near the model.
And nothing said what orientation is FOR. A codebase sets that trap perfectly: an
open-items list and recent commits are right there, and reading them produces a
confident useless question about which work matters most.
So: the name settles the subject, and the search is for something that HAPPENS
AGAIN — what event recurs here, and what does somebody do by hand every time it
does. Current priorities are not a trigger. Nothing you can only do once is a
commander.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The first self-started intake produced a correct audit — session id, armed state,
the procedure file, the claim script and the incident behind it, six releases by
tag, the fleet doc, what is not currently polling — and then a question at the
bottom. Everything in it was true and it was the wrong shape. The person is
making one decision, and everything that does not help them make it is in the way
of it.
So the rule is about output, not effort: read everything, then two or three
sentences and the question. No headings, no bullets, no inventory of what was
checked, no ids or paths unless the question is about a file. Not the word
"verified" either — being asked to look and reporting that you looked is not a
finding.
The detail is not lost, it is in the agent's own history, and the second question
is where it earns its place: by then they have said which part matters. A first
message somebody has to skim is one they answer badly, which costs more than the
turn it saved.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The intake section named a `deploy/` folder as what to look for, which is a
platform-shaped thought in a file that has to work for a mailbox, a drop folder,
a document library or a machine that runs one script. An example that specific
reads as an instruction.
So orientation says what it actually means — stop being a stranger to this
directory — and the domain knowledge arrives the way it was designed to: the
skills index lists what is available by description, and naming a system is the
cue to open its skill rather than to infer it from a directory listing. Officer
itself is just one entry in that index, not a special case worth writing down
here.
And if there is no skill for what they named, say so and ask. That is a real
answer; inventing a mechanism to fill the gap is not.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A commander can now be started with a button instead of an opening prompt, which
means the first thing it has to do is ask rather than answer. Orientation comes
first — most jobs somebody wants automated have been done here by hand already,
and the shape is on disk. Finding that turns 'how should this work' into 'is this
still how you want it'.
One question at a time, and a written specification confirmed before anything is
armed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The registry gained minesweeper (execution) and the generated skill was two lines
behind, which docs:check catches by regenerating and comparing rather than by
trusting a number written down beside it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Its own section rather than a line inside the shaping questions, because it is a rule and they are advice.
Two independent reasons pointing the same way, which is why it is worth stating as a rule at all. The first
exchange is for agreeing what to watch — a watcher armed before that is armed on a guess, and a wrong
condition fails silently in both directions. And a first-turn commander has not been told where to record
itself, because the transcript id does not exist until that turn begins, so one that armed anyway would be
unstoppable and undeletable.
The second reason gives the first one teeth: if you have not been given paths, you are on your first turn.
The absence is the signal, so this does not depend on the agent remembering which turn it is on.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The rules had leaked toward the one commander that exists. Audited by grepping the commander skill for
deploy vocabulary rather than by rereading it, which found five places where a general rule was written in
terms of the specific job it came from:
- the baseline rule's headline example was "watch for a new tag" — the one case, standing in for all of them.
Now "watch for new X, whatever X is: a tag, a file in a folder, a row, an unread message, an alert".
- the loop "cannot weigh a host" → cannot weigh a situation.
- OFFICER_ROOT being empty "makes every release look permanently undeployed" → makes anything the loop writes
to record its own progress land where nothing reads it, so a watcher has no baseline and acts on the same
work for ever. Same defect, stated as what it costs any watcher.
- "a procedure in a file makes the deploy repeatable next month" → makes the same job repeatable, and
reviewable by somebody else.
- the local-address rule was fleet-specific AND duplicated what the deploy skill already says. Generalised to
"reach what you are watching by the shortest path available", with the Officer-specific instance left where
it belongs.
The cross-reference now names the Deploying Officer SKILL rather than a file path, because a skill has a
description in the index and a file path has to be known about first.
What the audit was checking: a user describing something that has nothing to do with releases must get the
same rules — baseline, claim once, ask before arming if the condition is not clear, spawn for judgement, say
what you did not do. Those were always general. The examples around them were not.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two gaps found by testing the actual goal — "I say watch master for a new tag, and it works without me
listing the caveats" — rather than by rereading what was written.
THE BASELINE. The commander skill had "what must never happen twice", which is a CLAIM: do not act twice on
the same item. The owner's constraint is different and was missing entirely: do not act on items that already
existed when you were armed. "Watch for a new tag" is not a condition — a watcher armed today sees every
historical tag and, unless something says otherwise, treats all of them as news and acts on each in turn.
Nobody says "ignore the ones already there" because to a person it is obviously implied. It is not implied to
a shell loop.
So the skill now names the two honest kinds of baseline — a record of what has been handled, which survives a
restart, or a snapshot taken at arming, which does not — and requires the loop to say which it is using. On
this machine the lock files made the omission harmless. On a fresh one, a new commander would have deployed
every tag in the history, one at a time.
FINDABILITY. The deploy procedure was reachable only through a sentence at the end of the commander skill, so
an agent asked to deploy would have to open one skill and read to its last line to learn the other existed.
It has a description of its own now, which is the entire interface: the agent sees only that before deciding
to open anything.
The new skill does NOT copy the procedure. It names `scripts/deploy-claim.sh`, `docs/servers.md` and the plan
format, which live with the code and change with it — a second copy would be right the day it was written and
wrong the day somebody edits the first, and the copy an agent happened to read would be the stale one. One
hop costs a Read; a wrong procedure costs a fleet.
What it does carry is the fleet-specific part that would not belong in a procedure: poll a local remote and
why (a tag pushed at 21:47 noticed at 23:07 through the public one, twenty seconds through the local),
pm_cwd rather than a hard-coded path, the per-host login, plugins:update restarting sidecars on its own, and
that a skipped host is either behind or current — different things, and only one of them asks the owner for
anything.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Audited it against what the background-job dialog actually sends and against the deploy procedure, rather
than trusting that it was complete. It carried the concepts and five of the nine mechanics. Four were absent,
and three had cost real time to discover:
- OFFICER_ROOT is EMPTY in the sidecar's environment, so a path built from it resolves to /data/... — a lock
lands where nothing reads it and every release looks permanently undeployed.
- stderr must be kept out of a --output-format=stream-json pipe. The CLI prints warnings there and one of
them corrupts the first jq parse.
- jq --unbuffered, or the job panel shows nothing for the duration and reads as hung. A background job with
no output is indistinguishable from a dead one.
- The claim goes before the SPAWN, not inside the action: an action that dies before claiming has claimed
nothing and runs again.
Also added the one instruction the dialog sends that the skill had dropped, and it is the most important of
them: ASK before arming if the condition is not completely clear. A wrong condition fails silently — it
either never fires or fires constantly — and is found out days later. Arming late costs a minute.
The audit is the point. A skill that covers the concepts and misses the mechanics reads as complete and
produces a loop that does not work, which is the failure mode a reference is supposed to prevent.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An agent answering "what is a commander, how do I start one" had nothing to answer from. skills/load.ts
already compiles an index of name + when-to-reach-for-it + path into every session, with the body read on
demand — so this needed skills written, not a mechanism built. There was one skill before these; now three.
skills/platform/SKILL.md is GENERATED by the platform repository's `bun run skills:platform`, and its
`docs:check` fails if it drifts. Do not edit it here — an edit is lost on the next run, and the generator
carries the prose for exactly that reason.
skills/commander/SKILL.md is written by hand, because none of it is derivable. What is in it is what three
days of running one taught, including the parts that surprised us:
- A commander is an ordinary chat session in a particular directory. Not a special agent — a conversation
plus a loop somebody started from inside it.
- Three pieces, and people get the third wrong: the conversation, the shell loop that waits, and the HEADLESS
AGENT the loop spawns when it fires. They expect the commander itself to wake up. It does not.
- Its cost line understates, structurally: only turns crossing the platform's chat socket are recorded, and a
spawned agent's never do. A commander that spent dollars through children can display cents.
- A spawned agent cannot be linked to its parent after the fact. The entry types that look like they mark one
are the harness's own and appear in both. If the link matters, the loop must record the id itself.
- Poll a local address, never a public hostname behind a reverse proxy — rate limiting there reads as an
access-rights error and is not one.
- The platform may not know a watcher exists: its bookkeeping engages only for the hand-back-and-re-arm fire
behaviour, so a working loop can sit beside a row that says unarmed.
The largest section is about helping somebody SHAPE one, since that is the part that is a conversation rather
than a form. Four questions, and the third is the one nobody volunteers: what must never happen twice. A
trigger that stays true after a failed action fires again, and again.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5