Step Types

🔀 Step Types

CodeGenesis supports several step types that can be composed together to build complex pipelines.

graph TD
    S[Step Types] --> A[Simple Step]
    S --> B[Foreach]
    S --> C[Parallel]
    S --> D[Parallel Foreach]
    S --> E[Approval]
    B -->|sequential| F[item 1 → item 2 → item N]
    C -->|concurrent| G["branch A ‖ branch B ‖ branch C"]
    D -->|concurrent| H["item 1 ‖ item 2 ‖ item N"]
    E -->|interactive| I["⚠ user confirms or rejects"]

Loading

---

📝 Simple Step

The basic unit of a pipeline. Sends a prompt to Claude and collects the response.

- name: "Analyze code"
  description: "Review the codebase"
  prompt: "Analyze the project structure"
  output_key: "analysis"
  optional: false

📋 All simple step fields

Field	Required	Description
name	Yes	Step identifier
prompt	Yes*	Prompt sent to Claude
context	Yes*	Context bundle path (alternative to prompt)
description	No	Shown in the pipeline progress UI
agent	No	Agent label for display
system_prompt	No	System prompt for Claude
model	No	Model override for this step
max_turns	No	Max agentic turns
output_key	No	Store output for later steps
allowed_tools	No	Restrict which tools Claude can use
mcp_servers	No	MCP stdio servers for this step
optional	No	If true, failure returns Skipped instead of Failed
fail_if	No	Fail if output contains this string
fail_message	No	Custom failure message for fail_if
retry_max	No	Max retry attempts
retry_backoff_seconds	No	Backoff between retries
rate_limit_pause_seconds	No	Pause duration on rate limit
rate_limit_max_pauses	No	Max rate limit pauses

*Either prompt or context is required.

---

🔁 Foreach (Sequential Iteration)

Loop over a collection and run sub-steps for each item sequentially:

- foreach:
    collection: "{{steps.modules}}"
    item_var: "module"
    output_key: "module_results"
    steps:
      - name: "Analyze {{module}}"
        prompt: "Analyze module: {{module}}"
        output_key: "analysis"

Collection Formats

Format	Example
JSON array	["auth", "api", "db"]
Comma-separated	auth, api, db
Newline-separated	One item per line

Loop Variables

Variable	Description
{{<item_var>}}	Current item value (e.g. {{module}})
{{loop.item}}	Alias for the current item
{{loop.index}}	Zero-based index

Note

Each iteration gets its own isolated context. Sub-step outputs from one iteration don't leak into the next. When output_key is set, all iteration results are aggregated into a JSON array.

---

⚡ Parallel (Concurrent Branches)

Run multiple independent branches concurrently:

- parallel:
    max_concurrency: 5
    fail_fast: true
    branches:
      - name: "Security Review"
        output_key: "security"
        steps:
          - name: "Check vulnerabilities"
            prompt: "Review for security issues"

      - name: "Performance Review"
        output_key: "performance"
        steps:
          - name: "Check performance"
            prompt: "Review for performance"

Option	Default	Description
max_concurrency	unlimited	Max branches running simultaneously
fail_fast	false	Cancel remaining branches on first failure

Important

Each branch runs in an isolated context. After all branches complete, their outputs are merged back into the parent context.

---

🔄 Parallel Foreach (Concurrent Iteration)

Combines foreach's collection parsing with parallel's concurrency model:

- parallel_foreach:
    collection: "{{steps.modules}}"
    item_var: "module"
    max_concurrency: 3
    fail_fast: false
    output_key: "results"
    steps:
      - name: "Analyze {{module}}"
        prompt: "Analyze module: {{module}}"
        output_key: "analysis"

Option	Default	Description
collection	(required)	JSON array, comma-separated, or newline-separated
item_var	"item"	Variable name for the current item
max_concurrency	unlimited	Max items processing simultaneously
fail_fast	false	Cancel remaining items on first failure
output_key	null	Store all results as a JSON array

---

✋ Approval Step

Pauses pipeline execution and prompts the user for confirmation:

- approval:
    name: "Approve deployment plan"
    message: "Review the plan and confirm you want to proceed."
    display_key: deployment_plan

Field	Required	Description
name	No	Label in pipeline progress (default: "Approval")
description	No	Sub-label under the step name
message	No	Message in the approval panel
display_key	No	Shows a previous step's output as preview

User input:

Action	Accepted Input
✅ Approve	y, yes, ok
❌ Reject	n, no, or Enter

Caution

On rejection the pipeline stops immediately with a Pipeline Failed banner.

---

🧩 Composing Steps

Foreach and parallel can be nested. For example, "for each module, run lint and test in parallel":

- foreach:
    collection: "{{steps.modules}}"
    item_var: "module"
    steps:
      - parallel:
          branches:
            - name: "Lint"
              steps:
                - name: "Lint {{module}}"
                  prompt: "Lint module {{module}}"
            - name: "Test"
              steps:
                - name: "Test {{module}}"
                  prompt: "Test module {{module}}"

graph TD
    FE[foreach modules] --> M1[module-auth]
    FE --> M2[module-api]
    FE --> M3[module-db]
    M1 --> P1["Lint ‖ Test"]
    M2 --> P2["Lint ‖ Test"]
    M3 --> P3["Lint ‖ Test"]

Loading