Author's Guide: Writing Workflows

This guide walks through writing and testing a workflow definition: choosing a source format, the Markdown structure, a minimal complete example, common authoring mistakes, and how to verify gates and outputs before you publish. It assumes you already know what a workflow is; for the exhaustive, exact-syntax reference — every frontmatter key, the reference grammar, gates, and outputs — see Workflow Schema. For operating a run once it's written, see Running Workflows.

Start from the template

Authors can choose peer Markdown or GitHub-shaped YAML sources. Markdown is the full AKM authoring format: OKF-conformant frontmatter carries the orchestration graph and its body carries instructions and gate rubrics. GitHub-shaped YAML is a strict local subset for interoperability. Read the authoritative YAML subset before translating an Actions-shaped file; AKM does not accept arbitrary GitHub semantics. .yaml is not recognized—use .yml.

Use akm workflow create --print to print a valid Markdown starter, then edit it and register it with akm workflow create. Author a YAML source directly under workflows/<name>.yml and validate either source with akm lint:

akm workflow create my-release --print   # Print the template, without writing
akm workflow create my-release --from ./my-release.md
akm lint --type workflows                # Check for structural errors before using it

Both formats compile to source IR version 1. Choose Markdown for maps, routes, gates, typed artifacts, and prose-rich agent instructions. Choose the bounded YAML subset for a single local self-hosted job made of token-safe run and supported local uses steps.

A minimal complete example

---
type: workflow
description: Ship a tagged release to production
params:
  version: { type: string, description: The semver version string to release }
steps:
  - id: validate
  - id: build
    inputs: [steps.validate.output]
---

# Ship Release

## validate

Check that the `version` parameter follows semver and the tag does not
already exist.

### gate

- `git tag v<version>` does not already exist.
- The version string matches `^\d+\.\d+\.\d+$`.

## build

Run `npm run build && npm test`, using the validation from `validate`,
attached to this unit as input. Fix any failures before proceeding.

Walking through it: validate and build are both bare unit steps — neither declares unit:, map:, or route:, so each is "still a unit step," the minimal declaration. build names steps.validate.output in inputs:, so the engine attaches validate's result to build's dispatched context, and build's own re-dispatch on a resumed run is keyed to that exact slice — not the whole run. validate has a ### gate; build does not, so build completes as soon as its unit succeeds, with no verification pass.

For a richer example — fan-out with map, route-based branching, retries, and a run budget — see Workflow Schema: Richer example.

Deterministic steps: run a command, gate on it

Not every step needs a model. Running the test suite, building, linting, or invoking a script is deterministic work: there is exactly one right answer and the command already knows it. A step whose unit: declares exec: runs that command directly — no LLM, no agent, no tokens, no nondeterminism.

The canonical shape is a test step that gates the rest of the run:

---
type: workflow
description: Fix a failing test, then verify the suite is green
params:
  failure: { type: string, description: The failing test name or error }
steps:
  - id: fix
  - id: test
    inputs: [steps.fix.output]
    unit:
      exec:
        command: ["bun", "run", "test:unit"]
      timeout: "10m"
      retry: { max: 1, on: [timeout] }
  - id: report
    inputs: [steps.test.output]
---

# Fix and Verify

## fix

Find the cause of the failure described in the run parameters and fix it.
Explain what you changed and why.

## test

Run the unit test suite. This step is deterministic: the command's exit code
decides whether the run continues.

## report

Summarize the fix and the test results attached to this unit.

What this buys you:

The suite is the gate. test uses the default on_error: fail, so a non-zero exit fails the unit with non_zero_exit, fails the step, and stops the run before report ever dispatches. No judge, no rubric, no prompt — the exit code is the verdict.
The output is real. steps.test.output is the command's stdout (trailing newlines stripped), so report receives the actual test output rather than a model's recollection of it.
It costs nothing. No tokens, no latency beyond the command itself, and the same input always produces the same dispatch.
It resumes correctly. A completed exec unit is journaled like any other; a resumed run reuses the row instead of re-running the suite.

Getting a typed result instead of raw text

If the command can print JSON, declare an output schema on the unit and the step artifact becomes a validated structure:

  - id: test
    unit:
      exec:
        command: ["bun", "run", "test:unit", "--reporter=json"]
      output:
        type: object
        required: [passed, failed]
        properties:
          passed: { type: number }
          failed: { type: number }

stdout must then be exactly one JSON value — no log noise around it — and downstream steps can address steps.test.output.failed.

What the command can see

The child does not inherit your environment. It starts empty and gets a small default allowlist — PATH, HOME, the locale/temp/identity variables, and the Windows essentials (SystemRoot, COMSPEC, PATHEXT, …) that process creation itself needs — then your env: bindings, then the AKM_* context variables. Ordinary commands (bun, git, make, cargo) work unchanged; an unrelated SOME_OTHER_SERVICE_TOKEN sitting in the shell that ran akm workflow run does not reach them.

Widen it only by naming what the unit needs:

  - id: build
    unit:
      env: [env/build]
      exec:
        command: ["cargo", "build", "--release"]
        pass_env: [CARGO_HOME, SCCACHE_DIR]   # a few extra names

pass_env: is for a per-machine variable an env: binding cannot express (an env asset stores a committed value; CARGO_HOME differs per build agent). Secrets and fixed values belong in exact named env: bindings: those values are redacted out of everything journaled, and pass_env: values are not.

Workflow starts freeze the durable plan v4 family's current executable format (irVersion: 5), which rejects inherit_env instead of persisting an unbounded ambient environment. Pre-irVersion-5 stored plans do not execute; start a new run after updating the source.

Named bindings and pass_env: are part of the unit's input hash, so changing either re-runs the command instead of reusing a row recorded under another scope.

Full list of allowlisted names: Workflow Schema: The child's environment is an allowlist.

Things to get right

command: is an argv array, not a shell string. ["bun", "run", "test"], never "bun run test". Nothing is shell-parsed, which is what makes it safe; if you truly need a pipeline, write ["bash", "-lc", "a | b"] and own that choice explicitly.
No interpolation. The argv is frozen. A map step's item reaches the command as AKM_ITEM (canonical JSON) and the run params as AKM_PARAMS — read them from the environment, do not try to splice them into command:.
Secrets go in env:, never in command:. command: is stored verbatim in the frozen plan; env: bindings are carried by name and their values are redacted out of everything journaled.
Long commands need a timeout:. An exec unit defaults to 10 minutes. Use timeout: "30m" for a slow suite, or timeout: "none" only when you really mean unbounded.
Don't assume your shell's environment. The child gets an allowlist, not an inheritance. If a command fails with "not found" or reads a missing toolchain variable, name it in pass_env:; use a named env: binding for a fixed or secret value. The durable v4 family (irVersion: 5) deliberately has no whole-process fallback.
A very chatty command still passes; its artifact just says so. akm retains 8 MiB of stdout and 8 MiB of stderr. Past that it keeps draining and discards, so the command runs to completion and its exit code decides the step. The artifact is then the retained head with a __akm_exec_output_truncated__ block appended, so nothing downstream can mistake it for the whole output. The one case that still fails is a unit with a declared output: schema — a truncated prefix is not one JSON value, so there is nothing to validate.
Bulk data reaches a command as a path, not as an environment variable. AKM_INPUTS / AKM_PARAMS / AKM_ITEM are bounded by what process creation accepts on the current platform (96 KiB per variable on Linux/macOS, 32 767 bytes on Windows). Over that, the unit fails exec_context_too_large before anything is spawned. If a workflow must also run on Windows, keep context under the Windows number — akm will not enforce it on your Linux box, but a Windows runner will.

Full reference: Workflow Schema: Exec (shell) units.

Common authoring mistakes

Templating prose. There is no ${{ … }}/{{ … }} interpolation anywhere in a workflow body. Write instructions in plain language that refer to attached context — "using the intake step's artifact attached to this unit" — never by splicing a value into the string. See Workflow Schema: The reference grammar.
Mismatched or missing step headings. Every ## <step-id> must match a step declared in frontmatter exactly — no titles, no Step:/Step ID: lines, no # Workflow: prefix on the H1.
A unit/map step with no body section. Its instructions (or, for a map step, its per-item template) are required — a route-only step is the one case a body section is optional.
Misplaced or misspelled ### gate. It is the format's single reserved marker, and it must be a ### sub-heading inside the step's own section. An empty ### gate section is the same as omitting it — no verification runs.
Referencing an item outside a map unit. item/item_index are not part of the reference language anywhere — they only arrive as attached context inside that map step's own unit template.
Backward routes. Every route target (when.step, default) must be a step declared later in the workflow; "loop back until it passes" is a bounded ### gate on the step doing the work, not a route back to an earlier step.
Referencing an unknown step or param. akm lint --type workflows checks every bare reference statically (unknown step, unknown param, bad path) — run it before you rely on a workflow working.
Writing exec.command as a shell string. command: "bun run test" is rejected; it must be an argv array (["bun", "run", "test"]). Nothing is ever shell-parsed, so metacharacters inside an argument stay literal.
Expecting an exec command to inherit your environment. It gets a default allowlist (PATH, HOME, locale/temp/identity, the Windows essentials) plus your env: bindings and the AKM_* context — nothing else. Widen it with exec.pass_env: (a few non-secret names). pass_env lives inside exec:; the unit-level env: key is a list of exact env asset binding refs. A new v4 start rejects inherit_env.
Asking a model to do deterministic work. "Run the test suite and tell me if it passed" is an exec step, not a prompt.

Typing what a step returns

A step's output: (and each params: entry) is a JSON Schema, and the engine validates the step's artifact against it before the step can complete. The runtime enforces a bounded subset of JSON Schema — anything outside it is an authoring error at akm lint, never a silent no-op, because a gate depending on a schema that constrains nothing is worse than a loud failure.

Enforced: type, enum, properties, required, items, additionalProperties: false, minItems, maxItems, minLength, maxLength, minimum, maximum, and the combinators allOf, anyOf, oneOf, not.

  - id: release
    output:
      type: object
      required: [version, verdict]
      additionalProperties: false
      properties:
        version: { type: string, minLength: 1 }
        verdict: { type: string, enum: [pass, fail] }
        detail:
          oneOf:
            - { type: string, minLength: 1 }
            - { type: "null" }

Outside the subset (each fails lint with the keyword named, its line, and a suggested replacement where one exists): $ref/$defs — inline the schema instead, since nothing resolves references; const — use a single-value enum; pattern and format — no regex or string-format constraint is evaluated at run time, so list the allowed values with enum when you can, bound the size with minLength/maxLength, and otherwise check the shape in the step's ### gate rubric, which can also say why a value is wrong; patternProperties, if/then/else, uniqueItems, multipleOf, tuple-form items, and schema-form additionalProperties (only additionalProperties: false is enforced). Annotation keywords — description, title, default, examples — always pass through untouched, and documenting each property is worth the keystrokes.

If lint reports a very broken workflow, note that its errors are sorted by line, so fix from the top and re-run — the later ones are usually fallout from the first.

Choosing engines and models

Set defaults.engine/defaults.model (or per-unit unit.engine/unit.model) rather than hardcoding an exact model id, so the workflow stays harness-agnostic. Reference semantic aliases — fast, balanced, reasoning, or aliases defined in the installed/user models.json files — in model: fields; see Workflow Schema: Model references for the exact resolution order and config shape.

Point reasoning work at a capable model and keep high-volume fan-out units on fast/balanced. The richer example's review map step is a good template: reasoning on the per-item reviewer, balanced as the run default for everything else.

Fan-out width

A map step runs its items in parallel by default — 4 at a time as of 0.9.1. (Earlier versions defaulted to 1, so a fan-out over 500 items crawled through them one by one unless you said otherwise.) Map units are independent by construction, so parallel is the honest default; the number is a modest 4 rather than "whatever the machine can take" so it stays predictable across the machines a workflow gets shared with.

Say so explicitly when the default is wrong for a step:

  - id: review
    map:
      over: steps.discover.output.files
      concurrency: 1     # serial — this step's units are NOT independent

concurrency: 1 is a genuine opt-out and always wins. Reach for it when the units touch a shared resource, when their side effects must happen in list order, or when they hit an external service you must not burst. To change the default for every workflow on a machine instead — including restoring the old serial behavior wholesale — set akm config set workflow.defaultMapConcurrency 1.

The declared width is a ceiling, not a promise. Three other limits clamp it and the smallest wins: workflow.maxConcurrency, the selected engine's engines.<name>.concurrency, and the host's CPU cap. The engine limit is the one that surprises people: an LLM engine pointed at localhost defaults to 1, because local model servers hold a single loaded model and fall over under concurrent requests — so a map against a local model stays serial no matter what the step declares, until you raise that engine's own concurrency. Remote LLM endpoints default to 4. See Workflow Schema: Fan-out and concurrency for the full table.

All of it is frozen into the run when it starts, so an in-flight or resumed run keeps the widths it began with even if you edit config or upgrade akm.

A workflow that fans out is authorizing N parallel agents, not one — the same trust model described in Running Workflows: workflow sources are executed code applies with multiplied blast radius. Give the workflow explicit safety and parameter metadata (document every params entry, keep destructive steps described plainly in the body) so a reader — human or agent — can judge that blast radius before running it.

Verify before you publish

Lint the structure.
```
akm lint --type workflows
```
This catches the body-rule violations above, plus every static reference check (unknown step, unknown param, bad path, backward route).
Run it for real. A dry inspection of the markdown doesn't tell you whether a gate actually rejects bad output or an output schema actually matches what units return. Run the workflow against representative params:
```
akm workflow run workflows/my-release --version 1.2.3
```
Inspect the evidence. Check that each step's promoted artifact is what you expect, and that a gate's rubric is judging that artifact, not engine prose:
```
akm workflow status <run-id> --units
```
--units shows per-unit diagnostics (status, failure_reason, raw result/error text) without polluting the deterministic artifact a gate judges — see Running Workflows: Check status.
Deliberately break a gate once. Run the workflow with params you expect to fail validation, and confirm the gate actually rejects rather than silently passing — a missing workflow.judgeEngine or a malformed verdict rejects the gate rather than bypassing it (see Workflow Schema: Gates and verification), so this is worth confirming once per workflow rather than assuming.

Composing a task with typed inputs

A uses: tasks/<ref> step in the GitHub-shaped YAML format can bind a task source v4 target's declared inputs: through with:. Given this task:

# tasks/ticket-review.yml
version: 4
name: Ticket review
inputs:
  ticket:
    type: string
    required: true
  scope:
    type: string
    enum: [changed, all]
    default: changed
uses: commands/review

a workflow step can bind ticket from an EARLIER step's output, and override scope with a literal:

# workflows/nightly.yml
name: Nightly review
on:
  workflow_dispatch: {}
jobs:
  main:
    runs-on: [self-hosted]
    steps:
      - id: pick
        run: echo T-42
      - id: dispatch
        uses: tasks/ticket-review
        with:
          ticket: { from: "steps.pick.output" }
          scope: all

{from: "steps.<id>.output(.<segment>)*"} and {from: "params.<name>"} are the only two reference roots; anything else, or an object carrying from plus any other key, is INPUT_BINDING_INVALID at freeze — never silently reinterpreted as a literal. pick's output is resolved just before the dispatch unit dispatches, then validated against ticket's declared schema; a literal (like scope: all here) is validated at freeze instead, before the plan is ever published.

The composed target — commands/review here — receives the resolved bindings on whichever delivery surface matches its kind: an akm/command/commands/<ref> target gets a ## Task inputs block appended to its prompt; a run: shell or scripts/<ref> target gets one AKM_TASK_INPUTS environment variable (canonical JSON of the resolved bindings). Inspect exactly what each step's with: would deliver, without running anything, with akm workflow plan workflows/nightly --format json — its per-step inputBindings show dispatch's scope as the literal all and ticket as the unresolved reference steps.pick.output, the same shape freezing a real run would produce. akm task explain is not a substitute here: it only reflects a task's OWN CLI flags, declared defaults, and schedule[].inputs — it never reads a workflow step's with: binding at all, so pointing it at tasks/ticket-review prints scope's task-level default (changed), not the all this step actually sends.

Troubleshooting

Every workflow run needs a selected engine. Freezing resolves an engine for each unit. With no defaults.engine, akm falls back to a config-free opencode-sdk engine — provider, model, and auth come from opencode's own configuration — and announces it once in the run's warnings. The fallback needs the opencode binary on PATH: the bundled @opencode-ai/sdk package is an HTTP client only and spawns opencode serve to have something to talk to, so installing the npm package alone is not enough. With no binary, freezing fails with INVALID_CONFIG_FILE and exit 78.

A workflow with a non-empty ### gate additionally requires workflow.judgeEngine to name a configured LLM or agent engine — the gate judge is not covered by the fallback.

akm setup normally selects a default execution engine. On a bare container or CI image, either install opencode and let the fallback apply, or choose an engine explicitly:

npm i -g opencode-ai           # fallback route: puts `opencode` on PATH
# ...or pick an engine yourself:
akm config set engines.claude '{"kind":"agent","platform":"claude"}'
akm config set defaults.engine claude