pastilhasandClaude Opus 5
57eaf603a0
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>
133 lines
8.3 KiB
Markdown
133 lines
8.3 KiB
Markdown
---
|
|
name: Commanders
|
|
description: >-
|
|
Use when the user asks about a commander — what one is, how to start one, why one is not firing, how much
|
|
one costs — or when they describe work that should keep happening while they are away ("watch X and do Y",
|
|
"every time Z, run this"). Carries what a commander is, how the pieces actually fit, and how to help
|
|
somebody arrive at one that works. Open the Officer platform skill too if the answer needs an endpoint.
|
|
version: 1
|
|
---
|
|
|
|
# What a commander is
|
|
|
|
An agent that keeps working when nobody is watching. It waits for something, acts on it, and reports.
|
|
|
|
Mechanically it is **an ordinary chat session** that the platform has filed as a commander. Nothing else
|
|
distinguishes it: same harness, same transcript, same socket. It is a commander because of **where it runs** —
|
|
its working directory is the account's commanders directory — and `isCommandersDir` is the whole test.
|
|
|
|
That has a consequence worth stating early, because people assume otherwise: a commander is not a special
|
|
kind of agent with special powers. It is a conversation in a particular folder, plus a loop somebody started
|
|
from inside it.
|
|
|
|
# The three pieces, and which one people get wrong
|
|
|
|
**1. The conversation.** Where you and it agree what the job is. This is the part to spend time on.
|
|
|
|
**2. The wait.** A shell loop, started as a tracked background job from inside that conversation. It polls,
|
|
and when its condition is true it acts. The wait happens **in the shell** — not by the model waking up to
|
|
check. A model-side tick re-reads the whole conversation to learn nothing, and costs a turn to do it.
|
|
|
|
**3. The action.** The loop cannot do judgement — it cannot read a plan, weigh a host, or write a report. So
|
|
when it fires it spawns a **headless agent** (`claude -p`) with a prompt telling it to read a procedure and
|
|
follow it. That agent does the work and exits.
|
|
|
|
The piece people get wrong is 3. They expect the commander itself to wake up and act. It does not: it started
|
|
a loop, and the loop starts somebody else.
|
|
|
|
# Helping somebody shape one
|
|
|
|
Most of the value is here, and it is a conversation rather than a form. Four questions, in this order:
|
|
|
|
**What is the trigger, exactly?** Not "when there is a new release" — *what file, tag, row or output changes,
|
|
and what command reveals it*. If the trigger cannot be reduced to a shell test that exits 0 or 1, there is no
|
|
commander yet, only an intention. Push until it can.
|
|
|
|
**What happens when it fires?** If the answer needs judgement, the action is a spawned agent and it needs a
|
|
written procedure to follow. Say that out loud — a procedure in a file, versioned, is what makes the same
|
|
deploy repeatable next month. A prompt typed into a dialog is not.
|
|
|
|
**What must never happen twice?** This is the question nobody volunteers and it is the expensive one. A
|
|
trigger that stays true after a failed action fires again, and again. Ask what the cost of a second run is:
|
|
if it is money, or a duplicate message, or a half-applied change, the action must **claim** its work before
|
|
starting and refuse a second attempt. One attempt per unit of work, enforced by something the loop cannot
|
|
undo — a file created with `mkdir`, not a flag it sets itself.
|
|
|
|
**What does "new" mean — and this one you must supply, not ask for.** "Watch for a new tag" is not a
|
|
condition. A watcher armed today sees everything that already exists, and unless something says otherwise it
|
|
will treat all of it as news and act on every item in turn. Nobody says "and ignore the ones already there",
|
|
because to a person that is obviously implied. It is not implied to a shell loop.
|
|
|
|
So a watcher needs a **baseline**, and there are only two honest kinds:
|
|
|
|
- **A record of what has been handled.** Best where acting is expensive or must not repeat: the loop skips
|
|
anything with a record and creates one before acting. This also survives a restart, which a remembered
|
|
baseline does not.
|
|
- **A snapshot taken at arming.** Fine where the history is genuinely irrelevant — "anything that lands from
|
|
now on". Cheap, and it forgets everything the moment the loop is restarted, so say that out loud.
|
|
|
|
Choose one and say which, in the condition itself. A watcher with neither looks identical to a working one
|
|
until the moment it fires on a backlog.
|
|
|
|
**What does "done" look like to you?** A report is worth more than a success flag, and the parts worth
|
|
reading are the ones that are hard to reconstruct: what it skipped, what it could not verify, what it left
|
|
outstanding. Ask for those explicitly or you will get a summary of what went right.
|
|
|
|
# Writing the loop, if you are the one writing it
|
|
|
|
The background-job dialog already sends the load-bearing mechanics — use the harness's own background
|
|
mechanism, keep the wait in the shell, put the test into the shell condition, and **ask first if the
|
|
condition is not completely clear** rather than arming a guess. That last one matters more than it reads: a
|
|
wrong condition fails silently, either never firing or firing constantly, and it is found out days later.
|
|
Arming late costs a minute.
|
|
|
|
Four details the mechanics do not carry, each of which was learned by getting it wrong:
|
|
|
|
- **`OFFICER_ROOT` is empty in the sidecar's environment.** Any path built from it resolves to `/data/...`,
|
|
so a lock file lands somewhere nothing reads and every release looks permanently undeployed. Set it
|
|
explicitly in the loop.
|
|
- **Keep stderr out of a `--output-format=stream-json` pipe.** The CLI prints warnings there — a
|
|
connectors notice, among others — and one of them landing in the stream corrupts the first `jq` parse.
|
|
Redirect it to its own reader.
|
|
- **`jq --unbuffered`**, or the job panel shows nothing for as long as the work takes and reads as hung.
|
|
A background job that produces no output is indistinguishable from a dead one.
|
|
- **The claim goes before the spawn, not inside the action.** If the action claims its own work, an action
|
|
that dies before claiming has claimed nothing and will run again.
|
|
|
|
# Things that are true and surprising
|
|
|
|
- **Its cost line understates.** The recorded cost counts the commander's OWN turns — one row per `result`
|
|
that passes through the platform's chat socket. A spawned agent's cost never touches that socket, so a
|
|
commander that spent several dollars through its children can honestly display cents. Do not quote the
|
|
number as total spend.
|
|
- **A spawned agent cannot be found from its parent.** Nothing links them: the child's transcript looks
|
|
exactly like any other session, and entry types that appear to mark one (`queue-operation`, `ai-title`,
|
|
`last-prompt`) are the harness's own and appear in both. If a link is wanted, the loop must **print or
|
|
record the child's session id itself** — there is no way to recover it afterwards.
|
|
- **A child transcript is not permanent.** It is readable while it lives and for a while after. Two from a
|
|
previous day were gone. Anything worth keeping must be captured while it runs.
|
|
- **Poll a local address, never a public hostname.** Where the thing being watched is on the same machine or
|
|
the same tailnet, reach it directly. A public hostname through a reverse proxy shares one source IP with
|
|
everything else behind it, and rate limiting there refuses connections for long stretches — which shows up
|
|
as an access-rights error and is not one.
|
|
- **The platform may not know a watcher exists.** Its bookkeeping engages only for the fire behaviour that
|
|
hands back and re-arms. Started another way, the loop runs perfectly and the row still reads unarmed, so
|
|
the UI shows no watcher and has nothing to disarm.
|
|
|
|
# When something is not firing
|
|
|
|
In this order, because each rules out the one below:
|
|
|
|
1. **Is the loop alive?** It is a tracked background job — look at the job, not at the agent.
|
|
2. **Is its condition ever true?** Run the test by hand, in the same shell form the loop uses.
|
|
3. **Can it reach what it polls?** An access-rights error on a repository or an endpoint that plainly exists
|
|
is usually a rate-limited public path, not a credential.
|
|
4. **Has it already claimed this work?** A refusal to act twice looks identical to a failure to notice.
|
|
5. **Only then** the model, the prompt or the procedure.
|
|
|
|
# Where to look next
|
|
|
|
For endpoints, permissions or why something is refused, open the **Officer platform** skill. For a deploy
|
|
specifically, `prompts/deploy-commander.md` in the platform repository is the worked example: a real
|
|
procedure, with the reasoning for each rule written beside it.
|