[{"k":"h","depth":1,"text":"02 · The 4 verbs","id":"02--the-4-verbs"},{"k":"quote","inline":[{"k":"text","text":"Every task in a Nika workflow binds to "},{"k":"strong","text":"exactly one"},{"k":"text","text":" of 4 verbs.\nA verb is a "},{"k":"strong","text":"distinct native execution model"},{"k":"text","text":" the engine itself\nimplements: call a model, run a process, dispatch a tool, drive an\nagentic loop. That is the whole operation space."},{"k":"text","text":"Everything "},{"k":"em","text":"callable"},{"k":"text","text":" (fetching a URL, a database query, a file\nwrite, cognitive recall) is a "},{"k":"strong","text":"tool"},{"k":"text","text":" reached through "},{"k":"code","text":"invoke:"},{"k":"text","text":".\nEverything about "},{"k":"em","text":"ordering"},{"k":"text","text":" (iteration, branching) is a "},{"k":"strong","text":"DAG"},{"k":"text","text":"\nconstruct ("},{"k":"code","text":"for_each"},{"k":"text","text":" · "},{"k":"code","text":"when"},{"k":"text","text":"). The 4 verbs never change; tools and\nthe stdlib grow freely."}]},{"k":"hr"},{"k":"h","depth":2,"text":"The 4 verbs · summary","id":"the-4-verbs--summary"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Verb · What it does · Stdlib it consumes"}],[{"k":"text","text":"`infer:` · Single LLM call · text · structured · vision · thinking · providers"}],[{"k":"text","text":"`exec:` · Shell command with sandboxing · (none · pure effect)"}],[{"k":"text","text":"`invoke:` · Call a builtin tool OR an MCP tool · builtins · MCP servers"}],[{"k":"text","text":"`agent:` · Multi-turn agentic loop with tool calls · providers · builtins · MCP"}]]},{"k":"p","inline":[{"k":"text","text":"A task "},{"k":"strong","text":"must"},{"k":"text","text":" specify exactly one of these. Multiple verbs on a single task is a validation error."}]},{"k":"quote","inline":[{"k":"strong","text":"Where did `fetch` go?"},{"k":"text","text":" Fetching a URL is "},{"k":"em","text":"calling a tool"},{"k":"text","text":", not a\ndistinct execution model, so it is the "},{"k":"code","text":"nika:fetch"},{"k":"text","text":" builtin, reached\nthrough "},{"k":"code","text":"invoke:"},{"k":"text","text":" (the extract modes become its "},{"k":"code","text":"mode"},{"k":"text","text":" argument). Same\nreason a DB query ("},{"k":"code","text":"invoke: mcp:postgres/query"},{"k":"text","text":") or a file write\n("},{"k":"code","text":"invoke: nika:write"},{"k":"text","text":") is not its own verb. See\n"},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"What `\u0024{{ tasks.<id>.output }}` holds · per verb","id":"what--tasksidoutput--holds--per-verb"},{"k":"p","inline":[{"k":"text","text":"Every task also exposes the full result record ("},{"k":"code","text":".status"},{"k":"text","text":" · "},{"k":"code","text":".error"},{"k":"text","text":" ·\n"},{"k":"code","text":".started_at"},{"k":"text","text":" · "},{"k":"code","text":".ended_at"},{"k":"text","text":" · "},{"k":"code","text":".duration_ms"},{"k":"text","text":" · "},{"k":"link","text":"04 §task output reference","href":"./04-variables.md#-taskxoutput--task-output-reference"},{"k":"text","text":").\nThe "},{"k":"code","text":".output"},{"k":"text","text":" shape depends on the verb (know this before you bind downstream) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Verb · `.output` is · Structured when"}],[{"k":"text","text":"`infer:` · the model's reply · **string** · `schema:` set → **object** matching it"}],[{"k":"text","text":"`exec:` · **stdout string** (default) · `capture: structured` → `{ stdout, stderr, exit_code }`"}],[{"k":"text","text":"`invoke:` · the **tool's response** (tool-defined · string · object · or bytes) · per builtin / MCP tool schema · bytes are tool-determined (MCP image content · binary read) · flow opaquely · see 04 §value rendering"}],[{"k":"text","text":"`agent:` · the loop's **final message** · string · `schema:` set → **object** matching it"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`infer:` · LLM call","id":"infer--llm-call"},{"k":"p","inline":[{"k":"text","text":"A single LLM call. The result is the model's response."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal"},{"k":"code","lang":"yaml","text":"greet:\n    infer:\n      prompt: \"Say hello in French\""},{"k":"h","depth":3,"text":"Full","id":"full"},{"k":"code","lang":"yaml","text":"research:\n    infer:\n      prompt: \"Research Rust async runtimes 2026 in 5 paragraphs\"\n      system: \"You are a senior software architect.\"\n      model: mistral/mistral-large         # override default · <provider>/<name>\n      temperature: 0.3\n      max_tokens: 2000\n      schema:                            # optional · structured output\n        type: object\n        required: [summary, paragraphs]\n        properties:\n          summary: { type: string }\n          paragraphs: { type: array, items: { type: string } }\n      thinking:                          # optional · extended thinking\n        enabled: true\n        budget_tokens: 4000\n      vision:                            # optional · vision input\n        - source: file\n          path: \"./diagram.png\""},{"k":"h","depth":3,"text":"Fields","id":"fields"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`prompt` · yes · string · User prompt · may use `\u0024{{ ... }}` substitution"}],[{"k":"text","text":"`system` · no · string · System prompt"}],[{"k":"text","text":"`model` · no · string · Override workflow default · `<provider>/<name>` · see stdlib/providers-v0.1.md"}],[{"k":"text","text":"`temperature` · no · number 0-2 · Sampling temperature"}],[{"k":"text","text":"`max_tokens` · no · integer · Max output tokens · provider-dependent default"}],[{"k":"text","text":"`schema` · no · object · raw JSON Schema · structured output validation — the **out-of-core hatch**; the typed door is task-level `returns:` ([09](./09-types.md) · both on one task = `NIKA-TYPE-003`). Numeric facts (`0|1|3`, counts, coded levels) are `type: integer` with a numeric `enum` — never `enum: [\"0\",\"1\",\"3\"]`. Models emit JSON numbers; a string-digit enum can reject the call before coerce (reference engine hint `digit-string-enum`). The model extracts facts; `nika:jq` or `nika:decide` is the law ([11](./11-decision.md) · `examples/13-extract-then-law.nika.yaml`)"}],[{"k":"text","text":"`thinking` · no · object · Extended thinking · `{ enabled, budget_tokens }`"}],[{"k":"text","text":"`vision` · no · array · Image inputs · each `{ source: file"}]]},{"k":"h","depth":3,"text":"Conformance","id":"conformance"},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Call the configured provider with the given prompt + system + parameters"}],[{"k":"text","text":"Return the model's response as the task output"}],[{"k":"text","text":"Validate the response against "},{"k":"code","text":"schema"},{"k":"text","text":" if present · MAY auto-retry validation failures internally before surfacing "},{"k":"code","text":"NIKA-INFER-002"},{"k":"text","text":" (engine-configurable · the same rule as "},{"k":"link","text":"05 §structured output","href":"./05-errors.md#structured-output-validation"},{"k":"text","text":")"}],[{"k":"strong","text":"Reject"},{"k":"text","text":" any unknown field with a clear error ("},{"k":"code","text":"NIKA-PARSE-005"},{"k":"text","text":") — the choice this line used to leave open is closed by "},{"k":"link","text":"07 §unknown key","href":"./07-conformance.md#an-unknown-key-is-an-error-at-every-level-normative--d-2026-08-11-n20"},{"k":"text","text":": a key can REMOVE authority, so accept-and-warn fails open"}]]},{"k":"h","depth":3,"text":"Subscription harness access (normative)","id":"subscription-harness-access-normative"},{"k":"p","inline":[{"k":"text","text":"An engine MAY execute "},{"k":"code","text":"infer:"},{"k":"text","text":" through a user's authenticated CLI seat\ninstead of a provider API key, but only after an "},{"k":"strong","text":"infer-grade meet"},{"k":"text","text":" proves\nall four properties for that adapter and this task:"}]},{"k":"list","ordered":true,"items":[[{"k":"code","text":"single_turn"},{"k":"text","text":" — one request produces one terminal answer;"}],[{"k":"code","text":"no_implicit_tools"},{"k":"text","text":" — an accepted answer contains no tool, command, file,\nnetwork, or permission event;"}],[{"k":"code","text":"structured_output"},{"k":"text","text":" — the adapter's level is at least the task's need\n(plain text, JSON, or JSON Schema);"}],[{"k":"code","text":"model_identity"},{"k":"text","text":" — the requested model identity is observable at command\nconstruction and is recorded without being relabelled as the model that\nanswered."}]]},{"k":"p","inline":[{"k":"text","text":"The meet is evidence, not a product-name allowlist. A seat with no attestation,\nor one failing any conjunct, MUST be refused before inference with a witness\nthat names the failed property. It MUST NOT fall back to a native provider or\nto the seat's agentic loop. In particular, an ACP-capable agent seat is not\nthereby infer-grade."}]},{"k":"p","inline":[{"k":"text","text":"For an accepted seat run, the receipt MUST record the seat id and the\n"},{"k":"strong","text":"requested"},{"k":"text","text":" model. It MUST leave the responding model absent unless the\nadapter reports that fact explicitly; request identity is never promoted into\nresponse identity. Subscription inference has no numeric token count and no\nnumeric price in the Nika receipt or budget. Its budget lane is\n"},{"k":"code","text":"subscription quota"},{"k":"text","text":", never "},{"k":"code","text":"0 USD"},{"k":"text","text":". An adapter may read a terminal usage\nobject as protocol-completeness evidence, but MUST NOT project its numeric\nmeters into the Nika receipt."}]},{"k":"p","inline":[{"k":"text","text":"A non-executing preview that accepts an access pin MUST apply the same access\nadmission meet as a live run and record the requested pin plus each requested\nmodel. The same invalid or unattested pin MUST refuse with the same access\ncode. For an admitted subscription seat, the preview MUST name\n"},{"k":"code","text":"subscription quota"},{"k":"text","text":" and MUST NOT display a numeric USD or token meter."}]},{"k":"hr"},{"k":"h","depth":2,"text":"`exec:` · shell command","id":"exec--shell-command"},{"k":"p","inline":[{"k":"text","text":"Run a shell command. The result is the command's stdout (default) or a structured output."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal-1"},{"k":"code","lang":"yaml","text":"build:\n    exec:\n      command: [\"cargo\", \"build\", \"--release\"]"},{"k":"h","depth":3,"text":"Full","id":"full-1"},{"k":"code","lang":"yaml","text":"test:\n    timeout: \"60s\"                   # task-level (applies to any verb · Go duration · see 03-dag)\n    exec:\n      command: [\"cargo\", \"test\", \"--workspace\", \"--lib\"]\n      cwd: \"./engine\"\n      env:\n        RUST_LOG: \"debug\"\n      stdin: \"\u0024{{ inputs.input_data }}\"\n      capture: structured            # stdout | stderr | structured | combined"},{"k":"h","depth":3,"text":"Fields","id":"fields-1"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`command` · one of · array · **argv** — `[\"prog\", \"arg\", …]` → direct `execve`, **NO shell** · each element substituted independently — an interpolated `\u0024{{ }}` value can never break out of its argument (see Security). Exactly one of `command` | `shell`."}],[{"k":"text","text":"`shell` · one of · string · **The explicit shell door** — one line run via `/bin/sh -c` · pipes · redirects · globs. The blocklist applies HERE; interpolating untrusted values here is the author's own risk, visibly. Exactly one of `command` | `shell`. *(D1 · #75: semantics never fork on a YAML type — the field name carries the meaning. The old string `command:` is rejected at parse.)*"}],[{"k":"text","text":"`cwd` · no · string · Working directory · default = engine's cwd"}],[{"k":"text","text":"`env` · no · object · OS environment variables for **this subprocess** · key→value map · applied over the COMPOSED environment ([01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary) env · never inherited)"}],[{"k":"text","text":"`stdin` · no · string · Stdin data · may use `\u0024{{ ... }}`"}],[{"k":"text","text":"`capture` · no · enum · `stdout` (default) · `stderr` · `combined` · `structured` (= `{ stdout, stderr, exit_code }`) — the **source**"}],[{"k":"text","text":"`decode` · no · enum · `text` (default) · `json` · `jsonl` · `bytes` — how the captured **string** becomes a value ([09 §decode](./09-types.md#decode--how-exec-bytes-become-a-value-normative)) · illegal with `capture: structured` (`NIKA-PARSE-025` — that capture already IS an object) · a non-parsing stream settles the task `failure` inside `on_error:` scope"}]]},{"k":"quote","inline":[{"k":"strong","text":"`exec.env` is a subprocess field, never an envelope block"},{"k":"text","text":": no top-level\nkey of that family survives — the pre-flip envelope "},{"k":"code","text":"env:"},{"k":"text","text":" block is dead\n("},{"k":"code","text":"NIKA-VALUES-002"},{"k":"text","text":") and the top-level "},{"k":"code","text":"config:"},{"k":"text","text":" block died with the envelope\nnuke, so "},{"k":"code","text":"exec.env"},{"k":"text","text":" is the "},{"k":"em","text":"OS environment of this subprocess"},{"k":"text","text":" and nothing\nelse. Nothing is auto-connected. To pass a workflow value into the process,\ndo it explicitly: "},{"k":"code","text":"env: { API_BASE: \"\u0024{{ inputs.api_base }}\" }"},{"k":"text","text":". The subprocess\nenvironment itself is COMPOSED, never inherited (NEP-0005 ·\n"},{"k":"link","text":"01 §permits","href":"./01-envelope.md#permits--optional--the-declared-capability-boundary"},{"k":"text","text":"):\nthe runner env floor ∪ the "},{"k":"code","text":"permits.env:"},{"k":"text","text":" passthrough ∪ this map, minus\nthe dangerous-name floor · an ambient engine variable reaches the child\nonly through a declared "},{"k":"code","text":"permits.env:"},{"k":"text","text":" name."}]},{"k":"quote","inline":[{"k":"code","text":"timeout"},{"k":"text","text":" and "},{"k":"code","text":"retry"},{"k":"text","text":" are "},{"k":"strong","text":"task-level"},{"k":"text","text":" fields (see "},{"k":"link","text":"03-dag.md","href":"./03-dag.md"},{"k":"text","text":"): they apply uniformly to every verb, so they are not repeated inside "},{"k":"code","text":"exec:"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Security","id":"security"},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Honor the two exec bodies"},{"k":"text","text":" · "},{"k":"code","text":"command:"},{"k":"text","text":" (array) runs through "},{"k":"code","text":"execve"},{"k":"text","text":" with NO shell: "},{"k":"code","text":"command[0]"},{"k":"text","text":" is the program, the rest are argv passed verbatim, each element substituted independently. "},{"k":"code","text":"shell:"},{"k":"text","text":" (string) runs through "},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" — the shell-feature path (pipes · redirects · globs). "},{"k":"strong","text":"Exactly one"},{"k":"text","text":" of the two; a string "},{"k":"code","text":"command:"},{"k":"text","text":" (the pre-0.103 implicit-shell form) is rejected at parse ("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":")."}],[{"k":"text","text":"Implement a shell "},{"k":"strong","text":"blocklist"},{"k":"text","text":" for dangerous commands on "},{"k":"code","text":"shell:"},{"k":"text","text":" (see reference impl "},{"k":"code","text":"nika-policy"},{"k":"text","text":" for canonical list · 100+ patterns including "},{"k":"code","text":"rm -rf /"},{"k":"text","text":" · "},{"k":"code","text":"chmod 777"},{"k":"text","text":" · "},{"k":"code","text":"curl … | sh"},{"k":"text","text":" · etc.)"}],[{"k":"text","text":"Reject blocklist matches with a clear error"}],[{"k":"text","text":"Honor "},{"k":"code","text":"timeout"},{"k":"text","text":" with a hard kill (Go-duration string · see 03-dag)"}],[{"k":"text","text":"Sandbox "},{"k":"code","text":"cwd"},{"k":"text","text":" if configured (engine-specific)"}]]},{"k":"quote","inline":[{"k":"strong","text":"The argv form is the STRUCTURAL fix for command injection: prefer it."},{"k":"text","text":"\nA "},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":"-interpolated value in the STRING form is shell-parsed:\n"},{"k":"code","text":"shell: \"process \u0024{{ item }}\""},{"k":"text","text":" with "},{"k":"code","text":"item == \"; rm -rf /\""},{"k":"text","text":" is a classic\ninjection, and the blocklist is a "},{"k":"em","text":"detector"},{"k":"text","text":" (best-effort), not a guarantee.\nThe ARRAY form removes the shell entirely: "},{"k":"code","text":"command: [\"process\", \"\u0024{{ item }}\"]"},{"k":"text","text":"\npasses "},{"k":"code","text":"item"},{"k":"text","text":" as ONE argv element no matter what it contains; there is no\nshell to parse it. "},{"k":"strong","text":"Rule of thumb · any command carrying a task output, a\n`var`, or any value not authored inline → use the array form."},{"k":"text","text":" "},{"k":"code","text":"nika check"},{"k":"text","text":"\nwarns ("},{"k":"code","text":"one-obvious-way"},{"k":"text","text":") when an interpolated value lands in a string\n"},{"k":"code","text":"command"},{"k":"text","text":". The string form stays first-class for genuine shell pipelines\n("},{"k":"code","text":"\"cat x | grep y > z\""},{"k":"text","text":"). That is what "},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" is for."}]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-1"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Run the STRING command via the OS shell ("},{"k":"code","text":"/bin/sh -c"},{"k":"text","text":" on Unix · "},{"k":"code","text":"cmd /c"},{"k":"text","text":" on Windows, OR a sandboxed equivalent) · run the ARRAY command via "},{"k":"code","text":"execve"},{"k":"text","text":" with no shell"}],[{"k":"text","text":"Capture stdout/stderr as configured"}],[{"k":"text","text":"Return exit code in "},{"k":"code","text":"structured"},{"k":"text","text":" capture mode"}],[{"k":"strong","text":"Fail the task on non-zero exit"},{"k":"text","text":" ("},{"k":"code","text":"NIKA-EXEC-001"},{"k":"text","text":" · "},{"k":"code","text":"process_error"},{"k":"text","text":") in\n"},{"k":"code","text":"stdout"},{"k":"text","text":" / "},{"k":"code","text":"stderr"},{"k":"text","text":" / "},{"k":"code","text":"combined"},{"k":"text","text":" capture modes (unless "},{"k":"code","text":"on_error:"},{"k":"text","text":" recovers ·\n"},{"k":"link","text":"05","href":"./05-errors.md"},{"k":"text","text":"), "},{"k":"strong","text":"EXCEPT `capture: structured`"},{"k":"text","text":", where a non-zero\nexit is "},{"k":"strong","text":"data, not failure"},{"k":"text","text":" · the task succeeds and "},{"k":"code","text":"exit_code"},{"k":"text","text":" is the\nworkflow's to branch on ("},{"k":"code","text":"when: \u0024{{ tasks.test.output.exit_code != 0 }}"},{"k":"text","text":") ·\nthe one-obvious-way split · default modes for « must succeed » · structured\nfor « inspect the outcome »"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`invoke:` · builtin or MCP tool call","id":"invoke--builtin-or-mcp-tool-call"},{"k":"p","inline":[{"k":"text","text":"Call a builtin ("},{"k":"code","text":"nika:"},{"k":"text","text":" namespace) or an MCP tool ("},{"k":"code","text":"mcp:"},{"k":"text","text":" namespace). The result is the tool's response."}]},{"k":"h","depth":3,"text":"Tool reference grammar (canonical)","id":"tool-reference-grammar-canonical"},{"k":"code","lang":"text","text":"<namespace>:<path>          one colon introduces the namespace · `/` separates the path\n\nnika:fetch                  builtin · HTTP + extraction (used to be a verb)\nnika:write                  builtin · flat name\nnika:connectome/recall      builtin · grouped path\nmcp:browser/navigate        MCP · server `browser` · tool `navigate`\nmcp:postgres/query          MCP · server `postgres` · tool `query`\nmcp:my-server/do_thing      MCP · server names admit kebab-case · tools admit snake_case"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"mcp:"},{"k":"text","text":" form "},{"k":"strong","text":"requires the slash"},{"k":"text","text":": "},{"k":"code","text":"mcp:postgres"},{"k":"text","text":" alone (no tool) is a\nparse error ("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":") · server segment\n"},{"k":"code","text":"[a-z][a-z0-9-]*"},{"k":"text","text":" · tool segment "},{"k":"code","text":"[A-Za-z0-9_-]+"},{"k":"text","text":" (tool names are the MCP\nserver's to define)."}]},{"k":"p","inline":[{"k":"text","text":"One rule everywhere · the "},{"k":"strong","text":"colon"},{"k":"text","text":" marks the namespace boundary (exactly once),\nthe "},{"k":"strong","text":"slash"},{"k":"text","text":" separates the path within it. No "},{"k":"code","text":"::"},{"k":"text","text":", no mixed "},{"k":"code","text":"."},{"k":"text","text":"/"},{"k":"code","text":":"},{"k":"text","text":". Globs are\nclean · "},{"k":"code","text":"nika:*"},{"k":"text","text":" · "},{"k":"code","text":"nika:connectome/*"},{"k":"text","text":" · "},{"k":"code","text":"mcp:browser/*"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"strong","text":"The namespace set is CLOSED at v1"},{"k":"text","text":" · "},{"k":"code","text":"nika:"},{"k":"text","text":" and "},{"k":"code","text":"mcp:"},{"k":"text","text":" are the only two ·\nany other namespace ("},{"k":"code","text":"custom:thing"},{"k":"text","text":" · "},{"k":"code","text":"x:tool"},{"k":"text","text":") is rejected at parse time\n("},{"k":"code","text":"NIKA-PARSE"},{"k":"text","text":" · "},{"k":"code","text":"validation_error"},{"k":"text","text":"). A third namespace would be an additive\nspec minor. It never appears silently."}]},{"k":"h","depth":3,"text":"Builtin call","id":"builtin-call"},{"k":"code","lang":"yaml","text":"read_config:\n    invoke:\n      tool: \"nika:read\"\n      args:\n        path: \"./config.yaml\""},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" for the canonical builtin list (28 builtins in v0.1)."}]},{"k":"quote","inline":[{"k":"strong","text":"Grouped paths are grammar-legal · v0.1 ships none."},{"k":"text","text":" The reference\ngrammar admits "},{"k":"code","text":"nika:<group>/<tool>"},{"k":"text","text":" (the "},{"k":"code","text":"nika:connectome/recall"},{"k":"text","text":"\nillustration above is the reserved FUTURE shape), but the v0.1 builtin\nset contains only flat names · a grouped "},{"k":"code","text":"nika:"},{"k":"text","text":" path is rejected against\nthe closed 23 set today ("},{"k":"code","text":"NIKA-INVOKE-001"},{"k":"text","text":"). The seam exists so the\nConnectome tools land additively · zero workflow-shape change."}]},{"k":"h","depth":3,"text":"MCP call","id":"mcp-call"},{"k":"code","lang":"yaml","text":"query_db:\n    invoke:\n      tool: \"mcp:postgres/query\"\n      args:\n        sql: \"SELECT * FROM users WHERE id = \u00241\"\n        params: [\"\u0024{{ inputs.user_id }}\"]"},{"k":"p","inline":[{"k":"text","text":"The MCP server "},{"k":"code","text":"postgres"},{"k":"text","text":" must be configured in the engine's MCP server registry."}]},{"k":"h","depth":3,"text":"Fields","id":"fields-2"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`tool` · yes · string · Tool identifier · `nika:<path>` OR `mcp:<server>/<tool>`"}],[{"k":"text","text":"`args` · no · object · Tool arguments · schema is tool-specific"}]]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-2"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Resolve the tool identifier to its implementation (builtin or MCP server)"}],[{"k":"text","text":"Reject unknown tools with a clear error"}],[{"k":"text","text":"Pass "},{"k":"code","text":"args"},{"k":"text","text":" to the tool · validate against tool's schema if known"}],[{"k":"text","text":"Return the tool's response as task output"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"`agent:` · multi-turn agentic loop","id":"agent--multi-turn-agentic-loop"},{"k":"p","inline":[{"k":"text","text":"Run an agentic loop · the model + a set of tools · iterating until completion or budget exhausted."}]},{"k":"h","depth":3,"text":"Minimal","id":"minimal-2"},{"k":"code","lang":"yaml","text":"research:\n    agent:\n      system: \"You are a research assistant.\"\n      prompt: \"Research the topic · \u0024{{ inputs.topic }}\"\n      tools: [\"nika:fetch\"]             # default-deny · grant explicitly"},{"k":"h","depth":3,"text":"Full","id":"full-2"},{"k":"code","lang":"yaml","text":"research:\n    agent:\n      system: \"You are a research assistant. Use tools to gather info.\"\n      prompt: \"Research the topic · \u0024{{ inputs.topic }} · and produce a markdown brief\"\n      model: mistral/mistral-large\n      tools:                            # whitelist · default-deny (no tools if omitted)\n        - \"nika:fetch\"\n        - \"nika:write\"\n        - \"mcp:browser/*\"               # all tools from browser MCP server\n      skills:                           # Agent Skills · SKILL.md paths (agentskills.io shape)\n        - \".agents/skills/nika-authoring/SKILL.md\"\n      max_turns: 20\n      max_tokens_total: 100000\n      temperature: 0.3\n      schema:                           # optional · validate the final message as structured output\n        type: object\n        required: [findings]\n        properties:\n          findings: { type: array, items: { type: string } }"},{"k":"h","depth":3,"text":"Fields","id":"fields-3"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Field · Required · Type · Notes"}],[{"k":"text","text":"`system` · no · string · System prompt"}],[{"k":"text","text":"`prompt` · yes · string · Initial user message (same field name as `infer:` · consistent)"}],[{"k":"text","text":"`model` · no · string · Override workflow default · `<provider>/<name>`"}],[{"k":"text","text":"`tools` · no · array · Tool whitelist · glob patterns · **default-deny** · if absent the agent gets NO tools (pure conversation · least-privilege). Grant explicitly."}],[{"k":"text","text":"`skills` · no · array · [Agent Skill](https://agentskills.io) file paths (each an agentskills.io-shape `SKILL.md`) · **explicit static paths only** — no globs, no `\u0024{{ }}` templates (the `permits:` explicitness law) · loaded at **compose time**, **inside `permits.fs.read`** (the text reaches the model), and injected into the system context (§Agent Skills below)"}],[{"k":"text","text":"`max_turns` · no · integer · Loop limit · default 10"}],[{"k":"text","text":"`max_tokens_total` · no · integer · Cumulative token budget · default engine-configurable"}],[{"k":"text","text":"`temperature` · no · number 0-2 · Sampling temperature"}],[{"k":"text","text":"`schema` · no · object · raw JSON Schema · validates the agent's **final message** as structured output (same contract as `infer.schema:` · the out-of-core hatch — the typed door is `returns:` · [09](./09-types.md)) · `.output` becomes the matching object"}]]},{"k":"h","depth":3,"text":"Loop semantics","id":"loop-semantics"},{"k":"p","inline":[{"k":"text","text":"The agent loops · model response → if tool calls present, execute tools → feed results back to model → repeat. The loop terminates when ·"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Model returns a final response with no tool calls, OR"}],[{"k":"code","text":"max_turns"},{"k":"text","text":" reached, OR"}],[{"k":"code","text":"max_tokens_total"},{"k":"text","text":" exhausted, OR"}],[{"k":"text","text":"A tool returns the canonical completion sentinel "},{"k":"code","text":"nika:done"},{"k":"text","text":" (the builtin tool · see "},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":")"}]]},{"k":"p","inline":[{"k":"code","text":"nika:done"},{"k":"text","text":" is "},{"k":"strong","text":"valid only inside an `agent:` loop's tool whitelist"},{"k":"text","text":": it is\nthe loop-completion sentinel. Calling "},{"k":"code","text":"nika:done"},{"k":"text","text":" from a standalone "},{"k":"code","text":"invoke:"},{"k":"text","text":"\ntask (outside any agent loop) is an error ("},{"k":"code","text":"NIKA-BUILTIN-DONE-001"},{"k":"text","text":"). The\nsentinel has no meaning without a loop to terminate. "},{"k":"code","text":"nika:done"},{"k":"text","text":" accepts an\noptional "},{"k":"strong","text":"`result:`"},{"k":"text","text":" arg (any JSON value) · when present the task's\n"},{"k":"code","text":".output"},{"k":"text","text":" is that value (and "},{"k":"code","text":"schema:"},{"k":"text","text":" validates IT) · when absent "},{"k":"code","text":".output"},{"k":"text","text":"\nis the final assistant message (string)."}]},{"k":"p","inline":[{"k":"text","text":"The agent may also grant itself "},{"k":"strong","text":"`nika:compose`"},{"k":"text","text":", a second loop-only\nbuiltin (also valid ONLY inside an "},{"k":"code","text":"agent:"},{"k":"text","text":" whitelist · standalone is\n"},{"k":"code","text":"NIKA-BUILTIN-COMPOSE-001"},{"k":"text","text":"). It lets the model "},{"k":"strong","text":"self-check a workflow it is\ndrafting"},{"k":"text","text":": pass a "},{"k":"code","text":"workflow_yaml"},{"k":"text","text":" string, get the full "},{"k":"code","text":"nika check"},{"k":"text","text":" verdict\nback (conformance + secret-flow + permits + the termination/cost certificate)\nas the tool result. It "},{"k":"strong","text":"never executes"},{"k":"text","text":" the draft: verification yields an\nartifact + its certificate, and running it stays a separate, gated decision.\nThe teaching shape is\n"},{"k":"link","text":"`examples/15-compose-self-check.nika.yaml`","href":"../examples/15-compose-self-check.nika.yaml"},{"k":"text","text":"\n("},{"k":"code","text":"nika:done"},{"k":"text","text":" first so "},{"k":"code","text":"mock/echo"},{"k":"text","text":" closes at turn one). See\n"},{"k":"link","text":"stdlib/builtins-v0.1.md","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" §"},{"k":"code","text":"nika:compose"},{"k":"text","text":".\nDo not confuse this loop intrinsic with parent→child composition\n("},{"k":"code","text":"invoke: { workflow: }"},{"k":"text","text":" · "},{"k":"link","text":"14","href":"./14-composition.md"},{"k":"text","text":" · lesson 10)."}]},{"k":"p","inline":[{"k":"strong","text":"Termination outcomes (normative)"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Case 1 or 4 (natural completion · "},{"k":"code","text":"nika:done"},{"k":"text","text":") → "},{"k":"code","text":"status: success"},{"k":"text","text":"."}],[{"k":"text","text":"Case 2 ("},{"k":"code","text":"max_turns"},{"k":"text","text":" reached) → "},{"k":"strong","text":"`status: failure`"},{"k":"text","text":" · "},{"k":"code","text":"NIKA-AGENT-001"},{"k":"text","text":" ·\n"},{"k":"code","text":"budget_error"},{"k":"text","text":" · the last assistant message is preserved at\n"},{"k":"code","text":"error.details.partial_output"},{"k":"text","text":" (a budget that runs out did NOT produce the\nasked-for result: failing loudly beats returning an unfinished answer ·\nrecover the partial explicitly via "},{"k":"code","text":"on_error:"},{"k":"text","text":" if it is acceptable)."}],[{"k":"text","text":"Case 3 ("},{"k":"code","text":"max_tokens_total"},{"k":"text","text":" exhausted) → same shape · "},{"k":"code","text":"NIKA-AGENT-002"},{"k":"text","text":"."}]]},{"k":"p","inline":[{"k":"strong","text":"Tool-call errors inside the loop are fed back, not fatal"},{"k":"text","text":" · a failing tool\ncall returns its typed error to the MODEL as the tool result (the standard\nagentic convention: the model sees the failure and adapts) · the loop\ncontinues against its budgets. The ONE exception · a "},{"k":"code","text":"security_error"},{"k":"text","text":"\n(whitelist violation "},{"k":"code","text":"NIKA-SEC-002"},{"k":"text","text":" · blocklist) "},{"k":"strong","text":"fails the task\nimmediately"},{"k":"text","text":": security boundaries are not negotiation material for a model."}]},{"k":"h","depth":3,"text":"Tool whitelist · glob semantics","id":"tool-whitelist--glob-semantics"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"tools:"},{"k":"text","text":" whitelist uses "},{"k":"strong","text":"gitignore-style globs"},{"k":"text","text":" for matching ·"}]},{"k":"code","lang":"yaml","text":"tools:\n  - \"nika:read\"                  # exact match\n  - \"nika:*\"                     # any nika builtin\n  - \"mcp:browser/*\"              # any tool from the `browser` MCP server\n  - \"mcp:postgres/query\"         # exact match · postgres query only"},{"k":"p","inline":[{"k":"text","text":"Match rules (canonical) ·"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"*"},{"k":"text","text":" matches any sequence of characters EXCEPT the path separator "},{"k":"code","text":"/"},{"k":"text","text":" (so "},{"k":"code","text":"mcp:browser/*"},{"k":"text","text":" matches "},{"k":"code","text":"mcp:browser/navigate"},{"k":"text","text":" but not "},{"k":"code","text":"mcp:browser/tab/open"},{"k":"text","text":")"}],[{"k":"code","text":"**"},{"k":"text","text":" matches any sequence including "},{"k":"code","text":"/"},{"k":"text","text":" (rare · use sparingly)"}],[{"k":"text","text":"The namespace colon is never crossed by "},{"k":"code","text":"*"},{"k":"text","text":" (so "},{"k":"code","text":"nika:*"},{"k":"text","text":" never matches an "},{"k":"code","text":"mcp:"},{"k":"text","text":" tool)"}],[{"k":"text","text":"Order matters · later rules override earlier rules"}],[{"k":"text","text":"Negation via "},{"k":"code","text":"!"},{"k":"text","text":" prefix · "},{"k":"code","text":"tools: [\"mcp:browser/*\", \"!mcp:browser/navigate\"]"}]]},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine MUST implement these glob semantics canonically · NOT engine-specific. This is a portability invariant."}]},{"k":"p","inline":[{"k":"text","text":"The task output is the final model response."}]},{"k":"h","depth":3,"text":"Agent Skills · `skills:`","id":"agent-skills--skills"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"skills:"},{"k":"text","text":" field makes the agent a "},{"k":"strong","text":"consumer"},{"k":"text","text":" of the\n"},{"k":"link","text":"Agent Skills","href":"https://agentskills.io"},{"k":"text","text":" format — the same "},{"k":"code","text":"SKILL.md"},{"k":"text","text":" shape\n"},{"k":"code","text":"nika init"},{"k":"text","text":" already produces. Each entry is an "},{"k":"strong","text":"explicit file path"},{"k":"text","text":" to a\nskill file: a markdown document opening with a YAML frontmatter block\n("},{"k":"code","text":"---"},{"k":"text","text":" fences) that carries a non-empty "},{"k":"code","text":"name"},{"k":"text","text":" and "},{"k":"code","text":"description"},{"k":"text","text":"; the\nmarkdown body after the closing fence is the skill's instructions. Other\nfrontmatter keys ("},{"k":"code","text":"license"},{"k":"text","text":" · "},{"k":"code","text":"metadata"},{"k":"text","text":" · client-specific fields) are the\nskill author's surface — a consumer MUST tolerate them."}]},{"k":"code","lang":"yaml","text":"review:\n    agent:\n      system: \"You are a code reviewer.\"\n      prompt: \"Review the diff · \u0024{{ tasks.diff.output }}\"\n      skills:\n        - \".agents/skills/code-review/SKILL.md\"\n        - \"docs/skills/security-pass/SKILL.md\"\n      tools: [\"nika:read\"]"},{"k":"p","inline":[{"k":"strong","text":"Resolution (normative)"},{"k":"text","text":" · paths are "},{"k":"strong","text":"static"},{"k":"text","text":" — no globs, no\n"},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":" templates (the same explicitness law as "},{"k":"code","text":"permits:"},{"k":"text","text":"; a template\nor a glob in a skill path is a parse-time "},{"k":"code","text":"NIKA-AGENT-003"},{"k":"text","text":" — it can\nnever resolve). Relative paths resolve from the "},{"k":"strong","text":"directory of the\nworkflow file that names them"},{"k":"text","text":", exactly like a composed "},{"k":"code","text":"workflow:"},{"k":"text","text":"\nchild target ("},{"k":"link","text":"14","href":"./14-composition.md"},{"k":"text","text":") — never from the working\ndirectory ("},{"k":"code","text":"nika check sub/wf.nika.yaml"},{"k":"text","text":" run from the repo root reads\n"},{"k":"code","text":"sub/skills/…"},{"k":"text","text":", whatever the operator's cwd). The files are read at\n"},{"k":"strong","text":"compose time"},{"k":"text","text":" — before the run starts, by the composition layer,\nnever mid-loop by the runtime."}]},{"k":"p","inline":[{"k":"strong","text":"Skill reads are INSIDE `permits.fs.read`."},{"k":"text","text":" A skill file is not\nprogram text the way a composed child is: a child's "},{"k":"em","text":"effects"},{"k":"text","text":" are\nre-judged under the parent's boundary and its text goes nowhere, while\na skill's "},{"k":"em","text":"text"},{"k":"text","text":" is carried into the model's context — a file read whose\nbytes reach a destination, the same class as "},{"k":"code","text":"nika:read"},{"k":"text","text":". So the path\nas written must be admitted by the workflow's declared read boundary\n(the lexical "},{"k":"code","text":"permits.fs.read"},{"k":"text","text":" match every fs effect uses):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"the workflow declares · a `skills:` entry is · code"}],[{"k":"text","text":"no `permits:` block at all · an effect under an absent block · zero authority · `NIKA-AUTH-006`"}],[{"k":"text","text":"a `permits:` block whose `fs.read` does not admit the path · outside the declared boundary · `NIKA-SEC-004`"}],[{"k":"text","text":"a boundary that admits the path · the file is missing or unreadable · unresolvable at compose time · `NIKA-AGENT-003`"}],[{"k":"text","text":"a boundary that admits the path · the file is not a valid Agent Skill · resolvable, malformed · `NIKA-AGENT-004`"}],[{"k":"text","text":"a boundary that admits the path · a well-shaped `SKILL.md` · admitted · injected · —"}]]},{"k":"p","inline":[{"k":"text","text":"The boundary is judged "},{"k":"strong","text":"before"},{"k":"text","text":" the read: an ungranted path is never\nopened, so the refusal cannot leak whether the file exists or how its\nfirst line is shaped. (Measured on the shipped 0.108.0, 2026-08-12:\nunder "},{"k":"code","text":"permits: {}"},{"k":"text","text":" — the declared zero — a skill path of "},{"k":"code","text":"/etc/hosts"},{"k":"text","text":"\nwas read and the engine reported on its content while the permits and\ntrifecta rungs stayed green. The earlier text of this paragraph, «\nskill reads are outside "},{"k":"code","text":"permits.fs"},{"k":"text","text":" », was the sentence that\nauthorized it; it is retired here.)"}]},{"k":"p","inline":[{"k":"strong","text":"Injection (normative)"},{"k":"text","text":" · the resolved skills join the agent's system\ncontext as ONE deterministic section, appended after the authored\n"},{"k":"code","text":"system:"},{"k":"text","text":" (or standing alone when "},{"k":"code","text":"system:"},{"k":"text","text":" is absent) ·"}]},{"k":"code","lang":"text","text":"<authored system>\n\n## Skills\n\n### <frontmatter name>\n\n<frontmatter description>\n\n<markdown body · trimmed>"},{"k":"p","inline":[{"k":"text","text":"— one "},{"k":"code","text":"###"},{"k":"text","text":" block per skill, in "},{"k":"code","text":"skills:"},{"k":"text","text":" source order. Same inputs,\nsame bytes (provider-cache-friendly · reproducible transcripts)."}]},{"k":"p","inline":[{"k":"strong","text":"check≡run"},{"k":"text","text":" · "},{"k":"code","text":"skills:"},{"k":"text","text":" is fully validated statically. "},{"k":"code","text":"nika check"},{"k":"text","text":"\nfails a workflow whose skill paths lie outside the declared read\nboundary ("},{"k":"code","text":"NIKA-AUTH-006"},{"k":"text","text":" under an absent block · "},{"k":"code","text":"NIKA-SEC-004"},{"k":"text","text":" under\none that does not admit the path), do not resolve ("},{"k":"code","text":"NIKA-AGENT-003"},{"k":"text","text":" ·\nthe file is missing/unreadable · a template or glob) or whose files are\nnot valid Agent Skills ("},{"k":"code","text":"NIKA-AGENT-004"},{"k":"text","text":" · no/unterminated/non-mapping\nfrontmatter · missing/empty "},{"k":"code","text":"name"},{"k":"text","text":" or "},{"k":"code","text":"description"},{"k":"text","text":") — see\n"},{"k":"link","text":"05-errors.md","href":"./05-errors.md"},{"k":"text","text":". A run refuses on the same findings\nbefore any token is spent. The skill TEXT also joins the referencing\ntask's resume identity: editing a "},{"k":"code","text":"SKILL.md"},{"k":"text","text":" re-runs the task (the same\nlaw as an edited prompt — a resume never serves output produced under a\ndifferent skill)."}]},{"k":"h","depth":3,"text":"Conformance","id":"conformance-3"},{"k":"p","inline":[{"k":"text","text":"The engine MUST ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Honor the "},{"k":"code","text":"tools"},{"k":"text","text":" whitelist · reject tool calls not in the whitelist · "},{"k":"strong","text":"default-deny when `tools:` is absent"},{"k":"text","text":" (the agent gets no tools · least-privilege)"}],[{"k":"text","text":"Enforce "},{"k":"code","text":"max_turns"},{"k":"text","text":" and "},{"k":"code","text":"max_tokens_total"},{"k":"text","text":" budgets · terminate on exhaustion"}],[{"k":"text","text":"Detect the "},{"k":"code","text":"nika:done"},{"k":"text","text":" completion sentinel and exit gracefully"}],[{"k":"text","text":"Return the final model response as task output"}],[{"k":"text","text":"Resolve "},{"k":"code","text":"skills:"},{"k":"text","text":" at compose time · judge every path against the declared "},{"k":"code","text":"permits.fs.read"},{"k":"text","text":" boundary BEFORE opening it ("},{"k":"code","text":"NIKA-AUTH-006"},{"k":"text","text":" under an absent block · "},{"k":"code","text":"NIKA-SEC-004"},{"k":"text","text":" outside a declared one) · inject the "},{"k":"code","text":"## Skills"},{"k":"text","text":" section in source order exactly as specified above · fail statically ("},{"k":"code","text":"NIKA-AGENT-003"},{"k":"text","text":"/"},{"k":"code","text":"NIKA-AGENT-004"},{"k":"text","text":") on a missing or invalid skill file — never start a run with a half-composed context"}]]},{"k":"hr"},{"k":"h","depth":2,"text":"Forward-compat","id":"forward-compat"},{"k":"p","inline":[{"k":"text","text":"The 4 verb names are "},{"k":"strong","text":"ratified by the [v1 constitution](../design/v1-constitution.md)"},{"k":"text","text":", and the count is "},{"k":"strong","text":"4, absolute"},{"k":"text","text":" — under the constitutional hierarchy of "},{"k":"strong","text":"three atomic calls and one bounded controller"},{"k":"text","text":": call a model once ("},{"k":"code","text":"infer"},{"k":"text","text":"), apply a typed callable once ("},{"k":"code","text":"invoke"},{"k":"text","text":"), run a host process once ("},{"k":"code","text":"exec"},{"k":"text","text":"), and orchestrate a bounded sequence of the atomic calls ("},{"k":"code","text":"agent"},{"k":"text","text":"). Every other capability is either an "},{"k":"strong","text":"invoke-able callable"},{"k":"text","text":" (an HTTP fetch → "},{"k":"code","text":"invoke: nika:fetch"},{"k":"text","text":" · a database query → "},{"k":"code","text":"invoke: mcp:postgres/query"},{"k":"text","text":" · a file write → "},{"k":"code","text":"invoke: nika:write"},{"k":"text","text":" · cognitive recall → "},{"k":"code","text":"invoke: nika:connectome/recall"},{"k":"text","text":") or a "},{"k":"strong","text":"DAG control-flow construct"},{"k":"text","text":" (iteration → "},{"k":"code","text":"for_each"},{"k":"text","text":" · branching → "},{"k":"code","text":"when"},{"k":"text","text":"). There is no "},{"k":"code","text":"nika: v2"},{"k":"text","text":" — ever: while the reference engine is pre-1.0 a verb change would be a break INSIDE "},{"k":"code","text":"v1"},{"k":"text","text":" (per the "},{"k":"link","text":"pre-1.0 stability contract","href":"./00-overview.md#pre-10-stability-contract"},{"k":"text","text":"), and after engine 1.0.0 the verb set is frozen with the rest of the grammar, so a fifth verb is effectively never."}]},{"k":"h","depth":3,"text":"The closure argument · why no case forces a 5th verb","id":"the-closure-argument--why-no-case-forces-a-5th-verb"},{"k":"p","inline":[{"k":"text","text":"Every candidate operation decomposes along "},{"k":"strong","text":"two orthogonal axes"},{"k":"text","text":" ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"WHO executes"},{"k":"text","text":": the execution model. There are exactly four · model\ninference ("},{"k":"code","text":"infer"},{"k":"text","text":") · OS process ("},{"k":"code","text":"exec"},{"k":"text","text":") · dispatch-a-call-and-await-its-\nresult ("},{"k":"code","text":"invoke"},{"k":"text","text":") · model-driven loop over tools ("},{"k":"code","text":"agent"},{"k":"text","text":"). Anything with a\nrequest/response shape (however exotic the backend) is by construction\nthe "},{"k":"code","text":"invoke"},{"k":"text","text":" model."}],[{"k":"strong","text":"WHEN it runs"},{"k":"text","text":": ordering. Edges ("},{"k":"code","text":"with:"},{"k":"text","text":" data · "},{"k":"code","text":"after:"},{"k":"text","text":" control) ·\nconditions ("},{"k":"code","text":"when"},{"k":"text","text":") · iteration ("},{"k":"code","text":"for_each"},{"k":"text","text":") · time-bounds ("},{"k":"code","text":"timeout"},{"k":"text","text":") ·\nrecovery ("},{"k":"code","text":"retry"},{"k":"text","text":" · "},{"k":"code","text":"on_error"},{"k":"text","text":" · an "},{"k":"code","text":"unwind"},{"k":"text","text":" task). Ordering never executes\nanything: it is DAG-side, or host-side when it concerns "},{"k":"em","text":"starting"},{"k":"text","text":" a run\nat all."}]]},{"k":"p","inline":[{"k":"text","text":"The recurring « doesn't X need a verb? » cases, stress-tested ·"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Candidate · Axis · Resolution"}],[{"k":"text","text":"**wait-for-human** (approval gate) · WHO · a call that resolves when a human answers · a **tool** · request/response with a long latency · `invoke:` model · **already shipped** as `nika:prompt` (blocking confirm · [stdlib/builtins-v0.1.md](../stdlib/builtins-v0.1.md))"}],[{"k":"text","text":"**sleep / delay** inside a run · WHO · a call that resolves after a duration · a **tool** · **already shipped** as `nika:wait` (relative `duration:` XOR absolute `until:`) · NOT a verb · nothing is executed, a result (elapsed) is awaited"}],[{"k":"text","text":"**cron / schedule** (start a run at time T) · neither · it precedes the run · **host concern** · a workflow describes a run, not its triggering · explicitly out-of-scope ([08](./08-out-of-scope.md))"}],[{"k":"text","text":"**streaming between tasks** · WHEN · changes what an *edge* delivers · a **DAG-edge semantic**, not an execution model · out-of-scope v0.1 · an additive edge attribute later · never a verb"}],[{"k":"text","text":"**sub-workflow call** · WHO · dispatch-and-await a run · a **tool** (workflow-as-tool · see [08](./08-out-of-scope.md) §composition) · the `invoke` model again"}]]},{"k":"p","inline":[{"k":"text","text":"A 5th verb would have to name an execution model that is none of\ncall-with-result, process, inference, or loop, and every concrete candidate\ninspected since the 4-verb lock (D-2026-05-22-N18) has resolved to a tool\n(WHO · request/response) or an ordering construct (WHEN). That is the\nclosure: "},{"k":"strong","text":"the verb set is closed under decomposition into WHO × WHEN."}]},{"k":"p","inline":[{"k":"text","text":"Field additions to each verb are "},{"k":"strong","text":"additive"},{"k":"text","text":" within "},{"k":"code","text":"v1"},{"k":"text","text":" (feature-detected · no version marker in the file at all). Field removal NEVER happens at v1."}]},{"k":"p","inline":[{"k":"text","text":"A v0.1-compliant engine that encounters an unknown field on a verb may ·"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Reject"},{"k":"text","text":" with a clear error (strict mode · default for tests)"}],[{"k":"strong","text":"Warn + ignore"},{"k":"text","text":" the field (lenient mode · default for production)"}]]},{"k":"p","inline":[{"k":"text","text":"Engine config picks which mode."}]},{"k":"hr"},{"k":"p","inline":[{"k":"text","text":"🦋 "},{"k":"em","text":"Next · [03 · DAG shape](./03-dag.md)"}]}]

the spec · 02

The 4 verbs

Every task in a Nika workflow binds to **exactly one** of 4 verbs.

02 · The 4 verbs #

Every task in a Nika workflow binds to exactly one of 4 verbs. A verb is a distinct native execution model the engine itself implements: call a model, run a process, dispatch a tool, drive an agentic loop. That is the whole operation space.Everything callable (fetching a URL, a database query, a file write, cognitive recall) is a tool reached through invoke:. Everything about ordering (iteration, branching) is a DAG construct (for_each · when). The 4 verbs never change; tools and the stdlib grow freely.

The 4 verbs · summary #

Verb · What it does · Stdlib it consumes
`infer:` · Single LLM call · text · structured · vision · thinking · providers
`exec:` · Shell command with sandboxing · (none · pure effect)
`invoke:` · Call a builtin tool OR an MCP tool · builtins · MCP servers
`agent:` · Multi-turn agentic loop with tool calls · providers · builtins · MCP

A task must specify exactly one of these. Multiple verbs on a single task is a validation error.

Where did `fetch` go? Fetching a URL is calling a tool, not a distinct execution model, so it is the nika:fetch builtin, reached through invoke: (the extract modes become its mode argument). Same reason a DB query (invoke: mcp:postgres/query) or a file write (invoke: nika:write) is not its own verb. See stdlib/builtins-v0.1.md.

What `${{ tasks.<id>.output }}` holds · per verb #

Every task also exposes the full result record (.status · .error · .started_at · .ended_at · .duration_ms · 04 §task output reference). The .output shape depends on the verb (know this before you bind downstream) ·

Verb · `.output` is · Structured when
`infer:` · the model's reply · **string** · `schema:` set → **object** matching it
`exec:` · **stdout string** (default) · `capture: structured` → `{ stdout, stderr, exit_code }`
`invoke:` · the **tool's response** (tool-defined · string · object · or bytes) · per builtin / MCP tool schema · bytes are tool-determined (MCP image content · binary read) · flow opaquely · see 04 §value rendering
`agent:` · the loop's **final message** · string · `schema:` set → **object** matching it

`infer:` · LLM call #

A single LLM call. The result is the model's response.

Minimal #

yaml

1greet:2    ◇infer:3      prompt: "Say hello in French"

Full #

yaml

1research:2    ◇infer:3      prompt: "Research Rust async runtimes 2026 in 5 paragraphs"4      system: "You are a senior software architect."5      model: mistral/mistral-large         # override default · <provider>/<name>6      temperature: 0.37      max_tokens: 20008      schema:                            # optional · structured output9        type: object10        required: [summary, paragraphs]11        properties:12          summary: { type: string }13          paragraphs: { type: array, items: { type: string } }14      thinking:                          # optional · extended thinking15        enabled: true16        budget_tokens: 400017      vision:                            # optional · vision input18        - source: file19          path: "./diagram.png"

Fields #

Field · Required · Type · Notes
`prompt` · yes · string · User prompt · may use `${{ ... }}` substitution
`system` · no · string · System prompt
`model` · no · string · Override workflow default · `<provider>/<name>` · see stdlib/providers-v0.1.md
`temperature` · no · number 0-2 · Sampling temperature
`max_tokens` · no · integer · Max output tokens · provider-dependent default
`schema` · no · object · raw JSON Schema · structured output validation — the **out-of-core hatch**; the typed door is task-level `returns:` ([09](./09-types.md) · both on one task = `NIKA-TYPE-003`). Numeric facts (`0|1|3`, counts, coded levels) are `type: integer` with a numeric `enum` — never `enum: ["0","1","3"]`. Models emit JSON numbers; a string-digit enum can reject the call before coerce (reference engine hint `digit-string-enum`). The model extracts facts; `nika:jq` or `nika:decide` is the law ([11](./11-decision.md) · `examples/13-extract-then-law.nika.yaml`)
`thinking` · no · object · Extended thinking · `{ enabled, budget_tokens }`
`vision` · no · array · Image inputs · each `{ source: file

Conformance #

A v0.1-compliant engine MUST ·

Call the configured provider with the given prompt + system + parameters
Return the model's response as the task output
Validate the response against schema if present · MAY auto-retry validation failures internally before surfacing NIKA-INFER-002 (engine-configurable · the same rule as 05 §structured output)
Reject any unknown field with a clear error (NIKA-PARSE-005) — the choice this line used to leave open is closed by 07 §unknown key: a key can REMOVE authority, so accept-and-warn fails open

Subscription harness access (normative) #

An engine MAY execute infer: through a user's authenticated CLI seat instead of a provider API key, but only after an infer-grade meet proves all four properties for that adapter and this task:

single_turn — one request produces one terminal answer;
no_implicit_tools — an accepted answer contains no tool, command, file, network, or permission event;
structured_output — the adapter's level is at least the task's need (plain text, JSON, or JSON Schema);
model_identity — the requested model identity is observable at command construction and is recorded without being relabelled as the model that answered.

The meet is evidence, not a product-name allowlist. A seat with no attestation, or one failing any conjunct, MUST be refused before inference with a witness that names the failed property. It MUST NOT fall back to a native provider or to the seat's agentic loop. In particular, an ACP-capable agent seat is not thereby infer-grade.

For an accepted seat run, the receipt MUST record the seat id and the requested model. It MUST leave the responding model absent unless the adapter reports that fact explicitly; request identity is never promoted into response identity. Subscription inference has no numeric token count and no numeric price in the Nika receipt or budget. Its budget lane is subscription quota, never 0 USD. An adapter may read a terminal usage object as protocol-completeness evidence, but MUST NOT project its numeric meters into the Nika receipt.

A non-executing preview that accepts an access pin MUST apply the same access admission meet as a live run and record the requested pin plus each requested model. The same invalid or unattested pin MUST refuse with the same access code. For an admitted subscription seat, the preview MUST name subscription quota and MUST NOT display a numeric USD or token meter.

`exec:` · shell command #

Run a shell command. The result is the command's stdout (default) or a structured output.

Minimal #

yaml

1build:2    ▷exec:3      command: ["cargo", "build", "--release"]

Full #

yaml

1test:2    timeout: "60s"                   # task-level (applies to any verb · Go duration · see 03-dag)3    ▷exec:4      command: ["cargo", "test", "--workspace", "--lib"]5      cwd: "./engine"6      env:7        RUST_LOG: "debug"8      stdin: "${{ inputs.input_data }}"9      capture: structured            # stdout | stderr | structured | combined

Fields #

Field · Required · Type · Notes
`command` · one of · array · **argv** — `["prog", "arg", …]` → direct `execve`, **NO shell** · each element substituted independently — an interpolated `${{ }}` value can never break out of its argument (see Security). Exactly one of `command` | `shell`.
`shell` · one of · string · **The explicit shell door** — one line run via `/bin/sh -c` · pipes · redirects · globs. The blocklist applies HERE; interpolating untrusted values here is the author's own risk, visibly. Exactly one of `command` | `shell`. *(D1 · #75: semantics never fork on a YAML type — the field name carries the meaning. The old string `command:` is rejected at parse.)*
`cwd` · no · string · Working directory · default = engine's cwd
`env` · no · object · OS environment variables for **this subprocess** · key→value map · applied over the COMPOSED environment ([01 §permits](./01-envelope.md#permits--optional--the-declared-capability-boundary) env · never inherited)
`stdin` · no · string · Stdin data · may use `${{ ... }}`
`capture` · no · enum · `stdout` (default) · `stderr` · `combined` · `structured` (= `{ stdout, stderr, exit_code }`) — the **source**
`decode` · no · enum · `text` (default) · `json` · `jsonl` · `bytes` — how the captured **string** becomes a value ([09 §decode](./09-types.md#decode--how-exec-bytes-become-a-value-normative)) · illegal with `capture: structured` (`NIKA-PARSE-025` — that capture already IS an object) · a non-parsing stream settles the task `failure` inside `on_error:` scope

`exec.env` is a subprocess field, never an envelope block: no top-level key of that family survives — the pre-flip envelope env: block is dead (NIKA-VALUES-002) and the top-level config: block died with the envelope nuke, so exec.env is the OS environment of this subprocess and nothing else. Nothing is auto-connected. To pass a workflow value into the process, do it explicitly: env: { API_BASE: "${{ inputs.api_base }}" }. The subprocess environment itself is COMPOSED, never inherited (NEP-0005 · 01 §permits): the runner env floor ∪ the permits.env: passthrough ∪ this map, minus the dangerous-name floor · an ambient engine variable reaches the child only through a declared permits.env: name.

timeout and retry are task-level fields (see 03-dag.md): they apply uniformly to every verb, so they are not repeated inside exec:.

Security #

A v0.1-compliant engine MUST ·

Honor the two exec bodies · command: (array) runs through execve with NO shell: command[0] is the program, the rest are argv passed verbatim, each element substituted independently. shell: (string) runs through /bin/sh -c — the shell-feature path (pipes · redirects · globs). Exactly one of the two; a string command: (the pre-0.103 implicit-shell form) is rejected at parse (NIKA-PARSE · validation_error).
Implement a shell blocklist for dangerous commands on shell: (see reference impl nika-policy for canonical list · 100+ patterns including rm -rf / · chmod 777 · curl … | sh · etc.)
Reject blocklist matches with a clear error
Honor timeout with a hard kill (Go-duration string · see 03-dag)
Sandbox cwd if configured (engine-specific)

The argv form is the STRUCTURAL fix for command injection: prefer it. A ${{ }}-interpolated value in the STRING form is shell-parsed: shell: "process ${{ item }}" with item == "; rm -rf /" is a classic injection, and the blocklist is a detector (best-effort), not a guarantee. The ARRAY form removes the shell entirely: command: ["process", "${{ item }}"] passes item as ONE argv element no matter what it contains; there is no shell to parse it. Rule of thumb · any command carrying a task output, a `var`, or any value not authored inline → use the array form. nika check warns (one-obvious-way) when an interpolated value lands in a string command. The string form stays first-class for genuine shell pipelines ("cat x | grep y > z"). That is what /bin/sh -c is for.

Conformance #

The engine MUST ·

Run the STRING command via the OS shell (/bin/sh -c on Unix · cmd /c on Windows, OR a sandboxed equivalent) · run the ARRAY command via execve with no shell
Capture stdout/stderr as configured
Return exit code in structured capture mode
Fail the task on non-zero exit (NIKA-EXEC-001 · process_error) in stdout / stderr / combined capture modes (unless on_error: recovers · 05), EXCEPT `capture: structured`, where a non-zero exit is data, not failure · the task succeeds and exit_code is the workflow's to branch on (when: ${{ tasks.test.output.exit_code != 0 }}) · the one-obvious-way split · default modes for « must succeed » · structured for « inspect the outcome »

`invoke:` · builtin or MCP tool call #

Call a builtin (nika: namespace) or an MCP tool (mcp: namespace). The result is the tool's response.

Tool reference grammar (canonical) #

text

1<namespace>:<path>          one colon introduces the namespace · `/` separates the path23nika:fetch                  builtin · HTTP + extraction (used to be a verb)4nika:write                  builtin · flat name5nika:connectome/recall      builtin · grouped path6mcp:browser/navigate        MCP · server `browser` · tool `navigate`7mcp:postgres/query          MCP · server `postgres` · tool `query`8mcp:my-server/do_thing      MCP · server names admit kebab-case · tools admit snake_case

The mcp: form requires the slash: mcp:postgres alone (no tool) is a parse error (NIKA-PARSE · validation_error) · server segment [a-z][a-z0-9-]* · tool segment [A-Za-z0-9_-]+ (tool names are the MCP server's to define).

One rule everywhere · the colon marks the namespace boundary (exactly once), the slash separates the path within it. No ::, no mixed ./:. Globs are clean · nika:* · nika:connectome/* · mcp:browser/*.

The namespace set is CLOSED at v1 · nika: and mcp: are the only two · any other namespace (custom:thing · x:tool) is rejected at parse time (NIKA-PARSE · validation_error). A third namespace would be an additive spec minor. It never appears silently.

Builtin call #

yaml

1read_config:2    ◆invoke:3      tool: "nika:read"4      args:5        path: "./config.yaml"

See stdlib/builtins-v0.1.md for the canonical builtin list (28 builtins in v0.1).

Grouped paths are grammar-legal · v0.1 ships none. The reference grammar admits nika:<group>/<tool> (the nika:connectome/recall illustration above is the reserved FUTURE shape), but the v0.1 builtin set contains only flat names · a grouped nika: path is rejected against the closed 23 set today (NIKA-INVOKE-001). The seam exists so the Connectome tools land additively · zero workflow-shape change.

MCP call #

yaml

1query_db:2    ◆invoke:3      tool: "mcp:postgres/query"4      args:5        sql: "SELECT * FROM users WHERE id = $1"6        params: ["${{ inputs.user_id }}"]

The MCP server postgres must be configured in the engine's MCP server registry.

Fields #

Field · Required · Type · Notes
`tool` · yes · string · Tool identifier · `nika:<path>` OR `mcp:<server>/<tool>`
`args` · no · object · Tool arguments · schema is tool-specific

Conformance #

The engine MUST ·

Resolve the tool identifier to its implementation (builtin or MCP server)
Reject unknown tools with a clear error
Pass args to the tool · validate against tool's schema if known
Return the tool's response as task output

`agent:` · multi-turn agentic loop #

Run an agentic loop · the model + a set of tools · iterating until completion or budget exhausted.

Minimal #

yaml

1research:2    ✦agent:3      system: "You are a research assistant."4      prompt: "Research the topic · ${{ inputs.topic }}"5      tools: ["nika:fetch"]             # default-deny · grant explicitly

Full #

yaml

1research:2    ✦agent:3      system: "You are a research assistant. Use tools to gather info."4      prompt: "Research the topic · ${{ inputs.topic }} · and produce a markdown brief"5      model: mistral/mistral-large6      tools:                            # whitelist · default-deny (no tools if omitted)7        - "nika:fetch"8        - "nika:write"9        - "mcp:browser/*"               # all tools from browser MCP server10      skills:                           # Agent Skills · SKILL.md paths (agentskills.io shape)11        - ".agents/skills/nika-authoring/SKILL.md"12      max_turns: 2013      max_tokens_total: 10000014      temperature: 0.315      schema:                           # optional · validate the final message as structured output16        type: object17        required: [findings]18        properties:19          findings: { type: array, items: { type: string } }

Fields #

Field · Required · Type · Notes
`system` · no · string · System prompt
`prompt` · yes · string · Initial user message (same field name as `infer:` · consistent)
`model` · no · string · Override workflow default · `<provider>/<name>`
`tools` · no · array · Tool whitelist · glob patterns · **default-deny** · if absent the agent gets NO tools (pure conversation · least-privilege). Grant explicitly.
`skills` · no · array · [Agent Skill](https://agentskills.io) file paths (each an agentskills.io-shape `SKILL.md`) · **explicit static paths only** — no globs, no `${{ }}` templates (the `permits:` explicitness law) · loaded at **compose time**, **inside `permits.fs.read`** (the text reaches the model), and injected into the system context (§Agent Skills below)
`max_turns` · no · integer · Loop limit · default 10
`max_tokens_total` · no · integer · Cumulative token budget · default engine-configurable
`temperature` · no · number 0-2 · Sampling temperature
`schema` · no · object · raw JSON Schema · validates the agent's **final message** as structured output (same contract as `infer.schema:` · the out-of-core hatch — the typed door is `returns:` · [09](./09-types.md)) · `.output` becomes the matching object

Loop semantics #

The agent loops · model response → if tool calls present, execute tools → feed results back to model → repeat. The loop terminates when ·

Model returns a final response with no tool calls, OR
max_turns reached, OR
max_tokens_total exhausted, OR
A tool returns the canonical completion sentinel nika:done (the builtin tool · see stdlib/builtins-v0.1.md)

nika:done is valid only inside an `agent:` loop's tool whitelist: it is the loop-completion sentinel. Calling nika:done from a standalone invoke: task (outside any agent loop) is an error (NIKA-BUILTIN-DONE-001). The sentinel has no meaning without a loop to terminate. nika:done accepts an optional `result:` arg (any JSON value) · when present the task's .output is that value (and schema: validates IT) · when absent .output is the final assistant message (string).

The agent may also grant itself `nika:compose`, a second loop-only builtin (also valid ONLY inside an agent: whitelist · standalone is NIKA-BUILTIN-COMPOSE-001). It lets the model self-check a workflow it is drafting: pass a workflow_yaml string, get the full nika check verdict back (conformance + secret-flow + permits + the termination/cost certificate) as the tool result. It never executes the draft: verification yields an artifact + its certificate, and running it stays a separate, gated decision. The teaching shape is `examples/15-compose-self-check.nika.yaml` (nika:done first so mock/echo closes at turn one). See stdlib/builtins-v0.1.md §nika:compose. Do not confuse this loop intrinsic with parent→child composition (invoke: { workflow: } · 14 · lesson 10).

Termination outcomes (normative) ·

Case 1 or 4 (natural completion · nika:done) → status: success.
Case 2 (max_turns reached) → `status: failure` · NIKA-AGENT-001 · budget_error · the last assistant message is preserved at error.details.partial_output (a budget that runs out did NOT produce the asked-for result: failing loudly beats returning an unfinished answer · recover the partial explicitly via on_error: if it is acceptable).
Case 3 (max_tokens_total exhausted) → same shape · NIKA-AGENT-002.

Tool-call errors inside the loop are fed back, not fatal · a failing tool call returns its typed error to the MODEL as the tool result (the standard agentic convention: the model sees the failure and adapts) · the loop continues against its budgets. The ONE exception · a security_error (whitelist violation NIKA-SEC-002 · blocklist) fails the task immediately: security boundaries are not negotiation material for a model.

Tool whitelist · glob semantics #

The tools: whitelist uses gitignore-style globs for matching ·

yaml

1tools:2  - "nika:read"                  # exact match3  - "nika:*"                     # any nika builtin4  - "mcp:browser/*"              # any tool from the `browser` MCP server5  - "mcp:postgres/query"         # exact match · postgres query only

Match rules (canonical) ·

* matches any sequence of characters EXCEPT the path separator / (so mcp:browser/* matches mcp:browser/navigate but not mcp:browser/tab/open)
** matches any sequence including / (rare · use sparingly)
The namespace colon is never crossed by * (so nika:* never matches an mcp: tool)
Order matters · later rules override earlier rules
Negation via ! prefix · tools: ["mcp:browser/*", "!mcp:browser/navigate"]

A v0.1-compliant engine MUST implement these glob semantics canonically · NOT engine-specific. This is a portability invariant.

The task output is the final model response.

Agent Skills · `skills:` #

The skills: field makes the agent a consumer of the Agent Skills format — the same SKILL.md shape nika init already produces. Each entry is an explicit file path to a skill file: a markdown document opening with a YAML frontmatter block (--- fences) that carries a non-empty name and description; the markdown body after the closing fence is the skill's instructions. Other frontmatter keys (license · metadata · client-specific fields) are the skill author's surface — a consumer MUST tolerate them.

yaml

1review:2    ✦agent:3      system: "You are a code reviewer."4      prompt: "Review the diff · ${{ tasks.diff.output }}"5      skills:6        - ".agents/skills/code-review/SKILL.md"7        - "docs/skills/security-pass/SKILL.md"8      tools: ["nika:read"]

Resolution (normative) · paths are static — no globs, no ${{ }} templates (the same explicitness law as permits:; a template or a glob in a skill path is a parse-time NIKA-AGENT-003 — it can never resolve). Relative paths resolve from the directory of the workflow file that names them, exactly like a composed workflow: child target (14) — never from the working directory (nika check sub/wf.nika.yaml run from the repo root reads sub/skills/…, whatever the operator's cwd). The files are read at compose time — before the run starts, by the composition layer, never mid-loop by the runtime.

Skill reads are INSIDE `permits.fs.read`. A skill file is not program text the way a composed child is: a child's effects are re-judged under the parent's boundary and its text goes nowhere, while a skill's text is carried into the model's context — a file read whose bytes reach a destination, the same class as nika:read. So the path as written must be admitted by the workflow's declared read boundary (the lexical permits.fs.read match every fs effect uses):

the workflow declares · a `skills:` entry is · code
no `permits:` block at all · an effect under an absent block · zero authority · `NIKA-AUTH-006`
a `permits:` block whose `fs.read` does not admit the path · outside the declared boundary · `NIKA-SEC-004`
a boundary that admits the path · the file is missing or unreadable · unresolvable at compose time · `NIKA-AGENT-003`
a boundary that admits the path · the file is not a valid Agent Skill · resolvable, malformed · `NIKA-AGENT-004`
a boundary that admits the path · a well-shaped `SKILL.md` · admitted · injected · —

The boundary is judged before the read: an ungranted path is never opened, so the refusal cannot leak whether the file exists or how its first line is shaped. (Measured on the shipped 0.108.0, 2026-08-12: under permits: {} — the declared zero — a skill path of /etc/hosts was read and the engine reported on its content while the permits and trifecta rungs stayed green. The earlier text of this paragraph, « skill reads are outside permits.fs », was the sentence that authorized it; it is retired here.)

Injection (normative) · the resolved skills join the agent's system context as ONE deterministic section, appended after the authored system: (or standing alone when system: is absent) ·

text

1<authored system>23## Skills45### <frontmatter name>67<frontmatter description>89<markdown body · trimmed>

— one ### block per skill, in skills: source order. Same inputs, same bytes (provider-cache-friendly · reproducible transcripts).

check≡run · skills: is fully validated statically. nika check fails a workflow whose skill paths lie outside the declared read boundary (NIKA-AUTH-006 under an absent block · NIKA-SEC-004 under one that does not admit the path), do not resolve (NIKA-AGENT-003 · the file is missing/unreadable · a template or glob) or whose files are not valid Agent Skills (NIKA-AGENT-004 · no/unterminated/non-mapping frontmatter · missing/empty name or description) — see 05-errors.md. A run refuses on the same findings before any token is spent. The skill TEXT also joins the referencing task's resume identity: editing a SKILL.md re-runs the task (the same law as an edited prompt — a resume never serves output produced under a different skill).

Conformance #

The engine MUST ·

Honor the tools whitelist · reject tool calls not in the whitelist · default-deny when `tools:` is absent (the agent gets no tools · least-privilege)
Enforce max_turns and max_tokens_total budgets · terminate on exhaustion
Detect the nika:done completion sentinel and exit gracefully
Return the final model response as task output
Resolve skills: at compose time · judge every path against the declared permits.fs.read boundary BEFORE opening it (NIKA-AUTH-006 under an absent block · NIKA-SEC-004 outside a declared one) · inject the ## Skills section in source order exactly as specified above · fail statically (NIKA-AGENT-003/NIKA-AGENT-004) on a missing or invalid skill file — never start a run with a half-composed context

Forward-compat #

The 4 verb names are ratified by the [v1 constitution](../design/v1-constitution.md), and the count is 4, absolute — under the constitutional hierarchy of three atomic calls and one bounded controller: call a model once (infer), apply a typed callable once (invoke), run a host process once (exec), and orchestrate a bounded sequence of the atomic calls (agent). Every other capability is either an invoke-able callable (an HTTP fetch → invoke: nika:fetch · a database query → invoke: mcp:postgres/query · a file write → invoke: nika:write · cognitive recall → invoke: nika:connectome/recall) or a DAG control-flow construct (iteration → for_each · branching → when). There is no nika: v2 — ever: while the reference engine is pre-1.0 a verb change would be a break INSIDE v1 (per the pre-1.0 stability contract), and after engine 1.0.0 the verb set is frozen with the rest of the grammar, so a fifth verb is effectively never.

The closure argument · why no case forces a 5th verb #

Every candidate operation decomposes along two orthogonal axes ·

WHO executes: the execution model. There are exactly four · model inference (infer) · OS process (exec) · dispatch-a-call-and-await-its- result (invoke) · model-driven loop over tools (agent). Anything with a request/response shape (however exotic the backend) is by construction the invoke model.
WHEN it runs: ordering. Edges (with: data · after: control) · conditions (when) · iteration (for_each) · time-bounds (timeout) · recovery (retry · on_error · an unwind task). Ordering never executes anything: it is DAG-side, or host-side when it concerns starting a run at all.

The recurring « doesn't X need a verb? » cases, stress-tested ·

Candidate · Axis · Resolution
**wait-for-human** (approval gate) · WHO · a call that resolves when a human answers · a **tool** · request/response with a long latency · `invoke:` model · **already shipped** as `nika:prompt` (blocking confirm · [stdlib/builtins-v0.1.md](../stdlib/builtins-v0.1.md))
**sleep / delay** inside a run · WHO · a call that resolves after a duration · a **tool** · **already shipped** as `nika:wait` (relative `duration:` XOR absolute `until:`) · NOT a verb · nothing is executed, a result (elapsed) is awaited
**cron / schedule** (start a run at time T) · neither · it precedes the run · **host concern** · a workflow describes a run, not its triggering · explicitly out-of-scope ([08](./08-out-of-scope.md))
**streaming between tasks** · WHEN · changes what an *edge* delivers · a **DAG-edge semantic**, not an execution model · out-of-scope v0.1 · an additive edge attribute later · never a verb
**sub-workflow call** · WHO · dispatch-and-await a run · a **tool** (workflow-as-tool · see [08](./08-out-of-scope.md) §composition) · the `invoke` model again

A 5th verb would have to name an execution model that is none of call-with-result, process, inference, or loop, and every concrete candidate inspected since the 4-verb lock (D-2026-05-22-N18) has resolved to a tool (WHO · request/response) or an ordering construct (WHEN). That is the closure: the verb set is closed under decomposition into WHO × WHEN.

Field additions to each verb are additive within v1 (feature-detected · no version marker in the file at all). Field removal NEVER happens at v1.

A v0.1-compliant engine that encounters an unknown field on a verb may ·

Reject with a clear error (strict mode · default for tests)
Warn + ignore the field (lenient mode · default for production)

Engine config picks which mode.

🦋 Next · [03 · DAG shape](./03-dag.md)

nika-spec@14bf49f43 · 02-verbs.md · sha256 3744a8527e73fc55… · the pack upstream