design-workflow

Designing a headsign workflow

A headsign workflow is one YAML file, committed to the repository. It names the phases of a job and, for each phase, the shell commands whose exit codes decide whether the work may leave it. This skill works out what those phases and those commands should be for this repository, settles the shape with the person who asked, and writes the file.

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/design-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.

What this skill does not do

1. It is not itself driven as a headsign run. Do not headsign start anything in order to write a workflow. This is the machinery for making workflows; it does not need to be one.
2. It never runs headsign start on its own judgment. start does not just name a phase — it prints that phase's instructions, and an agent's discipline is to obey them, so the user's actual work begins the moment you call it. Someone who asked for a workflow to be written did not ask for the work in it to begin, least of all from a file that has never run. Finish at the file plus the one line that would start it. If the user asks you to write it and run it, that is a second request, and from there the workflow skill takes over.
3. It never deletes or renames a workflow file. Revision here means the contents of a file. A rename is not a design change, and it is the shortest path to breaking a run: a run goes looking for the exact path it recorded at start.
4. It does not build the checks a repository is missing. If there is nothing here a shell command can judge, name what is missing and stop. Adding tests, a linter, or a build to someone's repository is a different job, and taking it turns this into a tool that no longer writes workflows.
5. It does not send anyone to docs/workflow-reference.md. That file ships in neither the plugin nor the npm package, so it is not on the user's disk. Everything you need is below; the rest is in references/schema.md, next to this file. For the same reason, do not point at example.headsign/ either.
6. It does not have to match the paste-in prompt in headsign's README. They are independent documents, maintained separately. The order between them is only this: this skill is the procedure for someone who has adopted headsign, and the README's prompt is that procedure adjusted for someone who has not yet. If a user arrives holding that prompt's output, take it (step 1) — but do not treat its wording as a specification for yours.