workflow

headsign workflow

headsign is a phase gate: you do the work, deterministic shell checks decide the phase transitions. You never judge for yourself whether a phase is done — the gate does.

When this skill runs inside the headsign plugin in Claude Code or Codex, the CLI is bundled with it and no install is needed. In Claude Code, headsign <cmd> below means:

node "${CLAUDE_SKILL_DIR}/../../dist/headsign.mjs" <cmd>

In Codex, use the absolute SKILL.md path that Codex supplies for this skill. Go up from skills/workflow/SKILL.md to the plugin root, then invoke dist/headsign.mjs with Node. Do not assume a session environment variable for the skill directory; the Codex contracts checked for this release did not confirm one.

(A PATH-installed headsign works too, and so does npx headsign once the package is installed. Check which you have before reaching for either — command -v headsign names a PATH copy if one exists. npx headsign with nothing installed does not fail; it installs from the registry, at a version npm chooses rather than the one this plugin ships, and that copy will read and write the same .headsign/state.json the bundled one has been driving.)

If the bundled path above does not exist, this file is a copy running outside its plugin (for example, in .claude/skills/ or .agents/skills/) — the bundle only ships with the plugin. Use a PATH-installed headsign, or npx headsign on the terms above; otherwise stop and tell the user to either install the plugin or npm install the package. Do not guess at other paths.

The discipline

1. First, check whether this session is the driver. If this session did not run headsign start, and hasn't been explicitly asked (by the user, or by the session that did) to continue an existing run — do not run headsign next or headsign abort. A repository can have more than one coding-agent session open on it at once (a lead plus teammates, or a subagent working alongside the session that spawned it), and only the one driving the run should touch it: obeying a nudge you weren't meant to answer can burn a retry or advance a phase nobody asked you to touch. Want to know what's happening without touching anything? Run headsign status — it's read-only, and safe to call at any time. It also prints the current phase's instructions, in the same block next uses. If you are delegating the work to someone who does not run headsign — a subagent, a teammate — that block is what you hand them. They cannot see the gate's requirements any other way, and requirements you paraphrase from memory are the ones that come back as a gate failure a lap later.
2. If you are a delegated agent and were entrusted with driving a run, claim it first — don't just start calling next. This applies when you are a teammate (Claude Code's agent-teams feature) or a subagent: you share the spawning session's process and environment, so no command you run can say who you are, and headsign next records no driver at all. Instead: run headsign claim, then end your turn. The seal happens at your own turn end — that is the only moment headsign can learn which delegated agent you are — and the hook confirms it in its message, naming the workflow and phase. Do not run headsign next before you have seen that confirmation. If some other agent got adopted by mistake (it ended a turn while your marker was armed and could name itself), run headsign claim again from the agent that should be driving: a new claim re-arms the marker, and that agent is a real contender for it because its own turn end always fires the event that seals. Another agent naming itself first can take this marker too, so re-claim until the confirmation names the agent you meant. A session driving a run on its own does not need claim at all: start stamps it as the run's mover the moment the run begins, every next it runs re-stamps it, and while nobody has claimed the run the hook nudges that stamped session — exactly the backstop that session wants. A second session merely standing in the same directory, once the first has run start or next, is not nudged for a run it never touched — it does not learn a run is there by being nudged about it; a run with no session on record (one begun before this behavior shipped, one driven from a terminal rather than a session, or one whose state was hand-edited) still falls back to nudging whichever session stops there. Skipping the claim fails silently rather than loudly: the run stays unclaimed, so every later nudge goes to a session — usually the idle one that delegated to you — while nothing holds your own turns at all. (Nothing records them either: unheld is written only for a stop headsign can attribute, so an unclaimed run leaves no line for your turn ends.) And if you need to check whether you are the driver, don't read it off headsign status — it reports whether some delegated agent holds the run, never whether that agent is you. As a delegated agent, the reliable signal is the hook itself: if your turn ends are being pushed back to headsign next, this run is yours to drive. Read which message you got: an ordinary nudge fires only on a positive match, but Claim confirmed … means an armed marker just seated you — if you did not run headsign claim, you have taken a seat another agent was asking for, so say so and let it claim again. The test only works in this direction and only for delegated agents: ending quietly proves nothing (not having claimed, the host's already-continuing flag, an exhausted nudge cap, a pause note, HEADSIGN_OBSERVER, a directory the walk-up resolved only via CLAUDE_PROJECT_DIR, or a run this session simply never touched while someone else was last recorded moving it, all end turns quietly), and a session gets nudged on any run nobody has claimed and nobody has yet moved, whether or not it is driving — once someone has moved it, only that session is. A nudge arrives roughly once per exchange, not once per turn end. When the hook holds a turn, the host flags the continuation, so the ending of that turn passes quietly — recorded as an unheld line in .headsign/log and on headsign status's last stop: line. The window is one turn wide and closes when the turn ends. A probe is not free either: one that comes back as an ordinary nudge spends one from the cap, one that passes while your own pause note is armed consumes the note, and one that lands under another agent's armed marker consumes that marker. Probe deliberately, not by habit.
3. To begin a workflow: headsign start, or headsign start <name> when .headsign/ holds more than one — <name> is the file's basename, so headsign start fitness runs .headsign/fitness.yaml. Either way it prints the first phase's instructions. If start reports it cannot read .headsign/workflow.yaml, this repository names its workflows rather than keeping a default: list .headsign/ and start the one you were asked for.
4. When you have done work you think finishes the phase — or have just recovered from compaction and need to know where the run stands — run headsign next and obey the token on stdout's first line — merged with stderr, a progress line from the running gate may arrive first, so read stdout on its own. That one habit is the whole protocol. next is a judgment, not a peek: it runs the phase's gate, and a failure spends one of that phase's attempts. When you only want to look, run headsign status (rule 1) — it judges nothing and costs nothing. And when you want to know how your last turn end was handled, headsign status is the first command to run on resuming, before headsign next: next resets the nudge counter, and the record holds only the most recent stop.
5. RETRY → the output shows exactly which check failed and its last output. Fix that, then run headsign next again. ADVANCE → follow the printed instructions of the new phase. If ADVANCE <phase> is followed by a line like --- gate failed: ... → routed to <phase> ---, the previous phase's gate rejected the work and routed you here — read that line, it's why you're back. A line like --- routed: when "<command>" → <phase> --- (or --- routed: default → <phase> ---) means the opposite: the previous phase passed, and its on_pass routes chose this phase; the quoted command is the condition that matched. Either way, the phase you were sent to is the one printed on stdout's first line — read the line, don't infer the move.
6. Never end the run on your own judgment while the answer is anything other than COMPLETE. If you are genuinely stuck — or the user asks to stop mid-run — record why with headsign abort <reason> and report to the user; that's a legitimate exit, but it's permanent: the run cannot be resumed, and a later headsign start rewrites .headsign/state.json whole. What it does not end is .headsign/log: the reason you type outlives the run, and so does everything logged before it. So ending a run deliberately costs the run, not its history. The rest of what it costs is nothing, and this is worth knowing before you have to decide in a hurry: state.json is gitignored, so ending a run leaves every tracked file exactly as it was, and the artifacts the run already wrote are untouched — committed ones by definition. One place empties, and it empties at the next start rather than at the abort: .headsign/tmp/, which a run begins by deleting whole, so marks and notes kept there go when the replacement run starts. What you lose is the position: the phase, the attempt counts, the walk back to here. So the only real question is how expensive this workflow's earlier gates are to pass again, which you can read off the workflow file you are holding. To pause rather than end — stepping away to resume later — write one line to .headsign/tmp/stop-note naming what you are waiting for, and stop again. If you cannot name it, you are not blocked — run headsign next instead. The stop-boundary hook passes immediately, and headsign next picks the run back up later from the same phase. The hook consumes the note, so one note covers one turn end — if the wait runs over several exchanges, write it again before each turn that ends still waiting. ESCALATE means stop working and ask the user for direction. Some kinds end the run and some do not, so read which one you got before deciding anything — headsign status answers it directly, since a run that ended reads ESCALATED rather than RUNNING. Two kinds leave it running, so the user can answer and have you continue from the same phase. One reads max_total_iterations (<n>) reached: the user can raise that limit. The other reads the workflow's rules changed under this run — the workflow file was edited while the run was walking it, which headsign allows but reports once; the user either puts the file back or tells you to run headsign next --accept-graph-change, which accepts the change and counts it (the count is named at COMPLETE). A bare next never accepts it, however many times you run it — it reports the same change again and spends nothing, so do not try to get past this by asking twice. If you made that edit, say so plainly when you report it. Some edits are not reported, and silence there means "not a pinned key", never "not noticed" — so do not read it as permission you were granted, or as a report that failed. What is pinned is the rules of every phase this run can still reach, plus limits: gate, ready, clear, on_pass, on_fail, max_attempts. A phase's description is not — rewriting the instructions you were handed is invisible to this by design, and so are comments, formatting, and any phase the run can no longer reach. Also unreported: the contents of anything a check runs. run: "sh checks/thing.sh" pins that string, not the script, so editing that script mid-run changes what the gate decides with nothing said. If you need such a change on the record, abort and start again rather than editing under the run.