nika

# 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` 2. **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. 3. **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). 4. **Repair from the diagnostics** — they name the exact task, reference and fix. Unknown code? `nika explain NIKA-XXXX`. 5. 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). 6. 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`). 7. 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. 8. **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). 2. **Which MCP tool replaces it?** A product API deserves an MCP server, never a helper script. 3. **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.