### Participant Input Merge Example

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Demonstrates how flow overrides merge with base participant inputs.

```yaml
participants:
  fetch_page:
    type: exec
    input:
      NOTION_TOKEN: execution.context.token   # base input
    run: |
      curl -sS "https://api.notion.com/v1/pages/$(cat)" \
        -H "Authorization: Bearer ${NOTION_TOKEN}"

flow:
  # resolved input = { NOTION_TOKEN: execution.context.token, PAGE_ID: workflow.inputs.story_id }
  - fetch_page:
      input:
        PAGE_ID: workflow.inputs.story_id

  - fetch_page:
      input:
        PAGE_ID: open_task.output
```

--------------------------------

### Define Sub-Workflows

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Examples of declaring sub-workflows as reusable participants or inline steps.

```yaml
participants:
  reviewCycle:
    type: workflow
    path: ./review-loop.yaml
    input:
      repo: workflow.inputs.repoUrl
```

```yaml
flow:
  - coder
  - as: reviewCycle
    type: workflow
    path: ./review-loop.yaml
    input:
      repo: workflow.inputs.repoUrl
  - deploy
```

--------------------------------

### Configure Event Emission

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Example of an acknowledged event emission with timeout and fallback strategy.

```yaml
- as: notify
  type: emit
  event: "deploy.started"
  payload: deploy.output
  ack: true
  timeout: 10s
  onTimeout: skip
```

--------------------------------

### Define Event Payloads

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Examples of using CEL expressions for simple or structured event payloads.

```yaml
payload: coder.output
```

```yaml
payload:
  taskId: workflow.inputs.taskId
  status: coder.output.status
```

--------------------------------

### Define Workflow Inputs

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Examples of defining workflow inputs with and without JSON schema validation.

```yaml
inputs:
  repoUrl:
  branch:
```

```yaml
inputs:
  repoUrl:
    type: string
    format: uri
    required: true
  branch:
    type: string
    default: "main"
  maxRetries:
    type: integer
    minimum: 1
    maximum: 10
    default: 3
```

--------------------------------

### Define Workflow Output

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Examples of defining workflow outputs as single values, structured objects, or with schema validation.

```yaml
output: reviewer.output.summary
```

```yaml
output:
  approved: reviewer.output.approved
  code: coder.output.code
```

```yaml
output:
  schema:
    approved:
      type: boolean
      required: true
    code:
      type: string
  map:
    approved: reviewer.output.approved
    code: coder.output.code
```

--------------------------------

### Define Participant Input Mapping

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Examples of mapping participant inputs using simple or structured CEL expressions.

```yaml
participants:
  coder:
    type: exec
    run: ./code.sh
    input: workflow.inputs.taskDescription
```

```yaml
participants:
  coder:
    type: exec
    run: ./code.sh
    input:
      task: workflow.inputs.taskDescription
      context: reviewer.output.feedback
```

--------------------------------

### HTTP Participant: Fetch Data

Source: https://context7.com/duckflux/spec/llms.txt

Demonstrates an HTTP participant making a GET request to fetch user data, including dynamic URL construction and a specified timeout.

```yaml
fetch_data:
    type: http
    url: "'https://api.example.com/users/' + workflow.inputs.userId"
    method: GET
    headers:
      Authorization: "'Bearer ' + env.API_KEY"
    timeout: 30s

flow:
  - fetch_data
  - create_issue
```

--------------------------------

### HTTP Participant: Create GitHub Issue

Source: https://context7.com/duckflux/spec/llms.txt

Example of an HTTP participant making a POST request to create a GitHub issue, dynamically constructing the URL and body using CEL.

```yaml
participants:
  create_issue:
    type: http
    url: "'https://api.github.com/repos/' + workflow.inputs.repo + '/issues'"
    method: POST
    headers:
      Authorization: "'Bearer ' + env.GITHUB_TOKEN"
      Accept: "'application/vnd.github.v3+json'"
      Content-Type: "'application/json'"
    body:
      title: workflow.inputs.issueTitle
      body: coder.output.description
      labels: ["bug", "automated"]
```

--------------------------------

### Minimal and Full Workflow Structure

Source: https://context7.com/duckflux/spec/llms.txt

Defines the basic structure of a Duckflux workflow, including minimal and full examples with inputs, defaults, participants, and flow.

```yaml
# Minimal valid workflow
flow:
  - type: exec
    run: echo "Hello, duckflux!"
```

```yaml
# Full workflow structure
id: code-review-pipeline
name: Code Review Pipeline
version: 1

defaults:
  timeout: 10m
  cwd: ./repo
  onError: fail

inputs:
  repoUrl:
    type: string
    format: uri
    required: true
  branch:
    type: string
    default: "main"
  maxRetries:
    type: integer
    minimum: 1
    maximum: 10
    default: 3

participants:
  builder:
    type: exec
    run: npm run build

flow:
  - builder

output:
  status: builder.status
  duration: builder.duration
```

--------------------------------

### Define Anonymous Participants in Flow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Example of using anonymous participants that rely on the implicit I/O chain.

```yaml
flow:
  - type: exec
    run: echo "setup data"
  - as: processor
    type: exec
    run: process.sh    # input contains "setup data"
```

--------------------------------

### Reusable Participant Definition

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Define participants in the 'participants' block for reuse. This example defines a 'tests' participant of type 'exec'.

```yaml
participants:
  tests:
    type: exec
    run: npm test

flow:
  - tests
```

--------------------------------

### Execute Sequential Steps

Source: https://context7.com/duckflux/spec/llms.txt

Steps execute in order, with output from one step implicitly passed as input to the next.

```yaml
flow:
  - type: exec
    run: curl -s https://api.example.com/data

  - as: parser
    type: exec
    run: jq '.items'

  - as: processor
    type: exec
    run: ./process.sh

  - as: reporter
    type: exec
    run: ./report.sh
    input:
      data: parser.output
      processed: processor.output
```

--------------------------------

### Exec Participant: Input via Stdin (Unix Pipe Style)

Source: https://context7.com/duckflux/spec/llms.txt

Shows how string input can be piped to exec participants via stdin, chaining commands like in a Unix pipeline.

```yaml
# String input -> stdin (Unix pipe style)
flow:
  - type: exec
    run: curl -s https://api.example.com/data
  - type: exec
    run: jq '.items[] | .name'
  - type: exec
    run: sort | uniq
```

--------------------------------

### Implement Anonymous Participant Chaining

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Demonstrates how to mix anonymous steps with named steps, where anonymous steps automatically chain their output to the next step in the flow.

```yaml
flow:
  # Anonymous step — output chains to the next step
  - type: exec
    run: curl -s https://api.example.com/data

  # Named step — receives chained input, addressable by name
  - as: processor
    type: exec
    run: ./process.sh

  # Anonymous step — receives processor's output via chain
  - type: http
    url: https://api.example.com/result
    method: POST
    body: input
```

--------------------------------

### Sequential Execution in Flow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Steps in the 'flow' array execute in top-to-bottom order. Each step must complete before the next one begins.

```yaml
flow:
  - stepA
  - stepB
  - stepC
```

--------------------------------

### Emit and Wait for Events

Source: https://context7.com/duckflux/spec/llms.txt

Utilize `emit` to publish events and `wait` to subscribe. Events can be fire-and-forget or acknowledged with timeouts. Use `match` for conditional waiting.

```yaml
flow:
  - as: deploy
    type: exec
    run: ./deploy.sh

  # Fire-and-forget event
  - type: emit
    event: "deploy.started"
    payload: deploy.output

  # Acknowledged event (blocks until delivery confirmed)
  - as: notify
    type: emit
    event: "deploy.completed"
    payload:
      taskId: workflow.inputs.taskId
      status: deploy.status
    ack: true
    timeout: 10s
    onTimeout: skip

  # Wait for external event
  - wait:
      event: "approval.granted"
      match: event.userId == workflow.inputs.approver
      timeout: 24h

  # Continue after approval received
  - as: finalize
    type: exec
    run: ./finalize.sh
```

--------------------------------

### Exec Participant: Input as Environment Variables

Source: https://context7.com/duckflux/spec/llms.txt

Demonstrates passing map input to an exec participant as environment variables, using CEL expressions for dynamic values.

```yaml
# Map input -> environment variables
participants:
  deploy:
    type: exec
    run: ./deploy.sh --branch="${BRANCH}" --env="${TARGET_ENV}"
    input:
      BRANCH: workflow.inputs.branch
      TARGET_ENV: execution.context.environment

flow:
  - deploy
```

--------------------------------

### Apply Guard Conditions with when

Source: https://context7.com/duckflux/spec/llms.txt

Uses CEL expressions to conditionally execute steps. If the expression evaluates to false, the step is skipped.

```yaml
flow:
  - as: reviewer
    type: exec
    run: ./review.sh

  - deploy:
      when: reviewer.output.approved == true

  - notify:
      when: deploy.status == "success"

  # Guard with complex condition
  - cleanup:
      when: execution.context.environment == "staging" && tests.status != "success"
```

--------------------------------

### Execute Parallel Steps

Source: https://context7.com/duckflux/spec/llms.txt

Use the parallel construct to run multiple steps concurrently, waiting for all to complete before proceeding.

```yaml
flow:
  - parallel:
      - as: tests
        type: exec
        run: npm test
        timeout: 5m
        onError: skip

      - as: lint
        type: exec
        run: npm run lint
        timeout: 2m
        onError: skip

      - as: typecheck
        type: exec
        run: npm run typecheck
        timeout: 3m

  # Access parallel results
  - if:
      condition: tests.status == "success" && lint.status == "success"
      then:
        - type: exec
          run: npm run deploy
```

--------------------------------

### Guard Condition with when

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Skips a step if the CEL precondition evaluates to false.

```yaml
flow:
  - deploy:
      when: reviewer.output.approved == true
```

--------------------------------

### Define Working Directory Precedence

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

The hierarchy of working directory configuration levels.

```text
participant.cwd > defaults.cwd > CLI --cwd > process cwd
```

--------------------------------

### Define a complete code review pipeline in YAML

Source: https://context7.com/duckflux/spec/llms.txt

This pipeline demonstrates input validation, participant execution with retry logic, loop-based review cycles, parallel testing, and conditional deployment.

```yaml
id: code-review-pipeline
name: Code Review Pipeline
version: 1

defaults:
  timeout: 10m
  cwd: ./repo

inputs:
  repoUrl:
    type: string
    format: uri
    required: true
  branch:
    type: string
    default: "main"
  maxReviewRounds:
    type: integer
    default: 3
    minimum: 1
    maximum: 10

participants:
  coder:
    type: exec
    as: "Code Builder"
    run: ./code.sh
    timeout: 15m
    onError: retry
    retry:
      max: 2
      backoff: 5s
    input:
      repo: workflow.inputs.repoUrl
      branch: workflow.inputs.branch

  reviewer:
    type: exec
    as: "Code Reviewer"
    run: ./review.sh
    timeout: 10m
    onError: fail
    output:
      approved:
        type: boolean
        required: true
      comments:
        type: string
      score:
        type: integer
        minimum: 0
        maximum: 10

flow:
  - coder

  - loop:
      as: round
      until: reviewer.output.approved == true
      max: workflow.inputs.maxReviewRounds
      steps:
        - reviewer
        - coder:
            when: reviewer.output.approved == false

  - parallel:
      - as: tests
        type: exec
        run: npm test
        timeout: 5m
        onError: skip

      - as: lint
        type: exec
        run: npm run lint
        timeout: 2m
        onError: skip

  - if:
      condition: tests.status == "success" && lint.status == "success"
      then:
        - as: deploy
          type: exec
          run: ./deploy.sh
          timeout: 5m

        - as: notifySuccess
          type: emit
          event: "deploy.completed"
          payload:
            approved: reviewer.output.approved
            score: reviewer.output.score
      else:
        - as: notifyFailure
          type: emit
          event: "deploy.failed"
          payload:
            tests: tests.status
            lint: lint.status

output:
  approved: reviewer.output.approved
  score: reviewer.output.score
  testResult: tests.status
  lintResult: lint.status
```

--------------------------------

### Participant Types: Exec, HTTP, Workflow, Emit, MCP

Source: https://context7.com/duckflux/spec/llms.txt

Illustrates different participant types including shell command execution, HTTP requests, sub-workflow references, event emission, and MCP server requests.

```yaml
participants:
  # Shell command execution
  coder:
    type: exec
    run: ./code.sh
    cwd: ./src
    timeout: 15m
    onError: retry
    retry:
      max: 2
      backoff: 5s
```

```yaml
# HTTP request
  api_call:
    type: http
    url: "'https://api.example.com/data'"
    method: POST
    headers:
      Authorization: "'Bearer ' + env.API_TOKEN"
      Content-Type: "'application/json'"
    body:
      task: workflow.inputs.taskId
      status: coder.output.status
```

```yaml
# Sub-workflow reference
  reviewCycle:
    type: workflow
    path: ./review-loop.yaml
    input:
      repo: workflow.inputs.repoUrl
```

```yaml
# Event emission
  notifier:
    type: emit
    event: "deploy.completed"
    payload:
      result: coder.output
    ack: true
    timeout: 10s
```

--------------------------------

### Context Assignment with set

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Writes values into execution.context for use in subsequent CEL expressions.

```yaml
flow:
  - set:
      token: workflow.inputs.api_token
      region: env.AWS_REGION
```

```yaml
flow:
  - if:
      condition: has(workflow.inputs.notion_token)
      then:
        - set:
            notion_token: workflow.inputs.notion_token
      else:
        - set:
            notion_token: env.NOTION_TOKEN

  - as: fetch_pages
    type: http
    url: "'https://api.notion.com/v1/pages'"
    headers:
      Authorization: "'Bearer ' + execution.context.notion_token"
```

--------------------------------

### Runtime Variable Summary

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

A reference list of available variables and their purpose within workflow expressions.

```text
workflow.*              Definition metadata
workflow.inputs.*       Workflow input parameters
workflow.output         Workflow output
execution.*             Execution metadata
execution.context.*     Shared data scratchpad (writable via `set` construct)
input                   Current participant input (chain + explicit, merged)
output                  Current participant output (write-only)
env.*                   Environment variables
<step>.*                Named participant result
loop.*                  Iteration context (or renamed via 'as')
event                   Event payload (in wait blocks)
now                     Current timestamp
```

--------------------------------

### Map Input to Environment Variables in Exec Step

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

When the resolved input is a map, each key-value pair is injected as an environment variable into the subprocess. Keys become variable names, and values are coerced to strings. These variables are accessible via shell interpolation.

```yaml
- as: deploy
  type: exec
  run: ./deploy.sh --branch="${BRANCH}" --env="${TARGET_ENV}"
  input:
    BRANCH: workflow.inputs.branch
    TARGET_ENV: execution.context.environment
```

--------------------------------

### Implement Conditional Branching

Source: https://context7.com/duckflux/spec/llms.txt

Route execution based on CEL expressions using if, then, and else blocks.

```yaml
flow:
  - as: reviewer
    type: exec
    run: ./review.sh

  - if:
      condition: reviewer.output.approved == true
      then:
        - as: deploy
          type: exec
          run: ./deploy.sh
          timeout: 5m

        - as: notifySuccess
          type: emit
          event: "deploy.completed"
          payload:
            status: "'success'"
      else:
        - as: notifyFailure
          type: emit
          event: "deploy.failed"
          payload:
            reason: reviewer.output.comments

        - type: exec
          run: ./rollback.sh
```

--------------------------------

### Configure Step Timeouts

Source: https://context7.com/duckflux/spec/llms.txt

Set timeout durations for steps at global, participant, or flow levels. Flow-level timeouts have the highest precedence.

```yaml
defaults:
  timeout: 5m

participants:
  coder:
    type: exec
    run: ./code.sh
    timeout: 15m  # Overrides default

  reviewer:
    type: exec
    run: ./review.sh
    timeout: 10m

flow:
  - coder:
      timeout: 30m  # Flow-level override (highest precedence)

  - reviewer

# Precedence: flow-level > participant-level > defaults > runtime default (no timeout)
```

--------------------------------

### Configure Error Handling Strategies

Source: https://context7.com/duckflux/spec/llms.txt

Defines error handling at the participant or flow level using strategies like fail, skip, or retry.

```yaml
defaults:
  onError: fail
  retry:
    max: 3
    backoff: 5s
    factor: 2

participants:
  coder:
    type: exec
    run: ./code.sh
    onError: retry
    retry:
      max: 2
      backoff: 5s
      factor: 2  # Intervals: 5s, 10s, 20s...

  fallback_coder:
    type: exec
    run: ./fallback.sh

  risky_step:
    type: exec
    run: ./risky.sh
    onError: fallback_coder  # Redirect to named participant

flow:
  - coder

  # Flow-level override takes precedence
  - risky_step:
      onError: skip
      timeout: 1m
```

--------------------------------

### Exec Participant: Working Directory with CEL

Source: https://context7.com/duckflux/spec/llms.txt

Configures the working directory for an exec participant using a CEL expression to dynamically determine the path.

```yaml
# Working directory with CEL expression
participants:
  tests:
    type: exec
    run: npm test
    cwd: workflow.inputs.projectPath + "/tests"
```

--------------------------------

### Configure Retry Logic

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

YAML structure for defining retry attempts, backoff intervals, and multipliers.

```yaml
retry:
  max: <integer>       # Required when onError: retry. Maximum attempts.
  backoff: <duration>  # Interval between attempts. Default: 0s.
  factor: <number>     # Backoff multiplier. Default: 1 (constant).
```

--------------------------------

### String Input to Stdin in Exec Step

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

When the resolved input is a scalar string, it is passed to the subprocess via standard input (stdin), enabling Unix pipe-style chaining between 'exec' steps.

```yaml
flow:
  - type: exec
    run: curl -s https://api.example.com/data
  - type: exec
    run: jq '.items[] | .name'
```

--------------------------------

### Implicit I/O Chaining

Source: https://context7.com/duckflux/spec/llms.txt

The output of a step is implicitly passed as input to the next sequential step. Explicit input mappings merge with chained values, with explicit mappings taking precedence on conflict.

```yaml
flow:
  # Anonymous step output chains to next step
  - type: exec
    run: curl -s https://api.example.com/data

  # Named step receives chain input, also addressable by name
  - as: processor
    type: exec
    run: ./process.sh

  # Chain + explicit input are merged
  - as: reporter
    type: exec
    run: ./report.sh
    input:
      extra_context: workflow.inputs.context
      # Chain value also available via 'input' variable

# Merge rules:
# - map + map: merge keys (explicit wins on conflict)
# - string + string: explicit wins
# - incompatible types: runtime error

# Chain behavior in control flow:
# - if/else: output of last step in executed branch
# - loop: output of last step in last iteration
# - parallel: array of all branch outputs in declaration order
```

--------------------------------

### Context Assignment (set)

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Writes values into execution.context for use in subsequent CEL expressions.

```APIDOC
## Set

### Description
Writes one or more values into execution.context, making them available to all subsequent CEL expressions.

### Parameters
#### Request Body
- **<key>** (CEL expression) - Required - Each key becomes execution.context.<key>.

### Request Example
```yaml
flow:
  - set:
      token: workflow.inputs.api_token
      region: env.AWS_REGION
```
```

--------------------------------

### Define Input Precedence Logic

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Visual representation of how inputs are resolved based on the presence of chain, participant, and flow override inputs.

```text
Nothing defined                          → string in, string out (chain passthrough)
Chain only                               → previous step output becomes input
Participant input only                   → CEL expressions resolve input
Flow override input only                 → CEL expressions resolve input
Participant input + flow override input  → merge (flow override wins on conflict)
Chain + participant input                → merge (participant input wins on conflict)
Chain + participant input + flow override → three-way merge (flow override > participant > chain)
With schema                              → validation via JSON Schema
```

--------------------------------

### Implement Wait Constructs

Source: https://context7.com/duckflux/spec/llms.txt

Pauses execution based on events, durations, or polling conditions. The behavior is determined by the fields provided.

```yaml
flow:
  # Wait for event
  - wait:
      event: "approval.granted"
      match: event.userId == workflow.inputs.approver
      timeout: 24h
      onTimeout: fail

  # Wait for duration (sleep)
  - wait:
      timeout: 30s

  # Wait for condition (polling)
  - wait:
      until: now >= timestamp("2024-04-01T09:00:00Z")
      poll: 1m
      timeout: 48h

  # Wait for external state change
  - wait:
      until: api_check.output.status == "ready"
      poll: 10s
      timeout: 5m
      onTimeout: skip
```

--------------------------------

### Configure Workflow Output

Source: https://context7.com/duckflux/spec/llms.txt

Define the final workflow result using single values, structured mappings, or schema-validated objects.

```yaml
# Single value output
output: reviewer.output.summary

# Structured output mapping
output:
  approved: reviewer.output.approved
  code: coder.output.code
  testResults: tests.status

# With schema validation
output:
  schema:
    approved:
      type: boolean
      required: true
    code:
      type: string
    score:
      type: integer
      minimum: 0
      maximum: 10
  map:
    approved: reviewer.output.approved
    code: coder.output.code
    score: reviewer.output.score
```

--------------------------------

### Assign Context with Set Construct

Source: https://context7.com/duckflux/spec/llms.txt

Writes values to execution.context for use in subsequent CEL expressions. This construct does not produce output.

```yaml
flow:
  # Simple context assignment
  - set:
      token: workflow.inputs.api_token
      region: env.AWS_REGION
      timestamp: string(now)

  # Conditional assignment
  - if:
      condition: has(workflow.inputs.notion_token)
      then:
        - set:
            notion_token: workflow.inputs.notion_token
      else:
        - set:
            notion_token: env.NOTION_TOKEN

  # Use context values
  - as: fetch_pages
    type: http
    url: "'https://api.notion.com/v1/pages'"
    headers:
      Authorization: "'Bearer ' + execution.context.notion_token"
```

--------------------------------

### Accessing Environment Variables

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Access environment variables injected by the runtime within CEL expressions.

```text
env.API_KEY
env.NODE_ENV
```

--------------------------------

### Define Timeout Precedence

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

The hierarchy of timeout configuration levels.

```text
flow-level > participant-level > defaults > runtime default (no timeout)
```

--------------------------------

### HTTP Request Configuration

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Defines the structure for performing HTTP requests within a workflow.

```APIDOC
## HTTP Request Configuration

### Description
Configures an HTTP request step within a workflow.

### Parameters
#### Request Body
- **url** (string) - Required - Target URL. Supports CEL expressions.
- **method** (string) - Optional - HTTP method: GET, POST, PUT, PATCH, DELETE.
- **headers** (object) - Optional - HTTP headers. Values support CEL expressions.
- **body** (string or object) - Optional - Request body. Supports CEL expressions.
```

--------------------------------

### Conditional Branching with if/then/else

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Routes execution based on a CEL expression. The 'else' block is optional.

```yaml
flow:
  - if:
      condition: <CEL expression>
      then:
        - <step>
        - ...
      else:
        - <step>
        - ...
```

--------------------------------

### Define Workflow Inputs with JSON Schema

Source: https://context7.com/duckflux/spec/llms.txt

Use the inputs block to define and validate workflow parameters using JSON Schema types and constraints.

```yaml
inputs:
  repoUrl:
    type: string
    format: uri
    required: true
    description: "Git repository URL"
  branch:
    type: string
    default: "main"
    pattern: "^[a-zA-Z0-9_-]+$"
  maxRetries:
    type: integer
    minimum: 1
    maximum: 10
    default: 3
  tags:
    type: array
    items:
      type: string
  config:
    type: object

flow:
  - type: exec
    run: git clone "${REPO}" --branch="${BRANCH}"
    input:
      REPO: workflow.inputs.repoUrl
      BRANCH: workflow.inputs.branch
```

--------------------------------

### Define a Loop Construct in YAML

Source: https://context7.com/duckflux/spec/llms.txt

Repeats steps based on a CEL condition or maximum iteration count. Loop context variables like loop.iteration are available within the steps.

```yaml
flow:
  - as: coder
    type: exec
    run: ./code.sh

  - loop:
      as: round  # Rename loop context variable
      until: reviewer.output.approved == true
      max: workflow.inputs.maxReviewRounds
      steps:
        - as: reviewer
          type: exec
          run: ./review.sh

        - coder:
            when: reviewer.output.approved == false
            input:
              feedback: reviewer.output.comments
              iteration: string(round.iteration)

  # Loop context variables available:
  # loop.index     - 0-based iteration index
  # loop.iteration - 1-based iteration number
  # loop.first     - true on first iteration
  # loop.last      - true on last iteration (when max is defined)
```

--------------------------------

### Define Error Handling Precedence

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

The hierarchy of error handling configuration levels.

```text
flow-level onError > participant-level onError > defaults.onError > global default (fail)
```

--------------------------------

### Input Merge Precedence

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Defines the order of precedence for input merging.

```text
chain value < participant base input < flow override input
```

--------------------------------

### Access Runtime Variables with CEL

Source: https://context7.com/duckflux/spec/llms.txt

Use Google CEL expressions to access workflow metadata, execution context, participant results, environment variables, and loop context. Variables are prefixed (e.g., `workflow.*`, `execution.*`, `env.*`, `loop.*`).

```yaml
flow:
  - set:
      # workflow.* - Definition metadata
      wf_id: workflow.id
      wf_name: workflow.name

      # execution.* - Current run metadata
      exec_id: execution.id
      started: string(execution.startedAt)

      # env.* - Environment variables
      api_key: env.API_KEY
      node_env: env.NODE_ENV

      # now - Current timestamp
      current_time: string(now)

  - as: coder
    type: exec
    run: ./code.sh

  - type: exec
    run: echo "Results"
    input:
      # <step>.* - Named participant result
      STATUS: coder.status        # success, failure, skipped
      OUTPUT: coder.output        # step output (string or map)
      STARTED: string(coder.startedAt)
      FINISHED: string(coder.finishedAt)
      DURATION: string(coder.duration)
      RETRIES: string(coder.retries)
      ERROR: coder.error          # when status == "failure"

  - loop:
      max: 5
      steps:
        - type: exec
          run: echo "Iteration ${ITER}"
          input:
            # loop.* - Iteration context
            INDEX: string(loop.index)       # 0-based
            ITER: string(loop.iteration)    # 1-based
            FIRST: string(loop.first)       # true on first
            LAST: string(loop.last)         # true on last
```

--------------------------------

### Loop Construct in Flow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Repeats a set of steps until a CEL condition evaluates to 'true' or a maximum iteration count is reached. At least one of 'until' or 'max' must be present.

```yaml
flow:
  - loop:
      until: <CEL expression>
      max: <integer>
      as: <identifier>
      steps:
        - <step>
        - ...
```

--------------------------------

### Wait for Event

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Pauses execution until a specific event occurs, matching a CEL expression.

```yaml
- wait:
    event: <event name>
    match: <CEL expression>
    timeout: <duration>
    onTimeout: <fail | skip>
```

--------------------------------

### Conditional Branching (if/then/else)

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Evaluates a CEL expression to route execution flow.

```APIDOC
## Conditional Branching

### Description
Evaluates a CEL expression and routes execution to the matching branch.

### Parameters
#### Request Body
- **condition** (CEL expression) - Required - Boolean condition.
- **then** (array) - Required - Steps executed when the condition is true.
- **else** (array) - Optional - Steps executed when the condition is false.

### Request Example
```yaml
flow:
  - if:
      condition: <CEL expression>
      then:
        - <step>
      else:
        - <step>
```
```

--------------------------------

### Loop Control Flow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Defines the structure for repeating steps in a workflow.

```APIDOC
## Loop Control Flow

### Description
Repeats a set of steps until a CEL condition evaluates to true, or a maximum iteration count is reached.

### Parameters
#### Request Body
- **until** (CEL expression) - Conditional - Exit condition. Loop terminates when this evaluates to true.
- **max** (integer) - Conditional - Maximum number of iterations.
- **as** (string) - Optional - Renames the loop context variable (default: loop).
- **steps** (array) - Required - Steps to execute on each iteration.
```

--------------------------------

### Wait for Duration

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Pauses execution for a specified duration.

```yaml
- wait:
    timeout: <duration>
```

--------------------------------

### Define Sub-Workflows

Source: https://context7.com/duckflux/spec/llms.txt

Reference other YAML files as sub-workflows using `type: workflow`. Paths are relative to the parent workflow's directory. Sub-workflows have isolated execution contexts.

```yaml
# main.yaml
participants:
  reviewCycle:
    type: workflow
    path: ./review-loop.yaml
    input:
      repo: workflow.inputs.repoUrl

flow:
  - coder

  # As inline step
  - as: reviewCycle
    type: workflow
    path: ./review-loop.yaml
    input:
      repo: workflow.inputs.repoUrl
    timeout: 1h
    onError: skip

  - deploy

# review-loop.yaml (sub-workflow)
inputs:
  repo:
    type: string
    required: true

flow:
  - loop:
      until: reviewer.output.approved
      max: 5
      steps:
        - as: reviewer
          type: exec
          run: ./review.sh

output: reviewer.output
```

--------------------------------

### Event Emission

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Defines the structure for emitting events within a workflow.

```APIDOC
## Event Emission

### Description
Emits an event to the system.

### Parameters
#### Request Body
- **event** (string) - Required - Event name to emit.
- **payload** (string or object) - Optional - Event payload. A single CEL expression or a map of CEL expressions.
- **ack** (boolean) - Optional - If true, block until delivery is acknowledged. Default: false.
- **onTimeout** (string) - Optional - Timeout behavior in acknowledged mode (ack: true): fail or skip. Default: fail.
```

--------------------------------

### Parallel Execution in Flow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Executes multiple steps concurrently. The flow continues only after all parallel steps have completed. Branches can contain inline participants.

```yaml
flow:
  - parallel:
      - stepA
      - stepB
      - stepC
```

--------------------------------

### Minimal Duckflux Workflow

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

A minimal valid Duckflux workflow document requires at least a 'flow' array. The parser must reject workflows with an empty 'flow'.

```yaml
flow:
  - type: exec
    run: echo "Hello, duckflux!"
```

--------------------------------

### Define Participants

Source: https://context7.com/duckflux/spec/llms.txt

Participants can be defined as reusable blocks, named inline, or anonymous inline within the flow.

```yaml
participants:
  # Reusable participant - can be referenced multiple times
  tests:
    type: exec
    run: npm test

flow:
  # Reference reusable participant
  - tests

  # Named inline participant - addressable by name
  - as: processor
    type: exec
    run: ./process.sh

  # Anonymous inline participant - output via chain only
  - type: exec
    run: echo "setup complete"

  # Access named participant output
  - type: exec
    run: echo "Tests took ${DURATION}"
    input:
      DURATION: string(tests.duration)
```

--------------------------------

### Wait for Condition

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Polls a CEL expression until it evaluates to true or a timeout occurs.

```yaml
- wait:
    until: <CEL expression>
    poll: <duration>
    timeout: <duration>
    onTimeout: <fail | skip>
```

```yaml
- wait:
    until: now >= timestamp("2024-04-01T09:00:00Z")
    poll: 1m
    timeout: 48h
```

--------------------------------

### Sub-workflow Invocation

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Defines the structure for invoking a sub-workflow.

```APIDOC
## Sub-workflow Invocation

### Description
Invokes a sub-workflow file.

### Parameters
#### Request Body
- **path** (string) - Required - Path to the sub-workflow YAML file, resolved relative to the parent workflow's directory.
```

--------------------------------

### Named Inline Participant

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Define a participant inline within the 'flow' and assign it a name using 'as'. This name can be used to reference the participant's results.

```yaml
flow:
  - as: tests
    type: exec
    run: npm test
```

--------------------------------

### Exec Participant with Custom CWD

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

The 'exec' participant type allows specifying a custom working directory ('cwd') which supports CEL expressions.

```yaml
flow:
  - type: exec
    run: "ls -l"
    cwd: "/app/src"
```

--------------------------------

### Wait Operations

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Pauses execution based on events, durations, or polling conditions.

```APIDOC
## Wait

### Description
Pauses execution. The mode is determined by which fields are present.

### Parameters
#### Request Body
- **event** (string) - Optional - Event name to wait for.
- **match** (CEL expression) - Optional - Condition to match event payload.
- **timeout** (duration) - Optional - Duration to wait before timeout.
- **onTimeout** (string) - Optional - Action on timeout (fail or skip).
- **until** (CEL expression) - Optional - Condition to wait for (polling).
- **poll** (duration) - Optional - Polling interval.

### Request Example
```yaml
- wait:
    until: now >= timestamp("2024-04-01T09:00:00Z")
    poll: 1m
    timeout: 48h
```
```

--------------------------------

### Anonymous Inline Participant

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Define a participant inline within the 'flow' without a name. These participants cannot be referenced by name and their output is accessible only via the implicit I/O chain.

```yaml
flow:
  - type: exec
    run: echo "setup complete"
  - deploy
```

--------------------------------

### Workflow Inputs without Schema

Source: https://context7.com/duckflux/spec/llms.txt

Defines workflow inputs without explicit JSON Schema validation, where all fields are treated as strings by default.

```yaml
# Without schema (all fields treated as strings)
inputs:
  repoUrl:
  branch:
```

--------------------------------

### Override Participant Fields in Flow

Source: https://context7.com/duckflux/spec/llms.txt

Allows overriding participant configuration at the flow level. Input fields are merged with the participant's base definition.

```yaml
participants:
  fetch_page:
    type: exec
    input:
      NOTION_TOKEN: execution.context.token
    run: |
      curl -sS "https://api.notion.com/v1/pages/${PAGE_ID}" \
        -H "Authorization: Bearer ${NOTION_TOKEN}"

flow:
  # Override timeout and error handling
  - coder:
      timeout: 30m
      onError: skip

  # Input merge: base input + flow override input
  - fetch_page:
      input:
        PAGE_ID: workflow.inputs.story_id

  # Reuse with different input
  - fetch_page:
      input:
        PAGE_ID: open_task.output
```

--------------------------------

### Flow-Level Participant Overrides

Source: https://github.com/duckflux/spec/blob/main/SPEC.md

Overrides participant configuration for a specific invocation.

```yaml
flow:
  - coder:
      timeout: 30m
      onError: skip
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.