nika · author AI workflows as checkable files
Teach your agent to hand repeatable work to
Nika: a plain-text
.nika workflow it can check before a token is spent and
verify after. One Add installs the full bundle — your agent
learns to author, debug, operate and migrate workflows on its own.
brew install supernovae-st/tap/nika # the binary first; the plugin invokes it
What one install gives your agent
| Component | What it does |
|---|---|
nika-authoring skill | a concise authoring entry with task-specific language and validation references |
nika-debugging skill | run forensics: trace ls → show → outputs → verify · resume lines · surgical reruns |
nika-operating skill | day-2 hardening: spend caps · permits · secrets · model swaps · CI goldens · OTLP export |
nika-migration skill | convert scripts, CI jobs and prompt chains to workflows — mapping table + parity protocol |
nika-author subagent | writes or repairs the requested artifact, checks it and reports blockers; launching belongs to the conversation |
nika-debugger subagent | root-causes a failed or paused run from its hash-chained trace, hands back the exact resume line |
nika-migrator subagent | ports existing automation: inventory → native-first mapping → check loop → golden pin |
| language rule | the 4-verb surface (infer · exec · invoke · agent), auto-loaded on *.nika |
| delegation rule | teaches the agent WHEN to propose a workflow (repeatable · multi-step · spend-bound AI work) and which bundled surface to reach for |
/nika:check · /nika:explain · /nika:compile | audit a file · explain a finding code · compile an exact skeleton or conservative edit |
/nika:trace · /nika:permits | read a run's flight recorder (verdict · root cause · resume line) · infer and paste the tightest permits boundary |
/nika:doctor | diagnose this machine's Nika surface — binary · installed plugin kits (train drift, per-client fix) · providers · wiring — advisory by design, never breaks automation |
| session-context hook | a workspace with workflows greets the agent with the full nika map at session start (surfaces · laws · where traces live) — Cursor and Claude Code dialects |
| check-on-edit hook | every agent edit to a *.nika is audited immediately (findings in the hook log; never blocks the edit) |
| guard-run hook | pre-run judgment with findings on refusal (Cursor beforeShellExecution · Claude Code PreToolUse); installation and availability boundaries below |
| MCP oracle (9 tools) | nika_check · nika_explain · nika_schema · nika_examples · nika_template · nika_canon · nika_catalog · nika_tools · nika_inspect — read-only, by design |
The work it supports
Start from the named workflow or a suitable template, resolve unfamiliar shapes from the installed catalog, and adapt the artifact to the requested result. The authoring entry routes to only the needed references. Check the final file, repair actionable findings, and report concrete blockers if it is not ready. When execution is requested and authorized, the coordinating agent can run it within the existing effects and budget, inspect outputs and verify the trace. A check, run result and integrity verdict are different evidence.
No plugin store to audit on the workflow side either: everything
callable is a tool under invoke:, and the engine ships its own
builtin library.
Good to know
- macOS GUI PATH: Cursor may not inherit your shell PATH — if the
MCP oracle does not start, launch Cursor from a terminal once
(
open -a Cursor) or ensurenikais reachable from GUI apps. - Two hook classes, two failure laws. The comfort hooks (session
context, check-on-edit) degrade quietly: a missing binary or an
unreadable file means no context and no verdict, never a bricked
editor. The run guard is the opposite — fail-visible: if its sole
judge is unavailable (binary missing, broken judge, unreadable payload),
the hook blocks the action with exit 2 and
guard_unavailableon stderr. This also blocks ordinary shell actions until the editor PATH or judge failure is repaired: the shim cannot prove a command unrelated without the engine's JSON and shell decoding. It streams stdin directly into the engine's bounded reader and never guesses scope or host dialect. The other deny is a run on a file with live check findings — the denial carries the findings, so the agent repairs and re-checks by itself. - A healthy guard speaks only about
nika run. Every other parsed shell command the agent proposes passes through untouched — the hook returns no decision at all, so your host's own permission flow decides exactly as it would without the kit installed. An unavailable judge cannot return that no-opinion verdict; the degradation rule above applies. An affirmative « proceed » is only ever earned by a run the ladder just saw clean. - Windows: the hooks are bash scripts; without a bash on PATH the
hook processes cannot run — comfort AND guard rails are effectively
absent (runs fall back to the host's own permission flow, unguarded).
nika doctornames the missing rails; the engine's own boundaries (nika check·permits:· cost caps) still hold whenever you run the binary yourself. - The engine stays the authority: hooks are a seatbelt, never the airbag. Everything the oracle answers is read-only by design: the MCP oracle audits and teaches; execution uses the host's visible shell tools under the user's authorization and the engine's admission boundaries.
Links
Docs: https://docs.nika.sh · Spec: https://github.com/supernovae-st/nika-spec · Site: https://nika.sh · Engine (AGPL-3.0-or-later): https://github.com/supernovae-st/nika