agentleFS
MicrosoftKnown publishermicrosoft/PilotSwarm/packages/sdk/plugins/workflow/skills/workflow-reference/SKILL.md

workflow-reference

Skill17 starsChanged 9 months agoMITView on GitHub

Field reference for Workflow YAML (root keys, every state type, bindings, outputs, runtime error codes), what the engine guarantees, and a review fan-out example. For design, call load_skill with name workflow-authoring.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every state except a terminal has transition: { next: { <route>: <state> } }.

    line 55
  2. Very specific:

    Timers: Every deadline (a wait, a receive's wait, a request, an agent or parallel timeoutSeconds, the run's limits.timeoutSeconds) is a …

    line 257
  3. Very specific:

    Pause: No state starts and no result is routed until resume.

    line 265

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Workflow reference

Exact fields for apiVersion: pilotswarm.dev/v1 definitions and the workflow tools. workflow-authoring explains how to design with them.

Ids: a state id or an outcome is a letter, then at most 63 letters, digits, _ or -. State ids are unique in the whole workflow, body and branch states included. A contract name is Name@N (for example BuildEvent@1).

Root keys

KeyRule
apiVersionpilotswarm.dev/v1
kindWorkflow
metadata{ name, version, description? }. name: at most 128 characters. version: a semantic version string; quote it ("1.0.0").
descriptionOptional text.
inputsOptional { schema }: the run's static inputs must match it.
outputSchemaOptional: the output of a succeeded terminal must match it.
initialThe first state; not a terminal.
initialInputOptional JSON template (bindings: inputs, kv); the first state's input. Default null.
limitsOptional { maxNodeExecutions?, timeoutSeconds?, onExceeded? }. maxNodeExecutions: 1 to 10,000 per run, default 1,000. timeoutSeconds: the run's deadline, 1 to 2,592,000 seconds from when it begins; pause does not stop it. onExceeded: expired (the only policy).
catchAllOptional state that takes a runtime error no route takes; not initial; at most once per run.
schemasNamed JSON Schema 2020-12 documents; refer to one as { $ref: "#/schemas/Name" }.
contractsName@N: { schema, description?, response?: { schema, description? } }. A request's contract needs response.
states1 to 100 states, body states included.

Any schema field takes a $ref to schemas or an inline schema.

Bindings

A binding is one whole string "${root.path}" or "${root.path ?? <JSON literal>}". Roots: inputs, input, kv, runtime (runtime.error), branch (branch.item, branch.index; branch.name in named branches; branch states only). Path segments: .name, [index], ["any key"]. A template is any JSON value whose strings may be bindings.

A template is a YAML value: an object is a map ({ fact: "..." }), not JSON text in quotes ('{"fact": "..."}' is one string). A template with no binding is checked against its contract or inputSchema when the draft is saved (WORKFLOW_STATE_INPUT_INVALID); JSON written as text where an object or array is expected gets the warning WORKFLOW_INPUT_JSON_TEXT. A state with no input: whose closed inputSchema refuses a property that the outputSchema of the state before it declares (a wait passes its input on), or needs one it lacks, gets the warning WORKFLOW_INPUT_MISMATCH.

States

Every state except a terminal has transition: { next: { <route>: <state> } }. A route is an outcome of the state, a runtime error code or failure (any runtime error that has no route of its own). All states take an optional description.

script

FieldRule
sourceRequired. Node ES module text.
runtimeOptional; node only.
timeoutSeconds1 to 3,600; default 300.
inputOptional template; default: the value that arrived.
inputSchema, outputSchemaOptional.
outcomesOptional list; default: its routes that are not runtime routes.

Output: the setResult output. Errors: invalid_input, invalid_output (undeclared outcome, non-JSON or mismatched output), execution_failed (non-zero exit without a result), timed_out, cancelled.

wait

FieldRule
seconds1 to 86,400, or one binding (checked at entry: invalid_input). Required unless at.
atInstead of seconds: { minute, hour?, day_of_week? (0-6, Sunday 0) or day_of_month? (1-31), tz }; a day needs hour, and minute alone is every hour. Waits until the next such time in the IANA zone tz (daylight saving included), decided at entry.
inputOptional template.

Outcome: elapsed (route required). Output: its input.

messaging, mode receive

FieldRule
contractRequired. A root contract.
fromOptional: { parent: true }, a session id, or { sessionId } (may be a binding). Without it, any permitted sender.
correlateOptional template object; a message's correlation must equal it.
waitOptional { seconds } (as a wait state's seconds): the receive races a durable timer.
inputOptional template.

Outcomes: received (output: the message payload) and, with wait, elapsed (output: its input). Routes for both are required. A message given before the state starts is taken too, in the order the run accepted it.

messaging, mode send

FieldRule
contractRequired.
recipientRequired: { parent: true }, a session id, or { sessionId } (may be a binding).
correlateOptional template object.
inputOptional template; the message. At most 16 KB, valid for the contract.

Outcome: sent (output: the delivery receipt): the recipient accepted the message. The next state gets this receipt, not the message. That does not mean it was read. An agent session gets it in its queue (at least once). A workflow gets it as typed input (once). Errors: unavailable, forbidden, unsupported_contract, delivery_failed, invalid_input.

messaging, mode request

FieldRule
contractRequired. Its contract declares response.
recipientRequired, as for send.
timeoutSecondsRequired. 1 to 86,400, or one binding.
correlateOptional template object.
inputOptional template; the request payload.

Outcomes: responded (output: the response, valid for the response schema) and declined (output: { reason }). The next state gets only that output: nothing from before the request. Routes for both are required. The deadline is timed_out. The recipient answers with respond_session_request; session is not an answer.

agent

FieldRule
invokeRequired. { prompt: <text, at most 32 KB> } or { agent: { name, package?, version?, interface? } }; version and interface need package.
timeoutSecondsRequired. 1 to 86,400, or one binding.
inputOptional template; checked against inputSchema.
inputSchema, outputSchemaOptional.
outcomesOptional list of business outcomes; default: its routes that are not runtime routes.
sessionOptional. continue (default) or new. In a parallel body (For each or branch) only new, its default there. (session is no longer a field.)
toolsOptional. none or tool names: all the agent and its sub-agents get (plus complete_workflow_node).

Output: the agent's validated output. The agent may report needs_input or execution_failed. The workflow decides timed_out, invalid_output (three invalid completions), unavailable, forbidden and cancelled.

session: continue (the default) keeps one agent session across the state's visits in a Workflow: each later visit arrives as "cycle N" with the input, the variables now, which changed, and the previous result. The step remembers earlier cycles (no repeats, incremental work); its context grows, so it costs more. Use session: new (a fresh agent session each visit: clean, cheaper, no drift) only when the person asks for it, or the visits are independent and the person wants that. In a For each or a parallel branch each visit has its own agent session: new is the default there and continue is refused. Another Workflow (Run again) starts new agent sessions. Each completion gives node_execution_id from its prompt. Session lifecycle: the time limit is per visit; the agent session ends with the Workflow (a stop ends an idle one at once). An agent session that ended on its own is replaced, and the prompt says so.

interface: <name>@<version> (for example review_change@1) names the workflow interface its package agent exports. ps_list_agents lists it as the entry's workflowInterface (ref, outcomes, inputSchema, outputSchema, digest); set package to the entry's namespace. The state must declare outputSchema. At publication and at start, the state's outcomes and outputSchema must equal the interface's, and inputSchema too when the interface has one. Copy each interface schema into schemas unchanged (no $ref inside the copy) and refer to it from the state; a stricter or looser schema does not match. A mismatch refuses with CONTRACT_MISMATCH and its problems; a match pins the interface's digest with the package revision.

parallel

FieldRule
forEachOne binding that gives a list, or a list; at most 64 items.
branchesInstead of forEach and body: { <name>: { initial, states, input? } }, 1 to 64, each its own graph from its initial, with its input (default: the value that arrived). concurrency defaults to their number; above 16, set it.
concurrency1 to 16; default 1.
joinOptional: all (default; all_required is the same) or { first: k }, k from 1 to 64 and at most the items of a literal list.
failFastOptional boolean; default false. Cancels the other branches once the join can no longer succeed.
timeoutSecondsOptional: the state's own time limit, 1 to 86400 or one binding. Needs a timed_out route.
inputSchemaOptional: checks the whole list.
outputSchemaOptional: checks the joined output.
bodyWith forEach: { initial, states }. No parallel state inside.

Outcomes: joined and blocked. Routes for both are required.

  • joined with all: the branch outputs in list order. With { first: k }: [{ index, output }] of the first k successes, in the order the store saved them (ties: lower index first); the other branches are cancelled or not started. Named branches: { <name>: output }, the winners only; a report's branches add name. Without timeoutSeconds, a named branch with an agent state, or a receive with no wait, warns WORKFLOW_BRANCH_UNBOUNDED.
  • blocked: k successes can no longer happen (with { first: k } and fewer than k items, at once). Output: { joined: false, timedOut, total, needed, succeeded, failFast, branches: [{ index, ended, nodeExecutionId, outcome, resultKind, output or error, cancelledBy?, late? }] }. ended is terminal, error, cancelled, not_started or finished (its last step's result was saved, and kept, but its next step never started). cancelledBy is failFast, join or timeout. late marks a success saved after the time limit. A report too large to store drops every output and error and adds truncated: true.
  • With timeoutSeconds: a success counts only when it was saved at or before the time limit. A branch step whose own deadline equals the time limit ends just after it, so it does not count. When the time limit passes with k such successes, the state still joins. With fewer, it ends with the runtime error timed_out, whose details is the same report with timedOut: true; if k could already no longer happen then, it is blocked with timedOut: true instead.
  • outputSchema checks only the joined output, never a report.
  • Worker slots: each running script holds one of the worker's slots (PILOTSWARM_WORKER_CONCURRENCY; the duroxide default is 2) for its whole run, and the controller needs one too: keep concurrency below the slot count, with room to spare. Stopping a script is best-effort.

terminal

FieldRule
outcomeRequired: succeeded, blocked, failed or cancelled.
outputOptional template; default null.
summaryOptional text.
outputSchemaOptional, in addition to the root outputSchema for succeeded.

Runtime error codes

invalid_input, invalid_output, timed_out, cancelled, forbidden, unavailable, unsupported_contract, delivery_failed, budget_exceeded, needs_input, execution_failed. On an error route, input and runtime.error are the envelope { code, message, details? }.

Semantics

What the engine guarantees. Do not rely on more.

  • Durable. The store keeps the run, each visit (input, outcome, output), the variables, accepted messages and requests; the controller's history keeps its place. After a worker restart the run goes on where it was.
  • Order. The run starts at initial. Outside a parallel state one state runs at a time: its outcome, or its runtime error, takes one route, and the next state gets its output (or the error envelope). Every visit counts toward maxNodeExecutions; at the limit the run fails (limit_exceeded).
  • One result per visit. The first result stored stands. Nothing is undone: side effects that happened stay.
EffectOn a retry or a worker restart
scriptRuns again from its start (context.attempt above 1), tool calls too: make it safe to repeat.
agentKeeps the same agent session; its prompt is not given twice. The first accepted complete_workflow_node decides; later ones are refused.
sendAn agent session may get it twice (a repeat is dropped while its id is recent). A workflow takes it once.
requestReaches the responder at least once, under one id. The first answer decides; none after the deadline.
receiveTakes each message once, in the order the run accepted it.
waitElapses once, by the store's clock.
  • Timers. Every deadline (a wait, a receive's wait, a request, an agent or parallel timeoutSeconds, the run's limits.timeoutSeconds) is a durable timer, fixed when its state or run starts. Restarts and pauses do not stop it.
  • Joins. forEach is read once, at entry. At most concurrency branches run at once. Only successes stored in time count. A cancelled branch's running script may still finish (stopping is best-effort), but its result does not count.
  • Pause. No state starts and no result is routed until resume. Started work finishes and keeps its result; a state whose deadline passes meanwhile is routed after the resume.
  • Stop. Nothing new starts; started work settles. The run ends stopped when nothing is pending, or at the end of its grace, cancelling the rest.
  • Cancel, delete. The run ends when it is accepted: pending visits are cancelled, then scripts are stopped and agent sessions ended. A delete tells no one.
  • Run deadline. Pending work is cancelled and the run fails timed_out, paused or not.
  • Failure. A runtime error takes its code's route, else failure, else catchAll (once per run; a later route to it fails the run), else the run fails. In a branch it ends the branch without success. A run whose controller stopped shows needsRecovery; recover ends it failed.
  • Versions. A Workflow runs the revision it started with, with its named agents' pinned versions; a later save never changes it. To run a change, start the new revision as another Workflow. Only its variables change (set_vars); a step reads them as of its start.

Not supported: do not write

transition.function, transition.delaySeconds (use a wait state), join states, a parallel state in a body, inputSchema or outputSchema on a receive, parentNotification, the request field request and the route timeout, and text around a binding.

Tools

For every argument of the Workflow tools and the refusals you can fix, call load_skill with name workflow-tools. Use read_workflow, not list_sessions, for a Workflow's status.

Example: review fan-out with bounded rework

# example: change-review
apiVersion: pilotswarm.dev/v1
kind: Workflow
metadata: { name: change-review, version: "1.0.0" }
description: Reviews pinned changes in parallel with bounded rework, then asks the parent to approve the reviewed set.
inputs:
  schema: { $ref: "#/schemas/ReviewInputs" }
outputSchema: { $ref: "#/schemas/Decision" }
initial: review_changes
initialInput: "${inputs.changes}"
schemas:
  Change:
    type: object
    additionalProperties: false
    required: [workId, head, authorSessionId, round]
    properties:
      workId: { type: string, minLength: 1 }
      head: { type: string, minLength: 40, maxLength: 40 }
      authorSessionId: { type: string, minLength: 1 }
      round: { type: integer, minimum: 1, maximum: 3 }
  ReviewInputs:
    type: object
    additionalProperties: false
    required: [changes]
    properties:
      changes: { type: array, minItems: 1, maxItems: 16, items: { $ref: "#/schemas/Change" } }
  ReviewResult:
    type: object
    additionalProperties: false
    required: [workId, head, findings]
    properties:
      workId: { type: string }
      head: { type: string }
      findings: { type: array, items: { type: string } }
  NewHead:
    type: object
    additionalProperties: false
    required: [head]
    properties:
      head: { type: string, minLength: 40, maxLength: 40 }
  ReviewedSet:
    type: array
    items: { $ref: "#/schemas/ReviewResult" }
  Decision:
    type: object
    additionalProperties: false
    required: [approved]
    properties:
      approved: { type: boolean }
      note: { type: string }
contracts:
  Rework@1:
    schema: { $ref: "#/schemas/ReviewResult" }
    response: { schema: { $ref: "#/schemas/NewHead" } }
  Approve@1:
    schema: { $ref: "#/schemas/ReviewedSet" }
    response: { schema: { $ref: "#/schemas/Decision" } }
states:
  review_changes:
    type: parallel
    forEach: "${input}"
    concurrency: 4
    outputSchema: { $ref: "#/schemas/ReviewedSet" }
    body:
      initial: review
      states:
        review:
          type: agent
          invoke: { agent: { name: code-reviewer, package: review-kit, version: "1.2.0" } }
          inputSchema: { $ref: "#/schemas/Change" }
          outputSchema: { $ref: "#/schemas/ReviewResult" }
          outcomes: [accepted, changes_required]
          timeoutSeconds: 900
          transition:
            next: { accepted: accepted, changes_required: ask_rework, invalid_input: blocked, needs_input: blocked, failure: blocked }
        ask_rework:
          type: messaging
          mode: request
          contract: Rework@1
          recipient: { sessionId: "${branch.item.authorSessionId}" }
          timeoutSeconds: 3600
          transition:
            next: { responded: next_round, declined: blocked, failure: blocked }
        next_round:
          type: script
          timeoutSeconds: 120
          outcomes: [verified]
          source: |
            const item = context.branch.item;
            const checked = await callTool("verify_review_round", { workId: item.workId, head: context.input.head });
            await setResult("verified", { ...item, head: context.input.head, round: checked.round });
          transition:
            next: { verified: review, failure: blocked }
        accepted:
          type: terminal
          outcome: succeeded
          output: "${input}"
        blocked:
          type: terminal
          outcome: blocked
          output: "${input}"
    transition:
      next: { joined: approve, blocked: stuck, failure: failed }
  approve:
    type: messaging
    mode: request
    contract: Approve@1
    recipient: { parent: true }
    timeoutSeconds: 86400
    transition:
      next: { responded: decide, declined: rejected, timed_out: rejected, failure: failed }
  decide:
    type: script
    outcomes: [approved, rejected]
    source: |
      await setResult(context.input.approved ? "approved" : "rejected", context.input);
    transition:
      next: { approved: done, rejected: rejected, failure: failed }
  done:
    type: terminal
    outcome: succeeded
    output: "${input}"
  rejected:
    type: terminal
    outcome: blocked
    output: "${input}"
  stuck:
    type: terminal
    outcome: blocked
    output: "${input}"
  failed:
    type: terminal
    outcome: failed
    output: "${runtime.error}"

code-reviewer in review-kit and verify_review_round stand for an agent and a tool of your own. The rework loop is bounded by the schema: a fourth round fails review's input check (invalid_input) and ends the branch blocked; a blocked join ends at stuck with every branch's result.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.