Pipeline YAML Reference

📋 Pipeline YAML Reference

Pipelines are defined in YAML files with four sections:

graph TD
    A[pipeline] --> B[metadata: name, description, version]
    C[settings] --> D[model, max_turns, timeout, mcp_servers]
    E[inputs] --> F[variables with defaults]
    G[steps] --> H[step 1 → step 2 → step N]
    I[outputs] --> J[result mappings]

Loading

---

📄 Full Example

# ── Metadata ──────────────────────────────────────────
pipeline:
  name: "My Pipeline"
  description: "What this pipeline does"
  version: "1.0"

# ── Global settings ──────────────────────────────────
settings:
  model: "claude-sonnet-4-6"       # default model for all steps
  max_turns: 5                      # default max turns
  timeout_seconds: 300              # process timeout
  working_directory: "."            # working dir for Claude

# ── Input variables ──────────────────────────────────
inputs:
  task:
    description: "What to build"
    default: "Create a hello world page"
  language:
    description: "Target language"
    default: "html"

# ── Steps ─────────────────────────────────────────────
steps:
  - name: "Plan"
    agent: "architect"
    description: "Create implementation plan"
    model: "claude-opus-4-6"        # per-step model override
    context: "contexts/planner"     # load a context bundle
    output_key: "plan"              # store output for later steps

  - name: "Execute"
    agent: "engineer"
    description: "Implement the plan"
    system_prompt: "You are a senior engineer."
    prompt: |
      Implement this plan:
      {{steps.plan}}
      Original task: {{task}}
    max_turns: 10
    output_key: "result"
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash"

  - name: "Validate"
    agent: "reviewer"
    description: "Review the implementation"
    prompt: |
      Review: {{steps.result}}
      Verdict: PASS or FAIL
    optional: true                  # pipeline continues if this fails

  - name: "Run tests"
    use_pipeline: ./testing.yml     # compose another pipeline
    inputs:
      code: "{{steps.result}}"
    output_key: "test_results"

# ── Outputs ───────────────────────────────────────────
outputs:
  summary:
    source: "result"
    description: "Final implementation result"
  tests:
    source: "test_results"
    description: "Test execution results"

---

🔤 Template Variables

Use {{variable}} to reference inputs and {{steps.<output_key>}} to reference outputs from previous steps.

Syntax	Description	Example
{{variable}}	Pipeline input	{{task}}
{{steps.<key>}}	Output from a previous step	{{steps.plan}}
{{loop.item}}	Current foreach item	Inside foreach only
{{loop.index}}	Current foreach index	Inside foreach only

Note

Variables are resolved just before each step runs, so later steps always see the latest outputs.

---

⏱️ Understanding max_turns

A turn is one complete round-trip between CodeGenesis and Claude: the engine sends a prompt, Claude reasons, optionally calls tools, and returns a response.

Value	Behavior	Use Case
0	♾️ Unlimited	Complex, open-ended tasks
1	🎯 Single-shot, no tool use	Planning, review steps
3-5	🔧 Light agentic work	Read files + produce response (default)
10+	⚡ Deep agentic work	Multi-file creation, testing, iteration

Priority (most specific wins):

Per step  →  Per pipeline  →  Global default (5)

Warning

Unlimited turns (0) can consume significant API credits. Make sure timeout_seconds is configured as a safety net.

---

📤 Outputs Section

The outputs section declares which step outputs a pipeline exposes. This is especially important for composed pipelines (via use_pipeline), where the parent needs to know what data the child produces.

outputs:
  summary:
    source: "result"             # references a step's output_key
    description: "Final result"
  analysis:
    source: "analysis"
    description: "Detailed analysis"

Field	Description
source	The output_key of a step whose output to expose
description	Human-readable description of this output

Note

If a pipeline has no outputs section and is called via use_pipeline, all step outputs from the child are available to the parent. When outputs is defined, only the declared outputs are exposed.