Skip to content

Stage Types

| Field | Type | Required | Description |

v0.4.0concept

Stage types in detail (v0.2)

Common fields (all stage types)

Field Type Required Description
id string yes Unique within pipeline. Used in depends_on and $stages.X.output refs.
depends_on string[] no Stage IDs that must complete first. MVP = sequential; v0.3 = parallel DAG with explicit DAG.
input object no Inputs for this stage. May reference $input.X (pipeline input) or $stages.X.output (prior stage output).
system string no System prompt for the LLM call (added to model-specific system field, NOT merged with skill prompt).
mcp_servers string[] no v0.2 NEW. MCP server names to make available. Validated against server registry. NOT executed until v0.3.
mcp_tools string[] no v0.2 NEW. Tool name allowlist from declared mcp_servers. Validated against server-known tools. NOT executed until v0.3.
working_dir string no v0.2 NEW (CLI only). Local path created/passed to stage. Server ignores this field with a warning. See “Filesystem” below.

Stage type A: LLM-only stage (model: + prompt:)

- id: analyze
  model: gpt-4o
  system: "You are a senior code reviewer."
  prompt: |
    Language: $input.language
    Task: $input.task
    Code: $input.code
    List 3-5 specific improvement opportunities.
  output_format: structured_json      # optional
  fields: [issues, suggestions]      # required if output_format=structured_json

prompt: may interpolate $input.X and $stages.X.output. Model resolution follows the v0.1 chain (stage → pipeline.defaults → skill.preferred → agent → env → hardcoded). Skill is NOT loaded for this stage type.

Stage type B: uses: skill stage

- id: refactor
  uses: code_rewriter                  # latest version
  uses: code_rewriter@0.2.1            # v0.2 NEW: pinned version
  uses:
    - skill_a
    - skill_b@1.0.0                    # arrays support per-skill pinning too
  model: claude-3.5-sonnet             # LLM to use (skills are calls to LLM with skill as system prompt)

When the executor hits uses:, it:

  1. Parses uses into [{id, version?}] entries
  2. For each: fetches skill via API, validates access (private + granted_to + author)
  3. v0.2 NEW: If version is specified, refuses to run if actual version ≠ requested (strict pin)
  4. v0.2 NEW: If no version, fetches latest and emits warning in provenance payload: "uses_version_pin": "loose"
  5. v0.2 NEW: Computes keccak256(full_md + version + author) → records as skill.content_hash in stage provenance
  6. v0.2 NEW: Injects mandatory system prefix: [SKILL:<id> v<version> keccak256:<hash>]\n\nYou MUST follow the skill instructions above exactly. If you cannot, return { error: "<reason>" } as JSON.
  7. Sends skill’s full_md + input + optional output_format to LLM
  8. v0.2 NEW: If output_format: structured_json + fields: [...], post-LLM validation: parse output as JSON, assert all fields keys exist; if not, return StageOutputFormatError

Backward compat: uses: skill_X (string, no version) ≡ uses: skill_X@* (loose pin).

Stage type C: uses_parallel: (v0.3+)

- id: parallel_research
  uses_parallel:
    - uses: web_search
      input: { query: "$input.topic" }
    - uses: github_search
      input: { query: "$input.topic language:python" }

v0.3 will support parallel uses[] with explicit fan-out. v0.2 ignores this field with a warning. Deferred because it requires execution model rework (parallel DAG + partial-failure semantics).