domains / agent-tooling / nika-workflow-authoring / nika

nika

Skill card

combined

Both copies describe the same Nika workflow engine, but they are not interchangeable. The davepoon copy is a deep authoring guide focused on the 'native-first' law, the exec ledger, and specific builtin mappings (e.g., using nika:fetch instead of curl). The sickn33 copy is an operational guide focused on the Hermes agent context, installation, background execution, and specific error codes (NIKA-1704). The davepoon copy contains critical authoring constraints (the exec ledger) that the sickn33 copy lacks, while the sickn33 copy contains operational steps (background polling, installation) that the davepoon copy lacks. Combining them provides a complete skill for both authoring and running Nika workflows.

Repositories

Other copies

Combined skill

---
name: nika
description: "Author and run repeatable AI workflows using Nika .nika.yaml files with cost controls and tamper-evident traces."
category: automation
requires:
  bins: [nika]
---

# Nika Workflow Skill

Nika captures repeatable AI tasks as `.nika.yaml` files, audits them before execution, and runs them with cost caps and tamper-evident traces.

## 1. Setup & Verification
- Install Nika (human step): `brew install supernovae-st/tap/nika`.
- Verify: `nika --version`.
- Prove toolchain offline: `nika examples run 01-hello --model mock/echo`.

## 2. Authoring Workflows
1. **Start from a template**: `nika new --from <template> <file>.nika.yaml`.
2. **Native-First Law**: Before writing any `exec:`, check if a builtin (`nika:fetch`, `nika:jq`, etc.) or MCP tool can replace it. 
   - HTTP fetch → `invoke: nika:fetch`
   - JSON shaping → `invoke: nika:jq`
   - File I/O → `invoke: nika:read`/`nika:write`
3. **Exec Ledger**: If `exec:` is unavoidable, add a row to the workflow header comment explaining why no native path exists.
4. **Structure**: Use `infer:` for LLM calls, `exec:` for shell, `invoke:` for tools, `agent:` for multi-turn loops. Declare `depends_on` for data flow.

## 3. Checking & Cost Honesty
- **Check**: `nika check <file>` (exit 0 = clean). Use `--native-strict` to fail on non-native execs.
- **Cost**: `nika check` prints a cost ceiling. Local models are "unpriced", not "free".
- **Explain**: `nika explain <file>` narrates the plan, waves, and cost floor.

## 4. Execution
- **Local/Offline**: `nika run <file> --model ollama/<model>` or `--model mock/echo`.
- **Cloud/Budgeted**: `nika run <file> --model <provider>/<model> --max-cost-usd <n>`.
- **Variables**: Pass inputs with `--var key=value`.
- **Long Runs**: Use background execution and poll for status.
- **Resume**: `nika run <file> --resume <trace> --answer <task>=<value>`.

## 5. Verification & Audit
- **Traces**: Every run writes a hash-chained journal to `.nika/traces/`.
- **Verify**: `nika trace verify <trace>` to check tamper-evidence.
- **Golden Tests**: `nika test <file> --update` to create a deterministic golden file for CI.