Step library

The step library (~/.vectorstep/steps/) holds named, reusable step definitions. A pipeline references one with use: <step-name> and can override any field — overrides deep-merge over the library definition. Analytics aggregate per library step across every pipeline that uses it.

Named step definitions live in step_library_dir (/data/steps in the installer’s default config). Each file defines a reusable step config that pipelines can reference by name using a use: key. The loader resolves references before Pydantic validation, so the runner is completely unaware of the library mechanism.

A library step’s name: becomes its filename on disk, so it’s restricted to [a-zA-Z0-9][a-zA-Z0-9_-]{0,63} — same rule as a pipeline’s own name:, see Pipeline schema.

Library step file

steps/sre-investigation.yaml:

name: sre-investigation
description: Grafana RED metrics investigation — updates Jira with findings
tags: [investigation, grafana, openclaw]

executor: openclaw
executor_config:
  agent: sre-investigation
  session_key: "agent:sre-investigation:{{pipeline_run_id}}:{{current_step}}"
confidence_threshold: 0.60
on_low_confidence: escalate
timeout_seconds: 1200
prompt_template: |
  ... default prompt ...

Referencing a library step in a pipeline

steps:
  - use: first-line-triage          # fully inherits the library step

  - use: sre-investigation          # inherit config, override just the threshold
    confidence_threshold: 0.80

  - use: sre-investigation          # add a model override — executor_config is deep-merged
    executor_config:                # so agent/session_key are still inherited
      model: anthropic/claude-opus-4-8

  - use: sre-investigation          # custom prompt for this pipeline
    prompt_template: |
      Pipeline-specific prompt referencing {{steps.first_line_triage.summary}} ...

Merge rules

• All top-level fields: local value wins if present, library value is the default.
• executor_config only: deep-merged — local keys add to or override library keys, rather than replacing the whole block. This lets you add model or thinking_level without repeating agent and session_key.
• description and tags are library-only metadata and are stripped before the step is passed to the runner.

Step library UI

The /ui/steps page shows all loaded library steps with their executor/agent, confidence threshold, tags, which pipelines reference each step, and a copy button for the - use: step-name snippet. Each step with run history also gets a per-pipeline/agent/model breakdown table — runs, success rate, and avg tokens (in/out) for every distinct (pipeline, agent, model) combination that’s executed this step, since the same library step can be wired to a different agent or model in different pipelines. Scoped to stage=production runs, same as every other rollup surface (see Pipeline stages).

Hot reload

POST /reload and SIGHUP reload the step library first, then re-resolve all pipeline references against the updated library. A Reload config button on the /ui/pipelines page calls this endpoint directly from the browser.

Caution

~/.vectorstep/steps/ is an ordinary host directory, not version-controlled by VectorStep itself. Step definitions reference your specific agents, session key patterns, and confidence thresholds — they are personal to your deployment, like config/vectorstep.yaml. The installer seeds starter definitions there for you to adapt to your own agents.

The installer seeds both ~/.vectorstep/pipelines/ and ~/.vectorstep/steps/ with real starter templates on first install — edit them in place or use them as a reference while writing your own.