Create a New Workflow
Author a workflow — the fifth content type — as a self-contained workflows/<name>.mjs script run by Claude Code's Workflow tool. A workflow fixes its phases, fan-out, and verification structure in JavaScript: its control flow is deterministic and rereadable, while the outputs of its agent() calls are LLM subagents and remain nondeterministic. This skill is the procedure for authoring one; guides/creating-workflows.md is the API reference it draws on.
Vendor-API caveat. The Workflow run model is generally available on paid Claude Code plans (~v2.1.154+), but the script-authoring surface (the injected agent() / parallel() / pipeline() / phase() / log() / workflow() primitives and the args / budget globals) is an evolving vendor API — accurate as observed in Claude Code v2.1.x, subject to change, never CI-enforced.
When to Use
- You have a repeatable, parameterized procedure that coordinates several agents and want it captured as a reusable artifact whose shape you already know.
- You need a review, research, or migration procedure to run the same way every time, with the fan-out and verification logic auditable in code rather than re-decided by a lead each run.
- You are adding a reviewed seed to the
workflows/ library, or authoring a personal workflow for .claude/workflows/.
- You are deciding between writing a team and a workflow — read Step 1 first.
Inputs
- Required: Workflow name (lowercase kebab-case, e.g.,
review-changes). This becomes the filename stem, the sidecar name:, and meta.name — all three must be identical.
- Required: Purpose (one paragraph: what repeatable procedure this codifies and why its control flow should be fixed in code).
- Required: Phase plan (the named stages, e.g., Classify → Verify → Synthesize) and the fan-out shape (per-item
pipeline() vs barrier parallel()).
- Optional: Parameters the workflow accepts via
args (default them so it runs with no input).
- Optional: Source material (an existing ad-hoc multi-agent procedure to formalize).
Procedure
Step 1: Confirm a Workflow Is the Right Tool
A workflow is one of five content types. Choose deliberately:
- A skill is how one agent performs a procedure. A team is a declarative roster the lead coordinates at runtime (model-driven, adaptive). A workflow is a script whose phases and fan-out are fixed in code (deterministic control flow, auditable, parameterized).
- Pick a workflow only when the coordination shape is known in advance and you want it repeatable and rereadable. If the right next step depends on what the last step found, pick a team instead.
Expected: A one-line justification for why this is a workflow and not a team or a single skill.
On failure: If the coordination must adapt turn-by-turn, stop and use create-team. If only one agent acts, use create-skill.
Step 2: Copy the Template
Start from the canonical scaffold — never a blank file:
cp workflows/_template.mjs workflows/<name>.mjs
For a personal (non-library) workflow, copy into .claude/workflows/<name>.mjs instead. The template carries the sidecar block, a pure-literal meta, a phase(), a pipeline() fan-out, an agent({ schema }) call, and the hard constraints inline.
Expected: A new .mjs file that is a verbatim copy of the template.
On failure: If workflows/_template.mjs is missing, you are on a pre-Phase-1 checkout — fetch main.
Step 3: Satisfy the Triple-Name Discovery Contract
Rename in the three places that must stay identical — the filename stem, the sidecar // name:, and the meta.name literal:
grep -n "name:" workflows/<name>.mjs # sidecar + meta.name must equal the filename stem
That triple equality (filename ↔ sidecar name ↔ meta.name) is the Workflow({ name }) and /<name> discovery contract.
Expected: All three read the same kebab-case name.
On failure: A Workflow not found by name error at runtime means the triple is out of sync — re-check all three.
Step 4: Write the Pure-Literal meta and Sidecar
export const meta must be a pure literal — no variables, function calls, spreads, or template interpolation. Required fields: name and description. phases (one entry per phase the workflow uses, whether opened by a global phase() call or a stage's per-call phase: option) is optional but recommended. Mirror name, description, and the phases titles in the top-of-file sidecar comment block — the sidecar is the catalog source of truth (the analogue of YAML frontmatter on the other content types), readable by grep without a JS parser.
Expected: meta is a literal object; the sidecar agrees with it; phases ⊇ every title passed to phase() or a stage phase:.
On failure: A meta must be a pure literal error means a value references a variable or call — inline it.
Step 5: Build the Body
The body runs inside an async wrapper — use top-level await and a top-level return directly. Compose with the injected globals (no imports):
pipeline(items, ...stages) — the default: each item flows through every stage with no barrier between stages (wall-clock = slowest single chain).parallel(thunks) — a barrier: use only when a stage needs every prior result at once (dedup, an early-exit count, a synthesis step).agent(prompt, { schema, label, phase, agentType }) — spawn one subagent; with { schema } it returns a validated object.phase(title), log(message), and the args / budget globals. Default args so the workflow runs with no input.
Pass a JSON Schema as { schema } to force structured output (no free-text parsing). See guides/creating-workflows.md for the full primitive reference.
Decide the durability model before writing the body. The script cannot touch
the filesystem, so it cannot checkpoint itself: an interrupted Workflow(...) call
returns nothing whichever fan-out primitive it used, and resumeFromRunId is
same-session only (the tool's own contract; observed here for process death) —
once the launching session is gone, so is the run. Answer in one line: what survives
if this run dies halfway? The invariant is that every expensive result is on disk
before the run can die; the two ways to get there differ in where that write
happens and compose freely. Either the agents write validator-gated artifacts to
disk as they go (the batch-generate-waves
model — a stage that dies then loses only its unfinished items), or the invoker
splits the run into batches and persists each batch's results between
Workflow(...) calls, or both. Salvaging a run that did neither means hand-parsing
~/.claude/projects/<project-slug>/<session-id>/subagents/workflows/<runId>/journal.jsonl,
which recovers the results that finished, not the run. Full treatment:
guides/creating-workflows.md § Surviving an
Interrupted Run.
Expected: A body that defaults its inputs, fans out with the right primitive, returns a value, and a one-line answer to what survives if the run dies halfway.
On failure: If you reach for parallel() only to flatten or map between stages, that barrier is not justified — do the transform inside a pipeline() stage. If the honest answer to the durability question is "nothing", changing the primitive will not help: move the writing into the agents, or split the run into batches the invoker persists between.
Step 6: Honor the Capability Contract (#285)
agent({ agentType }) names the spawn type per call — the workflow's native expression of the persona-vs-spawn decoupling. The intent rule applies:
- A stage that mutates artifacts (uses Write/Edit/Bash to change files, or runs under
isolation: 'worktree') must target an implementing agent type.
- A read-only analysis stage targets an advisory type (e.g.,
Explore).
Set agentType explicitly on every stage so the contract is visible, not implied.
Expected: Every agent() call names an agentType whose capability matches what the stage does.
On failure: A mutating stage targeting an advisory type cannot write — switch it to an implementing type such as general-purpose.
Step 7: Apply the Adversarial-Verification Fail-Safes
If your workflow verifies candidate findings (the classify → refute → synthesize spine), bake in the three lessons the review-changes seed encodes:
- Gate on affirmative confirmations, not refutations.
agent() returns null when a subagent is skipped or dies, so filter(Boolean) before counting and require a majority of confirmations to survive (confirmedVotes >= Math.floor(n / 2) + 1). Surviving when "few enough refuted" inverts the fail-safe — a dead refuter would let an unverified finding through.
- Give verifiers the evidence the proposer had. If the classifier read a diff, tell the refuters to read it too — otherwise change-specific findings get default-refuted and unfairly killed.
- Default to refuted/unconfirmed unless a verifier can independently reproduce the finding.
Expected: Survival gates on a confirmation quorum, verifiers share the proposer's evidence, and null results are filtered.
On failure: If real findings vanish, check that verifiers aren't starved of context (lesson 2); if junk survives, check the gate counts confirmations, not refutations (lesson 1).
Step 8: Validate the Script
Workflow scripts use a top-level return, which the runtime accepts (it wraps the body in an async function) but raw ESM rejects — so plain node --check reports Illegal return statement on a valid workflow. Use the wrap-then-check recipe:
{ echo '(async()=>{'; \
sed 's/^[[:space:]]*export const meta/const meta/' workflows/<name>.mjs; \
echo '})()'; } | node --check -
The authoritative check is running it: Workflow({ name: '<name>' }).
Expected: The wrap-check passes with no syntax error.
On failure: Do not "fix" a top-level return to pass raw node --check — that would cripple the script. Use the wrap-check; debug any other syntax error normally.
Step 9: Install and Run
The Workflow tool resolves Workflow({ name }) from .claude/workflows/<name>.mjs. In Phase 1, install by hand:
cp workflows/<name>.mjs .claude/workflows/<name>.mjs # curated installs prefix: almanac-<name>.mjs
Then invoke Workflow({ name: '<name>' }) or the /<name> slash command. .claude/workflows/ is user-writable and the save-flow writes there, so a curated install must namespace (almanac-<name>.mjs) to avoid shadowing a user's own workflow.
Expected: The workflow runs end-to-end and returns its value.
On failure: If /<name> is not found, confirm the file is in .claude/workflows/ and the triple-name contract holds (Step 3).
Step 10: Register (Library Contributions)
Phase-2-pending. A workflows/_registry.yml, CI validation of the sidecar, and a CLI install adapter are deferred behind the #288 promotion gate (~8–10 workflows + a real install request). Until they land, a library workflow needs no registry entry — the sidecar frontmatter is its catalog metadata and discovery is by filename. When the registry exists, this step becomes "add an entry derived from the sidecar."
Workflows are excluded from i18n. Unlike skills/agents/teams/guides, a workflow is executable code, not prose — do not scaffold translations for it.
If contributing a reviewed seed to agent-almanac, place it in workflows/, cross-reference it from guides/creating-workflows.md, and carry the vendor-API caveat in any prose you add.
Expected: A library workflow lives in workflows/ with an accurate sidecar; no registry or translation steps are attempted in Phase 1.
On failure: If a tool expects workflows/_registry.yml, you are ahead of the promotion gate — stop and confirm Phase 2 has shipped.
Step 11: Contain a Fan-Out That Runs Against a Live Repository
The advisory/implementing contract in Step 7 governs the agent type a stage
declares. It does not constrain what a Bash-capable agent does to the working
tree, and a "read-only" review fleet is exactly where that gap bites: every agent
inherits the repository as its default working directory.
Name a write location in every prompt — one line per Bash-capable stage,
after the preamble, and the only control that reaches a stage nobody classified as
writing. Include the read-only-by-intent stages: those are exactly the ones that
pollute the repository by inherited working directory alone, with no collision, no
git add and no intent to touch it. Copy the template's WRITE_LOCATION: it names
the stage's own $DIR (the directory the preamble's mktemp -d created), covers
every file the agent produces by any tool, and rules out the repository root. It
also tells the agent to print that path and reuse it literally, because nothing but
files carries over between an agent's tool calls — each Bash call may start again in
the launch directory with DIR unset. A stage that must also write elsewhere
narrows the line as a <PREFIX>_WRITE_LOCATION constant ("write only under <that
directory> and your own $DIR; nowhere else in the repository") rather than
dropping it. A7b looks for the identifier, so a sentence typed in its place fails.
Bracket the run with repo-guard — this is the mechanical control. A workflow
body cannot run shell (no filesystem or Node API), so this is the invoker's
job, around the Workflow(...) call:
npm run guard:snapshot # before launching the workflow
npm run guard:verify # after it returns
npm run guard:release # when the run is genuinely over
verify keeps the snapshot and snapshot refuses to overwrite one, so skipping
guard:release leaves the next run failing with "a snapshot already exists".
That is deliberate — re-arming mid-run would rebaseline the damage — but it means
release is part of the loop, not an optional tidy-up. Note also that npm swallows
--release as its own config, which is why there is a script rather than a flag.
It compares HEAD, branch, worktree status, the content of every changed or
untracked file, and index flags. Exit 1 prints the difference; exit 2 means it
could not answer and must never be read as a pass. Two comparisons carry most of
the weight: HEAD, the only one that catches a subagent that committed (the tree
reads clean afterwards), and file content, without which a stray write to an
already-modified file is invisible — its status line does not move.
It does not cover ignored paths; walking them would mean hashing
node_modules.
Contain the agents themselves. Prepend the REPO_SAFETY preamble from
workflows/_template.mjs to the prompt of every agent that may run shell
commands — verifiers included, since a verifier reproducing a finding is the
agent most likely to build a fixture. Copying the template gets this by default.
Its rules, in the template's own order — deliberately uncounted, because a count
here is a claim about a file this one does not own, and it had silently drifted
by one before anyone noticed:
-
mktemp -d, never a shared fixed path. Parallel agents told to build
fixtures independently converge on the same obvious filename, and the second
clobbers the first.
-
cd "${DIR:?}" || exit 1. A bare cd that fails does not reliably abort
the surrounding script, and every following relative path then resolves
against the repository. Braced because cd "" returns 0 without moving, so an
unset DIR leaves the agent where it started and || exit 1 never fires.
-
An absolute path under $DIR in every destructive command, braced — write
rm -rf "${DIR:?}/fixtures", never rm -rf fixtures and never a bare
"$DIR/fixtures". The cd above is one control; a relative rm makes it the
only one, so the single failure it guards against becomes repository damage
instead of a wasted command. The brace is not decoration: an absolute path
trades the dependency on the working directory for one on $DIR being set,
and cd "" succeeds without moving, so an unset DIR leaves the agent
standing in the repository and expands "$DIR/fixtures" to /fixtures.
:? refuses both, unset and empty alike, on bash 5.2 and zsh 5.9.
-
A cwd assertion before git add, git commit, or a tool run with a write
flag — that is its scope, and it is narrower than "anything destructive",
which is why rule 3 exists: an rm falls outside it. Braced for rule 3's
reason too, since outside any repository git rev-parse prints nothing and an
unset DIR makes the unbraced form compare "" to "" and pass:
[ "$(git rev-parse --show-toplevel)" = "${DIR:?}" ] || exit 1
-
Never git commit, git update-index or git checkout -- against the
repository itself, and never a repo tool with a write flag there.
Prefer isolation: 'worktree' for any stage that might mutate — it is the
structural control and stronger than either of the others. The gap it leaves is
the one the prompt sentence covers: a stage that is read-only by intent is never
classified as mutating, and that is exactly the stage that pollutes by inherited
working directory. So the three are complements. The prompt prevents a compliant
agent from writing where it stands; worktree isolation contains a stage you
expected to write; the guard detects what neither caught, and because a workflow
body cannot run shell it runs only before and after the whole Workflow(...)
call, blind for the duration of the fan-out. What a prompt cannot do is bind: in
#493 it named the directory, the tool and the file to copy, the agent complied
with all three, and the write still landed in the repository because the failure
was mechanical. Instruction is worth its one sentence; enforcement is the guard's
job and the worktree's.
Expected: npm run guard:verify exits 0 after the run.
On failure: Exit 1 prints what moved and the recovery command. A stray commit
is recoverable while unpushed: confirm it is unpushed, state what the reset
destroys, then git reset --mixed <recorded-head> and remove the stray files.
Exit 2 means the guard could not compare — re-snapshot and re-run rather than
treating it as a pass.
Validation
Common Pitfalls
- Writing a workflow when a team fits. If the next step depends on what the last step found, the coordination is adaptive — use a team. Workflows are for procedures whose shape is fixed in advance.
- Counting refutations instead of confirmations. Gating survival on "few enough refuted" lets a
null/dead refuter pass an unverified finding through. Gate on a majority of affirmative confirmations.
- Starving verifiers of context. Refuters that see less than the proposer (e.g., the file but not the diff) default-refute legitimate change-specific findings and kill them.
- "Fixing" the top-level
return. It is valid Workflow dialect; rewriting it to satisfy raw node --check breaks the script. Use the wrap-check.
- Forbidden non-determinism.
Date.now() / Math.random() / argless new Date() break workflow resume. Pass timestamps via args; vary randomness by agent index or label.
- Building Phase-2 machinery early. Do not add a
workflows/_registry.yml or scaffold translations for a workflow — registries/CLI/validation are gated, and workflows are i18n-excluded.
- Treating a prompt sentence as a guarantee. "Build your fixture under
/tmp" prevents a compliant agent from writing where it stands, which is worth its one sentence (Step 11) — but an agent can follow it exactly and still write to the repository when its cd fails, and no amount of specificity changes that. Pair it with worktree isolation, a cwd assertion, and a HEAD check; never substitute it for them.
- Sharing one scratch path across parallel agents. Agents solving the same problem pick the same filename. A second agent overwriting
$SCRATCH/fixture.sh between the first agent writing it and running it turns a correct invocation into someone else's script — the first agent then runs the second's file, believing it ran its own.
- Believing
git status proves a fan-out was read-only. It cannot see an agent that committed. Compare HEAD, and treat unexplained staleness in any generated artifact derived from the corpus as evidence the corpus moved.
- Expecting a fan-out primitive to give you durability. An interrupted
Workflow(...) call returns nothing whether it fanned out with parallel() or pipeline(): the script cannot persist what already came back, and resumeFromRunId is same-session only. pipeline() buys wall-clock, not survival. Decide the durability model in Step 5 — gated artifacts on disk, or batches the invoker persists between calls.
Related Skills
create-skill — author a SKILL.md (the how for one agent); the meta-pattern sibling.create-agent — define an agent persona; workflows spawn agents by agentType.create-team — compose a declarative, model-driven roster (the adaptive counterpart to a workflow).commit-changes — commit the new workflow file.review-codebase / review-pull-request — the single-reviewer skills the review-changes workflow coordinates many of.