Templates

nika: v1
workflow: chain-template            # SLOT: kebab-case workflow id
description: "gather → think → persist"   # SLOT: one honest sentence

model: mock/echo                    # SLOT: provider/model (mock/echo = CI-safe)

vars:
  source: "./input.txt"             # SLOT: your inputs · typed where required

tasks:
  - id: gather
    invoke:                         # SLOT: the fact source · nika:read / nika:fetch / exec
      tool: "nika:read"
      args: { path: "${{ vars.source }}" }

  - id: think
    depends_on: [gather]
    infer:
      prompt: |
        # SLOT: the one model job · interpolate ${{ tasks.gather.output }}
        Summarize · ${{ tasks.gather.output }}

  - id: persist
    depends_on: [think]
    invoke:
      tool: "nika:write"
      args:
        path: "./output.md"         # SLOT: destination
        content: "${{ tasks.think.output }}"   # ALWAYS pass content · a write without it writes nothing

outputs:
  result: ${{ tasks.think.output }}  # SLOT: the callable contract

nika: v1
workflow: gate-and-act-template     # SLOT: kebab-case workflow id
description: "watch a value · act only when the condition holds"   # SLOT

vars:
  source_url: "https://api.example.com/v1/value"   # SLOT: what to watch
  threshold: 100                    # SLOT: the trigger condition value

secrets:
  webhook:
    source: env
    key: ALERTS_WEBHOOK_URL         # SLOT: where the act lands
    egress:
      - to: "nika:notify"
        host_from_self: true        # the secret value IS the destination URL

tasks:
  - id: check
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ vars.source_url }}"
        mode: jq
        jq: "."
    output:
      value: ".value"               # SLOT: the jq path to the watched field

  - id: act
    depends_on: [check]
    when: ${{ tasks.check.value > vars.threshold }}   # SLOT: the CEL condition
    invoke:
      tool: "nika:notify"           # SLOT: the action · notify / write / exec
      args:
        channel: webhook
        target: "${{ secrets.webhook }}"
        message: "Threshold crossed · ${{ tasks.check.value }}"   # SLOT
        severity: warning

outputs:
  value: ${{ tasks.check.value }}

nika: v1
workflow: fanout-template           # SLOT: kebab-case workflow id
description: "discover N items · process in parallel · merge"   # SLOT

model: mock/echo                    # SLOT: provider/model

vars:
  collection_source: "./items"      # SLOT: where the collection comes from

tasks:
  - id: discover
    invoke:                         # SLOT: glob / fetch sitemap / exec + jq split
      tool: "nika:glob"
      args: { pattern: "${{ vars.collection_source }}/*.md" }

  - id: process
    depends_on: [discover]
    for_each: ${{ tasks.discover.output }}
    max_parallel: 4                 # SLOT: the polite ceiling
    fail_fast: false
    timeout: "60s"                  # SLOT: per-iteration bound
    retry:
      max_attempts: 3
      backoff_strategy: exponential
      jitter: true
    on_error:
      recover: null                 # a failed item yields null at its index · the batch lives
    infer:                          # SLOT: the per-item job (any verb)
      prompt: |
        Process this item · ${{ item }}

  - id: survivors
    depends_on: [process]
    invoke:                         # the null-aware fan-in · order preserved
      tool: "nika:jq"
      args:
        input: ${{ tasks.process.output }}
        expression: "[ .[] | select(. != null) ]"


  - id: merge
    depends_on: [survivors]
    infer:
      prompt: |
        # SLOT: the fan-in · the survivors array (failed items filtered)
        Merge these results into one report · ${{ tasks.survivors.output }}

outputs:
  report: ${{ tasks.merge.output }}

nika: v1
workflow: etl-state-template        # SLOT: kebab-case workflow id
description: "read state · fetch fresh · diff · process the delta · save state"   # SLOT

vars:
  source_url: "https://api.example.com/v1/records"   # SLOT: the data source
  state_path: "./state/etl-state.json"               # SLOT: the cursor file

tasks:
  # First run · no state file yet · recover to an empty list.
  - id: empty
    invoke:
      tool: "nika:jq"
      args: { input: [], expression: "." }

  - id: previous
    invoke:
      tool: "nika:read"
      args: { path: "${{ vars.state_path }}" }
    on_error:
      on_codes: [NIKA-BUILTIN-READ-001]   # not-found ONLY · a permission error still fails loudly
      recover: ${{ tasks.empty.output }}

  - id: fresh
    invoke:
      tool: "nika:fetch"            # SLOT: fetch / read / exec — the fresh data
      args:
        url: "${{ vars.source_url }}"
        mode: jq
        jq: ".records"

  - id: delta
    depends_on: [previous, fresh]
    invoke:
      tool: "nika:json_diff"        # RFC 6902 · empty patch = nothing new
      args:
        before: "${{ tasks.previous.output }}"
        after: "${{ tasks.fresh.output }}"

  - id: process
    depends_on: [delta]
    when: ${{ size(tasks.delta.output) > 0 }}
    invoke:
      tool: "nika:jq"               # SLOT: the delta job (jq · infer · write…)
      args:
        input: "${{ tasks.delta.output }}"
        expression: "length"

  - id: save_state
    depends_on: [fresh]
    invoke:
      tool: "nika:write"
      args:
        path: "${{ vars.state_path }}"
        content: "${{ tasks.fresh.output }}"
        create_dirs: true
        overwrite: true

outputs:
  changes:
    value: ${{ tasks.delta.output }}
    type: array
    description: "RFC 6902 ops since last run · empty = no-op run"

nika: v1
workflow: agent-loop-template       # SLOT: kebab-case workflow id
description: "plan → budgeted agent → typed result"   # SLOT

model: mock/echo                    # SLOT: agents want a tool-calling model

vars:
  goal:
    type: string
    required: true
    description: "What the agent must accomplish"   # SLOT

tasks:
  - id: plan
    infer:
      prompt: "Break '${{ vars.goal }}' into at most 4 concrete steps."   # SLOT
      schema:
        type: object
        required: [steps]
        properties:
          steps: { type: array, items: { type: string } }

  - id: execute
    depends_on: [plan]
    agent:
      system: "Work the plan step by step. Call nika:done when finished."   # SLOT
      prompt: "Plan · ${{ tasks.plan.output.steps }}"
      tools:                        # SLOT: the MINIMUM grant for the job
        - "nika:read"
        - "nika:done"
      max_turns: 15                 # SLOT: the loop bound
      max_tokens_total: 80000       # SLOT: the spend bound
      schema:                       # SLOT: the typed final-message contract
        type: object
        required: [findings]
        properties:
          findings: { type: array, items: { type: string } }

  - id: confirm
    depends_on: [execute]
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ size(tasks.execute.output.findings) > 0 }}"
        message: "Agent returned no findings — do not trust an empty run"   # SLOT

outputs:
  findings:
    value: ${{ tasks.execute.output.findings }}
    type: array
    description: "The agent's typed findings"   # SLOT

nika: v1
workflow: human-gated-ship-template  # SLOT: kebab-case workflow id
description: "verify in parallel · human GO · act · record"   # SLOT

permits:                            # SLOT: the blast radius · default-deny once present
  exec: ["echo"]                    # SLOT: ONLY the programs the gates + act run (argv form)
  tools: ["nika:assert", "nika:prompt", "nika:notify"]
  net: { http: ["hooks.slack.com"] }   # SLOT: the webhook host · nothing else may leave

secrets:
  webhook:
    source: env
    key: TEAM_WEBHOOK_URL           # SLOT: where the record lands
    egress:
      - to: "nika:notify"
        host_from_self: true        # the secret value IS the destination URL

tasks:
  # ── the verification wave · all checks run in parallel ──
  - id: check_a
    exec:
      command: ["echo", "ok"]        # SLOT: gate 1 (argv form · injection-safe)
      capture: structured

  - id: check_b
    exec:
      command: ["echo", "ok"]        # SLOT: gate 2
      capture: structured

  - id: gates
    depends_on: [check_a, check_b]
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ tasks.check_a.output.exit_code == 0 && tasks.check_b.output.exit_code == 0 }}"
        message: "A gate is RED — refusing to proceed"   # SLOT

  - id: human
    depends_on: [gates]
    invoke:
      tool: "nika:prompt"
      args:
        message: "All gates GREEN. Proceed?"   # SLOT: the decision, fully informed
        default: false

  - id: act
    depends_on: [human]
    when: ${{ tasks.human.output == true }}
    exec:
      command: ["echo", "shipped"]   # SLOT: the irreversible action (argv · program must be in permits.exec)
      # default capture · a failing ship fails LOUDLY (NIKA-EXEC-001) —
      # never `capture: structured` on the irreversible step (exit codes
      # would become data and a red ship would read as success)

  - id: record
    depends_on: [act]
    when: true                      # the always-pattern · runs on success, failure, OR refusal
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.webhook }}"
        message: "Run finished · act=${{ tasks.act.status }}"   # SLOT · success | failure | skipped
        severity: info

outputs:
  acted: ${{ tasks.act.status }}