Authoring Nika workflows

Nika turns repeatable AI work into files: one .nika.yaml, four verbs, audited before it runs. You author the file; nika check is the oracle; the human runs it.

The loop (always)

1. Start from a template or example, never from scratch:

nika examples list · nika examples show <slug> · nika new --from <template> <file>.nika.yaml

1. Write the file. Envelope is always nika: v1 +

workflow: <kebab-id> + tasks:. Pick models and builtins from the embedded catalogs — nika catalog (providers · models · capabilities · which env var each needs) and nika tools (the nika:* builtins an invoke reaches without MCP); before a run, nika inspect <file> shows the anatomy: tasks · waves · the cost floor.

1. Check it: nika check <file> (exit 0 = clean · 2 = findings),

then nika check --native-strict <file> — it fails on any native-first hint (an exec: a builtin covers).

1. Repair from the diagnostics — they name the exact task, reference

and fix. Unknown code? nika explain NIKA-XXXX.

1. Repeat 3–4 until clean. Never hand a file to the human that does

not pass nika check — and pass --native-strict too, unless every remaining exec: is in the exec ledger (below).

1. The human (or CI) runs it: nika run <file>. Preview offline with

--model mock/echo; run locally with --model ollama/<model>. Inputs ride --var key=value (repeatable · unknown keys refused); a run paused on a nika:prompt resumes with nika run <file> --resume <trace> --answer <task>=<value> (confirm gates take booleans: --answer approve=true).

1. Pin it for CI: nika test <file> --update writes

<file>.golden.json from an offline mock run; nika test <file> replays and compares — deterministic, zero keys.

1. Prove a run that mattered: every run writes a hash-chained

journal to .nika/traces/ — nika trace verify <trace> checks the chain (tamper-evidence), nika trace show <trace> reads the card. Cite the trace, never a memory of the run.

Cost honesty (never hide unknown spend)

• nika check prints the cost ceiling BEFORE any token: ≤ $X is a

ceiling · ≥ $X FLOOR means at least one task is unbounded — name the reason (a missing max_tokens, an uncataloged model, an expression fan-out), never round it to $0.

• A local model (ollama/…) is unpriced compute, not « free » —

say "unpriced", never "$0" or "free".

• A spend cap rides the run: nika run <file> --max-cost-usd <n>

blocks BEFORE the call that would cross the cap.

• nika explain <file> narrates all of this (waves · cost · touches ·

how to run) — use it before handing a workflow to a human.

The four verbs (exactly one per task)

• infer: — an LLM call (prompt, schema? for typed output,

max_tokens?)

• exec: — a shell command (command, capture: text|structured) ·

last resort: run the native-first interrogation first (below)

• invoke: — a builtin or MCP tool (tool, args) · HTTP fetch is

tool: "nika:fetch", a tool, not a verb

• agent: — a bounded multi-turn loop (prompt, tools allowlist,

max_turns, max_tokens_total)

Native-first (the law)

The order is invoke: nika:* → invoke: mcp:<server>/<tool> → exec:. Before writing ANY exec:, answer in your head:

1. Which builtin replaces it? nika tools --json is the catalog.

HTTP (curl/wget/helper fetch) → nika:fetch · uploads → multipart: · site crawls → traverse: · file plumbing (cat/tee/cp/mkdir) → nika:read/nika:write (create_dirs: true) · JSON shaping (jq/sed) → nika:jq (or an output: binding) · in-place edits → nika:edit · image/speech provider calls → nika:image_generate/nika:tts_generate · image styling (ImageMagick convert / PIL filters / dither scripts) → nika:image_fx (deterministic — same input+args = same bytes, the artifact sha256 joins the trace chain).

1. Which MCP tool replaces it? A product API deserves an MCP

server, never a helper script.

1. Neither? Name the exact gap — then exec: is legitimate

(build tools · git · a product CLI with no MCP surface yet) and goes in the ledger.

Never write a helper script (node bin/helper.mjs …) that wraps HTTP/files/JSON — that is native-first/005, the exact failure class this law exists for.

Exec ledger (mandatory when any exec remains)

Every surviving exec: gets a row in the workflow's header comment:

# EXEC LEDGER ·
# | task | command | why no native path | unlock that removes it |

--native-strict + a complete ledger = a reviewable workflow.

Discipline

• References: ${{ tasks.<id>.output }} · ${{ vars.x }} ·

${{ env.KEY }} · ${{ secrets.X }} (never inline a credential).

• A task that reads another task's output MUST declare it in

depends_on: [<id>].

• Models are provider/name (ollama/llama3.2:3b local-first ·

mock/echo offline preview).

• Timeouts are quoted Go-durations (timeout: "7m") — give local

providers ≥300s: thinking models routinely think past 30s.

• Declare the blast radius: nika check --infer-permits <file> prints

the tightest permits: block — paste it in (default-deny from then on).

• Structured output: give infer: a schema:; add

additionalProperties: false for a deterministic shape.

• Auth rides headers: { x-api-key: "${{ secrets.KEY }}" } (masked ·

declared in secrets: with its egress: sink) — never exec: curl for the sake of a header.