Workflows

Overview

Workflows let you orchestrate multiple AI coding sessions as a single coordinated task. Define a sequence of steps in YAML or JSON, and CodePiper handles session creation, prompt delivery, wait conditions, result extraction, and error recovery.

Use workflows for:

• Multi-step code generation pipelines
• Automated testing across multiple projects
• Parallel refactoring with branch isolation
• Conditional logic based on intermediate results

Step Types

Workflows are built from five step types.

session

Spawns a new provider session, optionally sends a prompt, waits for a condition, and extracts results.

steps:
  - name: implement
    type: session
    provider: claude-code
    cwd: ~/projects/my-app
    prompt: "Implement the auth module with Argon2 hashing"
    wait:
      type: idle_prompt
      timeout: 300000
    extract:
      - key: files_changed
        type: regex
        pattern: "Created: (.+)"

if

Conditional branching based on previous step results or variables.

steps:
  - name: check-tests
    type: if
    condition: "${steps.run-tests.exit_code} === 0"
    then:
      - name: deploy
        type: session
        provider: claude-code
        prompt: "Deploy to staging"
    else:
      - name: fix
        type: session
        provider: claude-code
        prompt: "Fix the failing tests"

Conditions support comparison operators: ===, !==, ==, !=, >, <, >=, <=.

parallel

Run multiple steps concurrently.

steps:
  - name: multi-refactor
    type: parallel
    waitFor: all
    steps:
      - name: refactor-auth
        type: session
        provider: claude-code
        cwd: ~/projects/my-app
        prompt: "Refactor the auth module"
      - name: refactor-api
        type: session
        provider: claude-code
        cwd: ~/projects/my-app
        prompt: "Refactor the API layer"

Wait modes:

foreach

Loop over a list of items.

steps:
  - name: test-each
    type: foreach
    items: "${files}"
    step:
      name: test-file
      type: session
      provider: claude-code
      prompt: "Run tests for ${item}"

Inside the loop body, ${item} is the current value and ${index} is the zero-based position.

Items can be an array, a comma-separated string, or a JSON array from a previous step’s extraction.

log

Output a message (useful for debugging or progress tracking).

steps:
  - name: status
    type: log
    message: "Auth module created ${steps.implement.files_changed} files"

Wait Conditions

Session steps can wait for specific events before proceeding to the next step.

Codex sessions don’t support hook-based wait types (idle_prompt, permission_prompt, stop, event) or result extraction. These are validated at workflow creation time and rejected if the step uses the Codex provider.

Result Extraction

Extract data from session output to use in later steps.

extract:
  - key: test_result
    type: regex
    pattern: "Tests: (\\d+) passed, (\\d+) failed"
  - key: coverage
    type: jsonpath
    path: "$.coverage.total"

Extraction types:

Extracted values are stored in the execution context and accessible via ${steps.<step-name>.<key>}.

Error Handling

Each session step can define an error strategy:

steps:
  - name: risky-step
    type: session
    provider: claude-code
    prompt: "Try something experimental"
    onError: retry
    retry:
      attempts: 3
      delay: 5000

Variable Substitution

Variables use ${...} syntax and can reference:

• Input variables: Passed at execution time via --var KEY=VALUE
• Step results: ${steps.<step-name>.<extracted-key>}
• Loop variables: ${item} and ${index} inside foreach blocks

Execution Lifecycle

Workflows and their steps go through these states:

Cancel a running workflow:

codepiper workflow cancel <execution-id>

This gracefully stops any running sessions and marks remaining steps as skipped.

CLI Usage

# Create a workflow from a YAML file
codepiper workflow create workflow.yaml

# List all workflows
codepiper workflow list

# Run a workflow with variables
codepiper workflow run <workflow-id> --var branch=main --var target=staging

# Check execution status
codepiper workflow status <execution-id>

# Follow execution logs
codepiper workflow logs <execution-id> --follow

What’s next

• Workflow Authoring: Practical patterns and examples
• Sessions & Providers: Provider capabilities that affect workflows
• Analytics: Track token usage across workflow executions