# 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](../reference/workflow-schema.md). For operating a run once it's written, see [Running Workflows](../guides/run-workflows.md). ## 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](../reference/workflow-schema.md#github-shaped-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/.yml` and validate either source with `akm lint`: ```sh 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 ```markdown --- 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` 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](../reference/workflow-schema.md#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**: ```markdown --- 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: ```yaml - 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: ```yaml - 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](../reference/workflow-schema.md#the-childs-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](../reference/workflow-schema.md#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](../reference/workflow-schema.md#the-reference-grammar). - **Mismatched or missing step headings.** Every `## ` 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](#deterministic-steps-run-a-command-gate-on-it), 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`. ```yaml - 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](../reference/workflow-schema.md#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: ```yaml - 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..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](../reference/workflow-schema.md#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](run-workflows.md#security-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 1. **Lint the structure.** ```sh akm lint --type workflows ``` This catches the body-rule violations above, plus every static reference check (unknown step, unknown param, bad path, backward route). 2. **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: ```sh akm workflow run workflows/my-release --version 1.2.3 ``` 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: ```sh akm workflow status --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](run-workflows.md#check-status). 4. **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](../reference/workflow-schema.md#gates-and-verification)), so this is worth confirming once per workflow rather than assuming. ## Composing a task with typed inputs A `uses: tasks/` step in the GitHub-shaped YAML format can bind a task source v4 target's declared `inputs:` through `with:`. Given this task: ```yaml # 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: ```yaml # 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..output(.)*"}` and `{from: "params."}` 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/` target gets a `## Task inputs` block appended to its prompt; a `run:` shell or `scripts/` 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: ```sh 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 ``` ## See also - [Workflow Schema](../reference/workflow-schema.md) — exact frontmatter, refs, gates, and outputs syntax - [Running Workflows](run-workflows.md) — start, inspect, resume, and abandon a run - [Architecture: The Workflow Engine](../architecture/workflow-engine.md) — persistence, dispatch, and resume internals - [CLI Reference](../reference/cli.md) — full flag documentation for `workflow create`, `run`, and `lint`