DSL Reference

Workflow files use the .cloche extension and live in .cloche/. The first step declared is the entry point. Graphs are validated at parse time: all results must be wired, no orphaned steps, and an entry point must exist.

Basic Structure

workflow "develop" {
  container {
    image         = "my-project:latest"
    agent_command = "claude"
  }

  step implement {
    prompt  = file(".cloche/prompts/implement.md")
    results = [success, fail]
  }

  step test {
    run     = "make test && make lint"
    results = [success, fail]
  }

  step fix {
    prompt       = file(".cloche/prompts/fix.md")
    max_attempts = 3
    results      = [success, fail, give-up]
  }

  implement:success -> test
  implement:fail    -> abort
  test:success      -> done
  test:fail         -> fix
  fix:success       -> test
  fix:fail          -> abort
  fix:give-up       -> abort
}

Step Configuration

A step must have exactly one of prompt, run, workflow_name, or poll.

The file() Function

file("path") reads the file at the given path relative to the working directory (/workspace/ in containers) at execution time, not parse time.

prompt = file(".cloche/prompts/implement.md")

Prompt Templates

Prompt files referenced by file("...") are evaluated as templates before the agent runs. The {{ }} syntax injects runtime values.

Built-in variables:

Built-ins shadow KV keys with the same name. An unresolvable variable fails the step before the agent runs.

Agent Declarations

Declare reusable named agents at the workflow level and reference them from steps.

workflow "develop" {
  agent claude {
    command = "claude"
    args    = "-p --output-format stream-json"
  }

  agent codex {
    command = "codex"
    args    = "--full-auto"
  }

  step implement {
    prompt  = file(".cloche/prompts/implement.md")
    agent   = claude
    results = [success, fail]
  }

  step review {
    prompt  = file(".cloche/prompts/review.md")
    agent   = codex
    results = [success, fail]
  }

  implement:success -> review
  implement:fail    -> abort
  review:success    -> done
  review:fail       -> implement
}

Agent block fields:

Resolution order (highest to lowest priority):

1. Step-level agent_command / agent_args
2. agent = <identifier> declaration
3. Workflow-level config block
4. CLOCHE_AGENT_COMMAND environment variable
5. Default: claude

Referencing an undeclared agent is a validation error. Only agent steps may use the agent key. Duplicate agent names within a workflow are a parse error.

Configuration Blocks

container {} (container workflows)

workflow "develop" {
  container {
    id            = "dev-env"
    image         = "my-project:latest"
    agent_command = "claude"
    agent_args    = "-p --dangerously-skip-permissions"
    memory        = "4g"
    network_allow = ["docs.python.org", "api.example.com"]
  }
  ...
}

Supported keys: id, image, agent_command, agent_args, memory, network_allow.

network_allow is parsed but not yet enforced — containers currently run with unrestricted network access.

host {} (host workflows)

workflow "main" {
  host {
    agent_command = "claude"
  }
  ...
}

Supported keys: agent_command, agent_args. An empty host {} block is valid.

Repository Declarations

Repositories are configured in .cloche/config.toml as [[repositories]] entries. Within .cloche files, top-level repository blocks annotate each repository:

repository "backend" {
  path = "./repos/backend"
  url  = "https://github.com/example/backend"
}

Repository blocks are top-level constructs, not nested inside workflow blocks. Workflows can declare which repositories they use with the repos field:

workflow "develop-backend" {
  repos = ["backend"]
  ...
}

repos documents intent and surfaces in cloche project; the runtime does not enforce it.

Step Environment Variables

Cloche injects environment variables into every step invocation. The available variables differ between host and container contexts.

Host steps

Container steps

See Communicating Between Steps for how to pass data between steps using these variables, the KV store, and shared files.

Container IDs

Every container workflow has a container id used to identify which shared container to use per run attempt. Set via the id key in container {}. Default id is _default.

Workflows sharing the same id share a container per attempt:

workflow "develop" {
  container {
    id    = "dev-env"
    image = "my-project:latest"
  }
  ...
}

workflow "review" {
  container {
    id = "dev-env"  // shares the same container as "develop"
  }
  ...
}

cloche validate enforces consistent config for workflows sharing a container id.

Wiring

Connect steps with step:result -> next_step:

implement:success -> test
implement:fail    -> abort
test:success      -> done
test:fail         -> fix

Retry Loops

Wire failures back to earlier steps and use max_attempts to cap retries. When attempts are exhausted, the step returns give-up:

step fix {
  prompt       = file(".cloche/prompts/fix.md")
  max_attempts = 2
  results      = [success, fail, give-up]
}

test:fail   -> fix
fix:success -> test   // retry the test
fix:fail    -> abort
fix:give-up -> abort

Poll Steps

A poll step pauses a workflow until an external decision is available — a code review, an approval gate, a CI run, or any event the pipeline needs to wait for. The orchestrator polls a shell command at a fixed interval until the script reports a decision, the step times out, or the script fails.

Poll steps work in both host and container workflows. In a host workflow the daemon’s orchestration loop drives the polling. In a container workflow the in-container agent runs a standalone polling loop.

step code-review {
  poll     = "scripts/check-pr-review.sh"
  interval = "5m"
  timeout  = "48h"
  results  = [approved, fix]
}

code-review:approved -> merge
code-review:fix      -> address-feedback
code-review:timeout  -> escalate     // or omit; default routes to abort

The polling script reports a decision by printing CLOCHE_RESULT:<wire-name> to stdout, the same mechanism as script steps. The key difference is what happens when no marker is printed:

Polling cadence

The default timeout for poll steps is 72h (vs. 30m for other step types). The first poll fires immediately; subsequent polls fire no sooner than interval after the previous poll completes. interval is a no-sooner-than constraint, not a strict schedule — actual poll times depend on the loop tick rate and on how long the previous invocation took, so expect polls to land within ~30 seconds of the ideal time.

Overlapping invocations. If a poll is still running when the next interval comes due, that interval is skipped. If a single invocation runs longer than 4x interval (three consecutive skips), the step produces a fail result and follows the fail wire.

Script execution environment

Poll scripts run under sh -c. In a host workflow the working directory is the project’s main git worktree. In a container workflow it is /workspace/. The following variables are injected on every invocation:

Reading run context

Poll scripts can read values written to the run’s KV store by earlier steps via cloche get <key> (host-side) or clo get <key> (container-side). The KV store persists for the lifetime of the run.

# In an earlier container step (e.g. create-pr):
clo set pr_id 1234

# In the polling script:
pr_id=$(cloche get pr_id)
state=$(gh pr view "$pr_id" --json state -q .state)
case "$state" in
  MERGED) echo "CLOCHE_RESULT:approved" ;;
  CLOSED) echo "CLOCHE_RESULT:rejected" ;;
  *)      ;;  # still open → exit 0 with no marker → pending
esac

Idempotency

Poll scripts are invoked once per interval for the lifetime of the step — which can easily be dozens or hundreds of invocations over a 72-hour window. Any side effect (posting a comment, sending a notification, creating a ticket) must be guarded so it runs at most once. Use the KV store to record that the side effect has occurred:

if [ "$(cloche get notified_reviewer)" != "yes" ]; then
  slack-notify "@reviewer PR ready"
  cloche set notified_reviewer yes
fi

Visibility in cloche list / cloche status

While a poll step is active, its run’s state is set to waiting, which cloche list and cloche status surface distinctly from running. The daemon also records last_poll_at and the step name so you can see how long the step has been waiting and when it last polled.

Poll Steps

A poll step runs a script at a fixed interval until a decision is available. The step type is inferred from the poll field, just like other step types. Poll steps work in both host and container workflows — useful for waiting on CI runs, PR reviews, external APIs, approval gates, or any condition that resolves asynchronously.

step code-review {
  poll     = "scripts/check-pr-review.sh"
  interval = "5m"
  timeout  = "48h"
  results  = [approved, fix]
}

code-review:approved -> merge
code-review:fix      -> address-feedback
code-review:timeout  -> escalate

Exit 0 with no CLOCHE_RESULT: marker means “not yet” — Cloche polls again after interval. Exit 0 with a marker follows the named wire. Non-zero exit with no marker follows fail.

Parallel Branches (Fanout)

Wire one result to multiple targets for concurrent execution:

test:success -> lint
test:success -> quality

Collect (Join)

Synchronize parallel branches with collect:

collect all(lint:success, quality:success) -> done
collect any(lint:success, quality:success) -> done

all fires when every condition is met. any fires when at least one is.

Comments

Line comments use //:

// This is a comment
implement:success -> test  // inline comment

Examples

Host Workflow

workflow "list-tasks" {
  host {}

  step get-tasks {
    run     = "python3 .cloche/scripts/get-tasks.py"
    results = [success, fail]
  }

  get-tasks:success -> done
  get-tasks:fail    -> abort
}

workflow "main" {
  host {}

  step claim-task {
    run     = "python3 .cloche/scripts/claim-task.py"
    results = [success, fail]
  }

  step develop {
    workflow_name = "develop"
    results       = [success, fail]
  }

  step finalize {
    run     = "python3 .cloche/scripts/finalize.py"
    results = [success, fail]
  }

  claim-task:success -> develop
  claim-task:fail    -> abort
  develop:success    -> finalize
  develop:fail       -> finalize
  finalize:success   -> done
  finalize:fail      -> abort
}

Container Workflow with Parallel Validation

workflow "develop" {
  step implement {
    prompt  = file("prompts/implement.md")
    results = [success, fail]
  }

  step test {
    run     = "bundle exec rake test 2>&1"
    results = [success, fail]
  }

  step lint {
    run     = "bundle exec rubocop 2>&1"
    results = [success, fail]
  }

  step quality {
    run     = "python3 scripts/quality-check.py 2>&1"
    results = [success, fail]
  }

  step fix {
    prompt       = file("prompts/fix.md")
    max_attempts = 2
    results      = [success, fail, give-up]
  }

  implement:success -> test
  implement:fail    -> abort

  test:success -> lint
  test:success -> quality
  test:fail    -> fix

  lint:fail    -> fix
  quality:fail -> fix
  collect all(lint:success, quality:success) -> done

  fix:success  -> test
  fix:fail     -> abort
  fix:give-up  -> abort
}