Run auditable, budgeted AI workflows with cost caps and receipts

Nika Skill

Use Nika as a deterministic workflow worker orchestrated by
the Hermes terminal tool. Nika is an open-source (AGPL) Rust engine that captures
a repeatable AI task as a plain-text *.nika.yaml file, audits it before a
single token is spent (plan, cost floor, secret flows, types), executes it
against local or cloud providers (Ollama/llama.cpp/vLLM included), and records
a tamper-evident trace.

Division of labor: Hermes orchestrates · Nika captures repeatable work as a
checkable file and runs it with receipts. Nika is NOT another coding agent -
for autonomous coding, use the opencode skill. Delegate to Nika when the
work should be repeatable, budgeted, and auditable.

When to Use

• The user asks to run, check, or author a *.nika.yaml workflow
• A task will be repeated (daily digest, triage, ETL, report, multi-step LLM
  pipeline) - capture it as a workflow instead of re-prompting
• The user wants a hard cost cap, a cost estimate before running, or
  receipts/audit of what ran
• A pipeline mixes models/providers (local + cloud) or mixes LLM steps with
  shell/HTTP/file steps
• The user wants a run they can replay, verify, or reproduce later

When NOT to use

• One-off questions or single tool calls - just answer or use a tool
• Autonomous code implementation/refactoring/PR review - use the opencode skill
• Interactive back-and-forth tasks - workflows are non-interactive by design

Prerequisites

• Nika installed: brew install supernovae-st/tap/nika - other install
  paths (script, manual download) are documented at https://nika.sh: installing
  is a human step, not something this skill runs
• Verify: terminal(command="nika --version")
• Zero keys needed for local/offline work: --model mock/echo (offline) and
  --model ollama/... (local) run without any API key
• Cloud providers read standard env vars from the shell;
  terminal(command="nika doctor") diagnoses and prints exact fix commands

How to Run

Prove the toolchain offline first (no key, no network):

terminal(command="nika examples run 01-hello --model mock/echo")

Run a real workflow - local model first:

terminal(command="nika run flow.nika.yaml --model ollama/qwen3.5:4b", workdir="~/project")

Cloud model with a hard budget (always set one for paid models):

terminal(command="nika run flow.nika.yaml --model mistral/mistral-small-latest --max-cost-usd 0.25", workdir="~/project")

Pass workflow variables:

terminal(command="nika run report.nika.yaml --var city=Paris --var days=7 --max-cost-usd 0.50", workdir="~/project")

Long runs: launch in background and poll - do not block the turn:

terminal(command="nika run long.nika.yaml --max-cost-usd 1.00", workdir="~/project", background=true)
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

The check-before-run law

Never run a workflow you have not checked. nika check is a static pre-flight
(no tokens spent, no network): plan shape, cost floor, secret-flow analysis,
type checks, tool args.

terminal(command="nika check flow.nika.yaml --json", workdir="~/project")

Findings carry NIKA-XXXX codes that explain themselves via
nika explain NIKA-XXXX. Exit 0 = green, safe to run. Fix findings before
running - never suppress them.

Authoring a workflow

Turn a repeated task into a file. List templates, then instantiate:

terminal(command="nika new --from '?'")
terminal(command="nika new flow.nika.yaml --from chain", workdir="~/project")

--from also accepts plain-words intent. Edit the skeleton (vars:,
tasks:, outputs:), then check it. nika explain flow.nika.yaml
narrates what it will do, the waves, the cost floor, and what it touches -
before anything runs.

The artifact you are producing looks like this (checks clean on 0.98):

nika: v1
workflow: daily-brief
model: ollama/qwen3.5:4b
tasks:
  - id: fetch
    invoke:
      tool: "nika:fetch"
      args: { url: "https://hn.algolia.com/api/v1/search?tags=front_page" }
  - id: brief
    depends_on: [fetch]
    infer:
      max_tokens: 300
      prompt: |
        Five bullet points, most signal first: ${{ tasks.fetch.output }}
outputs:
  brief: ${{ tasks.brief.output }}

One file, plain YAML: tasks, an explicit dependency, a bounded model step,
a declared output. That file is what gets checked, run, diffed and reused.

Cost honesty

• When the workflow prices above the budget, --max-cost-usd refuses to
  start (exit 2, zero tokens) - and since 0.99 the pre-start floor prices
  the EFFECTIVE model, --model override included
• Mid-run, the ledger stops the workflow the moment real spend crosses the
  budget: the crossing call completes, nothing new starts, the run fails
  NIKA-1704 (exit 1) with spent-vs-budget
• Estimates use LIST RATES from the vendored public catalog; local · mock ·
  unpriced work is never blocked
• A model absent from the catalog meters as $0 - a paid uncataloged model
  runs with no budget protection; prefer cataloged ids (nika catalog)
• Report the cost line from the final run card (the summary block nika run prints last - status, cost, trace path) back to the user verbatim

Receipts and verification

Every run writes a trace under .nika/traces/ - the run card prints the
trace path on its trace: line. Both commands take that path (bare
invocations are a usage error):

terminal(command="nika trace show .nika/traces/<run>.ndjson", workdir="~/project")
terminal(command="nika trace verify .nika/traces/<run>.ndjson", workdir="~/project")

trace verify checks the tamper-evidence hash chain: exit 0 intact · 2
broken · 3 pre-chain. Also useful: nika trace outputs · nika trace flow ·
nika trace reproduce · nika trace export (OTLP lines).

Optional: MCP oracle tools

Nika also ships a read-only MCP oracle (nika mcp) exposing validation and
learning tools (nika_check, nika_explain, nika_schema, nika_examples,
nika_template, nika_canon, nika_catalog, nika_tools). If the user
wants those wired into their agent client, point them at the wiring guide -
https://github.com/supernovae-st/nika-agents/tree/main/integrations/mcp -
editing the client's own configuration is the user's step, never this
skill's. Without the oracle, everything above still works over the terminal;
running workflows stays there regardless, where the budget flags and traces
live.

Quick Reference

Command	Use
nika welcome	What Nika is + what this machine has (offline, exit 0)
nika new <file> --from <template>	Scaffold a workflow (--from '?' lists)
nika check <file> --json	Static pre-flight - ALWAYS before run
nika explain <file>	Narrate: waves, cost floor, touches
nika run <file> --model <p/m> --max-cost-usd <usd>	Execute with budget
nika test <file>	Golden test under the mock provider (offline)
nika trace show/verify/outputs/flow <trace>	Receipts after a run (path from the run card's trace: line)
nika doctor	Diagnose env/keys - prints exact fixes
nika catalog	Provider/model ids + required env vars

Procedure

1. Verify readiness: terminal(command="nika --version"); install per
   Prerequisites if missing.
2. If the task is new, scaffold: nika new <file> --from <template>.
3. Check: nika check <file> --json. Fix every finding
   (nika explain <code>). Do not run an unchecked file.
4. Preview offline when useful: nika run <file> --model mock/echo.
5. Run with an explicit --model and, for any paid model, an explicit
   --max-cost-usd.
6. For long runs use background=true and poll with
   process(action="poll"|"log").
7. After the run: nika trace show <trace> + nika trace verify <trace>
   (path from the run card); report outputs, actual cost, and the verify
   verdict to the user.

Rules

1. NEVER run an unchecked workflow - nika check first, every time.
2. ALWAYS pass --max-cost-usd when the model is a paid cloud model.
3. Prefer local models (ollama/...) or mock/echo for drafts; escalate to
   cloud models only when needed.
4. Report the final run card honestly: status, actual cost, trace path,
   trace verify verdict.
5. One workflow file per delegated task; keep files in the user's repo so
   they are diffable and reusable.
6. If a run fails, read nika explain <NIKA-code> before retrying - do not
   blind-retry.

Pitfalls

• nika run renders live on a TTY; when piped (Hermes terminal), output can
  stay quiet until completion - for anything long, prefer background=true +
  poll, then read nika trace show <trace> for the final card.
• nika new with no --from opens a guided TTY flow; in a pipe it fails
  fast naming the flag - always pass --from <template> when delegating.
• The budget guard stops NEW admissions: one wide parallel wave can overshoot
  by that wave's spend. Tighten with max_parallel: when the budget is strict.
• Uncataloged model ids meter as $0 - never rely on --max-cost-usd for a
  custom endpoint model.
• Workflow outputs: are not resolved on a budget stop - per-task values
  live in the trace (nika trace outputs).

Limitations

• Static checks reduce risk but cannot prove that remote content, shell steps,
  provider behavior, or generated outputs are safe or correct.
• Cost caps are not reliable for uncataloged paid models and a parallel wave
  can overshoot before new work is stopped; require explicit user approval for
  paid runs and report the actual ledger result.
• Trace verification proves integrity of the recorded chain, not correctness
  of the workflow or truth of its outputs.

Verification

Smoke test (offline, zero keys):

terminal(command="nika examples run 01-hello --model mock/echo")

Success criteria: run completes exit 0 with a final run card · nika check
exits 0 before any real run · nika trace verify exits 0 after the run.