name	nika-authoring
description	Author, check and repair Nika workflows (.nika.yaml files — the workflow language for AI). Use when writing or editing a *.nika.yaml file, converting a repeated AI task or prompt chain into a workflow, or when nika check reports NIKA-XXXX findings to fix.

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)

Start from a template or example, never from scratch: nika examples list · nika examples show <slug> · nika new --from <template> <file>.nika.yaml
Write the file. Envelope is always nika: v1 + workflow: <kebab-id> + tasks:.
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).
Repair from the diagnostics — they name the exact task, reference and fix. Unknown code? nika explain NIKA-XXXX.
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).
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).
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.
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:

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).
Which MCP tool replaces it? A product API deserves an MCP server, never a helper script.
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.

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)

Start from a template or example, never from scratch: nika examples list · nika examples show <slug> · nika new --from <template> <file>.nika.yaml

Write the file. Envelope is always nika: v1 + workflow: <kebab-id> + tasks:.

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).

Repair from the diagnostics — they name the exact task, reference and fix. Unknown code? nika explain NIKA-XXXX.

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).

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).

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.

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:

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).

Which MCP tool replaces it? A product API deserves an MCP server, never a helper script.

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:

--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.

nika-authoring

Authoring Nika workflows

The loop (always)

Cost honesty (never hide unknown spend)

The four verbs (exactly one per task)

Native-first (the law)

Exec ledger (mandatory when any exec remains)

Discipline

Authoring Nika workflows

The loop (always)

Cost honesty (never hide unknown spend)

The four verbs (exactly one per task)

Native-first (the law)

Exec ledger (mandatory when any exec remains)

Discipline