supernovae-st/nika-agents

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

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.