Aegis Orchestrator
Reference

Workflow Manifest Reference

Complete specification for the WorkflowManifest YAML format — schema, field definitions, all seven state kinds including ContainerRun for CI/CD steps, Subworkflow for workflow composition, consensus strategies, and complete examples.

Workflow Manifest Reference

API Version: 100monkeys.ai/v1 | Kind: Workflow | Status: Canonical

A Workflow Manifest is a declarative YAML document defining a finite state machine (FSM) that coordinates agent executions, container-based CI/CD steps, system commands, and human approval gates into a durable, restartable sequence. It uses the same Kubernetes-style apiVersion/kind/metadata/spec format as the Agent Manifest.


Annotated Full Example

apiVersion: 100monkeys.ai/v1      # required; must be exactly this value
kind: Workflow                     # required; must be exactly "Workflow"

metadata:
  name: dev-pipeline               # required; unique DNS-label name (lowercase, alphanumeric, hyphens)
  version: "1.0.0"                 # required; semantic version. (name + version) must be unique.
                                   # Overwriting an existing version requires the `force` parameter in management tools.
  description: "Iterative code generation with multi-judge validation."  # optional
  labels:                          # optional; key-value pairs for filtering and discovery
    category: development
    pattern: iterative-refinement
  annotations:                     # optional; non-identifying metadata
    docs: "https://docs.example.com/workflows/dev-pipeline"
  output_schema:                   # optional; JSON Schema declaring the workflow's output shape
    type: object
    properties:
      result:
        type: string
      score:
        type: number
      iterations:
        type: integer
    required:
      - result
  output_template:                 # optional; Handlebars expressions evaluated against the final Blackboard
    result: "{{EXECUTE.output.stdout}}"
    score: "{{VALIDATE.score}}"
    iterations: "{{blackboard.iteration_number}}"

spec:
  initial_state: GENERATE          # required; name of the first state to enter

  # Optional: global constants available to all states via {{workflow.context.KEY}}
  context:
    max_iterations: 10
    validation_threshold: 0.95

  # Optional: workflow-level shared storage (volumes accessible by any state)
  storage:
    workspace:                     # default shared workspace; auto-created at workflow start
      storage_class: ephemeral     # ephemeral | persistent
      ttl_hours: 1
      size_limit_mb: 1000
    shared_volumes:
      - name: code-artifacts
        storage_class: ephemeral
        ttl_hours: 24
        size_limit_mb: 500

  # Required: state machine definition (map of state name → state definition)
  states:

    GENERATE:
      kind: Agent                  # StateKind: Agent | System | Action | Human | ParallelAgents | ContainerRun | ParallelContainerRun | Subworkflow
      agent: coder-v1              # required for Agent kind; deployed agent name or UUID
      input: |                     # Handlebars template rendered as the agent's task input
        {{#if blackboard.iteration_number}}
        Iteration {{blackboard.iteration_number}} failed.
        Error: {{state.feedback}}
        Fix the code.
        {{else}}
        {{intent}}
        {{/if}}
      volumes:                     # optional volume mounts for this state
        - volume: "{{workflow.storage.workspace}}"
          mount_path: /workspace
          access_mode: read-write
      transitions:
        - condition: always        # unconditional; first matching transition wins
          target: EXECUTE

    EXECUTE:
      kind: System
      command: python main.py      # required for System kind; shell command (Handlebars supported)
      env:
        CODE: "{{GENERATE.output}}"
        PYTHONPATH: /workspace
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

    VALIDATE:
      kind: Agent
      agent: judge-v1
      input: |
        Task: {{intent}}
        Output: {{EXECUTE.output.stdout}}
        Evaluate correctness and return JSON with score, confidence and reasoning.
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

    AWAIT_APPROVAL:
      kind: Human
      prompt: |                    # required for Human kind; message shown to operator
        Review the generated output and approve or reject.
        Output: {{EXECUTE.output.stdout}}
      timeout: 3600s               # optional; 3600s when omitted
      default_response: "no"       # optional; value taken if timeout elapses without signal
      transitions:
        - condition: input_equals_yes
          target: COMPLETE
        - condition: input_equals_no
          target: REFINE
          feedback: "{{human.feedback}}"

    AUDIT:
      kind: ParallelAgents
      agents:
        - agent: reviewer-v1
          input: "Review code quality: {{GENERATE.output}}"
          weight: 1.0              # optional; weight for consensus calculation (default 1.0)
          timeout_seconds: 120     # optional; per-agent timeout (default 60)
          poll_interval_ms: 500    # optional; polling interval (default 500)
        - agent: security-v1
          input: "Security audit: {{GENERATE.output}}"
          weight: 2.0              # security weighted higher
          timeout_seconds: 180
      consensus:
        strategy: weighted_average # weighted_average | majority | unanimous | best_of_n
        threshold: 0.85
        min_agreement_confidence: 0.75
        min_judges_required: 2     # optional; minimum judges that must complete (default 1)
        confidence_weighting:
          agreement_factor: 0.7    # weight for inter-judge agreement; sums to 1.0 with self_confidence_factor
          self_confidence_factor: 0.3
      transitions:
        - condition: consensus
          threshold: 0.85
          agreement: 0.75
          target: COMPLETE
        - condition: score_below
          threshold: 0.85
          target: REFINE
          feedback: "Audit failed (score: {{AUDIT.consensus.score}}): {{AUDIT.agents.0.output}}"

    REFINE:
      kind: System
      command: update_context
      env:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: finalize
      transitions: []              # empty transitions list = terminal state

    FAILED:
      kind: System
      command: "echo 'Max iterations reached'"
      transitions: []              # terminal state

Field Reference

Top-Level Fields

FieldTypeRequiredDescription
apiVersionstring✓Must be 100monkeys.ai/v1.
kindstring✓Must be Workflow.
metadataobject✓Manifest metadata.
specobject✓Workflow specification.

metadata

FieldTypeRequiredDescription
namestring✓Unique workflow name. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$.
versionstringManifest semantic version (e.g., "1.0.0").
descriptionstringHuman-readable purpose description.
labelsmap[string]stringKey-value labels for categorization and discovery.
annotationsmap[string]stringArbitrary non-identifying metadata (URLs, changelogs, JSON blobs).
input_schemaJSON Schema objectDeclares named inputs accepted at execution time. See metadata.input_schema.
output_schemaJSON Schema objectDeclares the shape of the workflow's structured output. See metadata.output_schema.
output_templatemap[string, string]Handlebars expressions that extract the workflow's final output from the Blackboard. See metadata.output_template.

metadata.input_schema

An optional JSON Schema object describing the named inputs this workflow accepts at execution time. Callers pass a JSON object matching this schema via --input (or the equivalent API field); the orchestrator validates the payload before the workflow starts.

FieldTypeRequiredDescription
input_schemaJSON Schema objectMust be a JSON Schema object with type: object.

Example:

metadata:
  name: data-pipeline
  version: "1.0.0"
  input_schema:
    type: object
    properties:
      dataset_path:
        type: string
        description: Path to the input dataset
      environment:
        type: string
        enum: [staging, production]
    required:
      - dataset_path
      - environment

The following JSON Schema property types are supported. The Zaru client context panel renders each type as a specific UI element:

JSON Schema typeZaru UI control
stringText input
number / integerNumber spinner
booleanCheckbox
enumDropdown select
objectNested form group
arrayRepeatable row builder

When input_schema is present, the orchestrator validates the caller's input payload before creating the WorkflowExecution. A payload that fails schema validation is rejected with HTTP 422; no workflow execution is created. When input_schema is absent, any payload is accepted.

The validated payload is stored as WorkflowExecution.input and is immutable for the lifetime of the execution. It is exposed to all workflow states via the {{input.KEY}} Handlebars namespace — not just the first state.

input_schema vs spec.context: spec.context holds author-time constants declared in the manifest, accessible via {{workflow.context.KEY}}. metadata.input_schema declares caller-supplied runtime values, accessible via {{input.KEY}}. These are separate namespaces — context is static, input is dynamic.

Richer example with multiple field types:

metadata:
  name: invoice-pipeline
  description: "Processes and validates invoice documents."
  input_schema:
    type: object
    required:
      - document_text
      - vendor_id
    properties:
      document_text:
        type: string
        description: "Raw invoice text to process."
      vendor_id:
        type: string
        description: "Vendor identifier for routing."
      currency:
        type: string
        enum: ["USD", "EUR", "GBP"]
        description: "Currency for amount normalization. Default: USD."
      strict_validation:
        type: boolean
        description: "Whether to apply strict validation rules. Default: false."

CLI invocation:

aegis workflow run invoice-pipeline \
  --input '{"document_text": "Invoice #1234...", "vendor_id": "acme-corp", "currency": "USD"}'

Attachments example. Workflows that consume uploaded files declare an attachments array in metadata.input_schema. The validated array is exposed to every state via {{input.attachments}} and can be propagated to states that dispatch agents capable of reading attachments.

metadata:
  name: document-pipeline
  input_schema:
    type: object
    properties:
      attachments:
        type: array
        items:
          type: object
          properties:
            volume_id: { type: string }
            path: { type: string }
            name: { type: string }
            mime_type: { type: string }
            size: { type: integer }
            sha256: { type: string }
          required: [volume_id, path, name, mime_type, size]
    required: [attachments]

States that dispatch agents to process the attachments forward {{input.attachments}} into the agent's input. The workflow engine renders this Handlebars expression at the state transition (resolving against the live Blackboard), and the resulting array is carried on the dispatch's attachments field. The receiving agent must declare its own attachments field in spec.input_schema and include aegis.attachment.read in spec.tools. Inside the receiving agent, attachments are surfaced as input.attachments in the substituted prompt input — the agent's task.instruction references them in prose, not via Handlebars iteration (the agent's instruction body is not re-rendered at runtime).

Scope: Workflows are deployed at Tenant scope by default. Use --scope user for personal workflows or --scope global for platform-wide workflows (requires operator role). After deployment, use aegis workflow promote and aegis workflow demote to change scope. Scope is not a manifest field — it is controlled via the CLI --scope flag or API parameter at deploy time.

metadata.output_schema

An optional JSON Schema object declaring the shape of the workflow's structured output. When present, the engine validates final_output against this schema at workflow completion. The schema must have type: object and supports the same draft-07 subset as input_schema.

FieldTypeRequiredDescription
output_schemaJSON Schema objectMust be a JSON Schema object with type: object.

Example:

metadata:
  name: data-extraction
  version: "1.0.0"
  output_schema:
    type: object
    properties:
      summary:
        type: string
        description: Natural language summary of the extraction
      record_count:
        type: integer
        description: Number of records extracted
      success:
        type: boolean
        description: Whether extraction completed without errors
    required:
      - summary
      - record_count

metadata.output_template

An optional object where each leaf value is a Handlebars expression evaluated against the final Blackboard at workflow completion. Each value is rendered independently (not as a single template). The rendered values are type-coerced according to the corresponding output_schema property type, validated, and stored as the WorkflowExecution.final_output.

FieldTypeRequiredDescription
output_templatemap[string, string]Each key matches a property in output_schema; each value is a Handlebars expression.

Type coercion rules:

Schema typeCoercion
stringUsed as-is (no conversion).
integerParsed with parseInt.
numberParsed with parseFloat.
booleanCompared to "true" (case-sensitive).
objectParsed with JSON.parse.
arrayParsed with JSON.parse.

If coercion or schema validation fails, the workflow fails with a descriptive error identifying the field and the value that could not be coerced or validated.

Example (paired with the output_schema above):

metadata:
  name: data-extraction
  version: "1.0.0"
  output_schema:
    type: object
    properties:
      summary:
        type: string
      record_count:
        type: integer
      success:
        type: boolean
    required:
      - summary
      - record_count
  output_template:
    summary: "{{EXTRACT.output}}"
    record_count: "{{TRANSFORM.output.count}}"
    success: "{{VALIDATE.status}}"

In this example, when the workflow completes, the engine renders each template value against the final Blackboard, coerces record_count to an integer and success to a boolean, validates the result against output_schema, and stores it as final_output on the WorkflowExecution.

output_template and output_schema are independently optional. output_template can be used without output_schema (no type coercion or validation -- all values remain strings). output_schema can be used without output_template. When both are present, the template is rendered first, then coerced and validated against the schema.

spec

FieldTypeRequiredDescription
initial_statestring✓Name of the first state to enter. Must exist in spec.states.
max_total_transitionsintegerMaximum total state transitions before the workflow terminates. Default: 50. Ceiling: 100.
contextmap[string, any]Global constants accessible via {{workflow.context.KEY}}.
storageobjectWorkflow-level shared volume configuration.
default_scheduleobjectA recommended timing for a schedule of this workflow: cron (five fields, required), timezone (default UTC) and jitter_seconds (default 0, at most 3600). It starts nothing by itself. A manifest that carries spec.schedule is refused at registration.
repositoriesintegerThe number of repositories every run of this workflow must name with the starting call's repositories (see Repositories of a Run). A start naming another number is refused before anything is held: workflow '<name>' works on exactly <n> repository; this run names <m> (repositories when <n> is not 1). Absent: any number.
statesmap[string, WorkflowState]✓State machine definition. Must contain initial_state.

Repositories of a Run

A run works in a person's git repositories when its starting call (aegis.workflow.run, the other starting tools, a schedule) names them under the reserved top-level key repositories. The five starting tools (aegis.workflow.run, aegis.workflow.generate, aegis.agent.generate, aegis.task.execute and aegis.execute.intent) list it in their schemas and take each entry in one of two forms:

FormEntry
A binding by its id{"binding_id": "<id of one of your git repository bindings>", "branch": "<work branch>"}, branch optional. aegis.git.list lists your bindings.
A repository by its URL{"url": "<https:// or git@host:path URL, with no credential in it>", "ref": "<branch>", "branch": "<work branch>"}, ref (default main) and branch optional.

For an entry naming a URL, the platform reaches the repository only through the GitHub connection the run names, by its profile or chosen one by one. It finds your binding of that URL and ref made with that connection, or with none, and uses it; when you have none, it makes one before the run starts with that connection, labelled with the repository's name, and waits for its clone. A URL entry is refused before the run starts:

RefusalWhen
"This run has no profile that names your GitHub. Choose a profile that names it, then start the run again."The run names no GitHub connection.
"no active GitHub credential of yours"None of the GitHub connections the run names is an active GitHub connection of yours.
"you have <n> active GitHub credentials, so which one reaches this repository is not known; link the repository with the one to use, then name its binding_id"The run names several active GitHub connections.
"your binding of this repository is linked with another GitHub credential than the one this run names; name its binding_id, or choose a profile that names that credential"Your binding of that URL and ref was made with another GitHub connection.
The clone's own sentenceThe clone of the new binding failed, for example a repository the credential does not reach; the binding is removed.
"this node cannot find a repository by its URL; name its binding_id"The node cannot find or make a binding by URL.

Any other shape (an entry naming both binding_id and url, a URL with user info in it, an unknown field) or a binding entry that names label, ref, started_from or author is refused with 'repositories' must be a list of objects naming a binding_id or a url and, optionally, a ref and a branch: a binding's label, ref, start and author are the platform's to fill.

When the run starts, each repository is prepared on its own work branch, and its entry is filled with the binding's label, its ref (the binding's git ref) and started_from, the commit the work branch started from. The run's first repository is written onto the Blackboard as repository:

VariableDescription
{{repository.label}}The binding's label.
{{repository.path}}/workspace/<label>, where an agent state sees the working tree.
{{repository.branch}}The run's work branch.
{{repository.ref}}The binding's ref: the branch a landing moves.
{{repository.started_from}}The commit the work branch started from.

A field the entry does not carry is null. No credential and no URL is on the Blackboard.

A repository's work branch is the entry's branch, else aegis/ and the first eight characters of the run's execution id; it is checked out from the remote's copy when the remote has it, else created from the binding's ref. Each repository is mounted read-write at /workspace/<label> in every container of the run and held by the run until it ends, however it ends. The mount shows the clone's working tree at its root: /workspace/<label>/README.md is the repository's README.md. An agent state of the run writes only inside the run's repositories: fs.write, fs.edit, fs.multi_edit, fs.create_dir and fs.delete refuse a path outside them, before anything is written, with "'<path>' is outside this run's repository; this step writes only under <mount>"; reads anywhere in the agent's volumes are unchanged (FSAL Tools). An entry is refused when the run starts, before any container:

RefusalWhen
"repository '<id>' is not one of yours"The binding is not yours; it is named by the first eight characters of its id.
"repository '<label>' is not ready (it is <status>); start the run when its clone has finished"The binding's clone has not finished.
"repository '<label>' is in use by another run"Another run holds it.
"repository '<label>' is named twice"Two entries name the same repository.
"a run works on its own branch, not on '<ref>'"branch is the binding's ref.

A run that has ended has released its repositories: a later state or child of it that would mount them is refused with "this run has ended, so its repositories are released", and takes no hold.

spec.storage

FieldTypeDescription
workspaceobjectDefault shared workspace. Auto-created at workflow start. Reference as {{workflow.storage.workspace}}.
workspace.storage_classephemeral | persistentVolume lifetime.
workspace.ttl_hoursintegerHours until auto-deletion (ephemeral only). Counted from workflow start.
workspace.size_limit_mbintegerMaximum volume size in MiB. Writes beyond this return ENOSPC.
shared_volumesobject[]Additional named shared volumes.
shared_volumes[].namestringUnique name. Reference as {{workflow.storage.shared_volumes.NAME}}.
shared_volumes[].storage_classephemeral | persistentVolume lifetime.
shared_volumes[].ttl_hoursintegerHours until auto-deletion (ephemeral only).
shared_volumes[].size_limit_mbintegerMaximum volume size in MiB (ephemeral only).
shared_volumes[].volume_idstringPre-created volume UUID (persistent only).

spec.states[*] — Common Fields

FieldTypeRequiredDefaultDescription
kindstring✓Agent | System | Action | Human | ParallelAgents | ContainerRun | ParallelContainerRun | Subworkflow
max_state_visitsinteger5Maximum times this state can be entered before the workflow terminates. Ceiling: 20.
timeoutstring300sMaximum time in this state. Human-readable: "300s", "5m", "1h".
volumesobject[]Volume mounts for this state (Agent kind).
volumes[].volumestring✓Volume reference. Supports Handlebars: {{workflow.storage.workspace}}.
volumes[].mount_pathstring✓Absolute path inside the container.
volumes[].access_moderead-write | read-only✓Access mode enforced by AegisFSAL.
transitionsobject[]✓Ordered transition rules. Evaluated top-to-bottom; first match wins.

kind: Agent

FieldTypeRequiredDescription
agentstring✓Deployed agent name or UUID.
intentstringHandlebars template rendered as the per-state natural-language steering for the agent ({{intent}} variable in the agent's prompt template). Falls back to the workflow-level caller intent when absent.
inputstringHandlebars template rendered as the agent's task input. Supports {{intent}}, {{input.KEY}}, {{STATE.output}}, {{blackboard.KEY}}, {{state.feedback}}.
isolationinherit | firecracker | docker | processOverride isolation mode. Default: inherit (from node config).

When the state's agent declares spec.input_schema, the state's rendered input is validated against it before the agent starts. The rendered input is text; text that is a JSON object is validated as that object. For an agent that requires an object, render the input as JSON with the json helper in triple braces, so it is not HTML-escaped: input: '{"message": {{{json input.message}}} }'. A plain string is refused with "Input validation failed: the workflow state's input is a string, and the agent's input_schema wants an object; render the state's input as a JSON object".

When the agent completes, the Blackboard is updated under the state name:

{
  "status": "success|failed",
  "output": "<agent final text output>",
  "score": 0.91,
  "iterations": 2
}

Use {{STATE.output}}, {{STATE.status}}, or {{STATE.score}} in downstream states.

An Agent state starts its agent's run once. The Temporal worker gives the run the agent's own time limit (spec.security.resources.timeout, else 1,800 seconds) plus 60 seconds, and keeps the step alive while the run streams. A retry after the run has begun starts no second run: the worker asks the orchestrator to cancel the earlier run and fails the step. A failure to reach the orchestrator before the run begins is retried, at most three attempts. When the step ends before its run does, by its time limit or by cancellation, the worker asks the orchestrator to cancel the run, so no run outlives its step.

When the state's agent run fails, or judging its output ends in an error, the worker records the iteration's failure (WorkflowIterationFailed). A state that declares an on_failure transition then takes it, and its Blackboard entry is {"status": "failed", "error": "<the failure's message>"}; a state that declares none fails the run.

kind: System

FieldTypeRequiredDescription
commandstring✓Shell command to run. Handlebars templates supported.
envmap[string]stringEnvironment variables. Values support Handlebars.
workdirstringWorking directory. Default: /workspace.

Output is written to the Blackboard as {state_name}.output.stdout, {state_name}.output.stderr, and {state_name}.output.exit_code.

Use condition: exit_code_zero, condition: exit_code_non_zero, or condition: exit_code with a value to branch on exit status.

kind: Action

An Action state is one of the workflow's own operations. The state machine runs it itself: no agent chooses or calls it, and no shell runs. A System state runs a shell command; an Action state names its operation.

FieldTypeRequiredDescription
actionstring✓The operation, one of the five below. A literal, never a template: it is fixed when the manifest is parsed, so the manifest alone says what the state does.
argsmap[string]stringThe operation's arguments. Values support Handlebars and are rendered against the Blackboard when the state runs.
COMMIT:
  kind: Action
  action: repository_commit
  args:
    message: "the-forge: {{{first_line input.task}}}"
  transitions:
    - condition: on_failure
      target: FAILED
    - condition: on_success
      target: LAND
actionargsNeedsTouches the worldHow it runs
update_blackboardAny keys: each rendered value is written to the Blackboard under its key.NothingNoIn the Temporal worker; no process runs.
repository_diffNoneThe run's repositoryNoBy the orchestrator, on the repository the run holds.
repository_commitmessage, requiredThe run's repositoryNo: the commit stays on the work branch in the person's volume.By the orchestrator, on the repository the run holds.
repository_landNoneThe run's repositoryYesBy the orchestrator, as the call aegis.git.land, after the person's approval.
image_generateprompt, required; alias, size, count (1 to 4), path (default generated/)An image generation model on the nodeNoBy the orchestrator, as the call aegis.image.generate makes it, writing into the run's volume.

A manifest is checked against its actions when it is parsed. An unknown action is refused with "unknown action '<name>'; the actions are update_blackboard, repository_diff, repository_commit, repository_land, image_generate". An argument the action does not take is refused with "action 'repository_commit' takes message; '<key>' is not one" (for repository_diff and repository_land, "takes no arguments"), and a missing message with "action 'repository_commit' needs the argument 'message'". A repository action in a workflow whose spec.repositories is absent or 0 is refused with "action '<name>' works on the run's repository; this workflow declares none". image_generate takes prompt, alias, size, count and path, and a missing prompt is refused with "action 'image_generate' needs the argument 'prompt'". A workflow with an image_generate state is refused at registration, not at parse, on a node with no image generation model: "this node has no image generation model".

update_blackboard runs no process. Each args value is rendered against the Blackboard and written to the Blackboard under its key, as a string, so later states read it as {{blackboard.KEY}}. The state answers success with exit code 0 and updated, the list of keys written. The keys input, intent, tenant_id, attachments, workflow and blackboard, and the name of any state, are reserved: writing one fails the state before any key is written, with "update_blackboard cannot write the reserved key '<key>'."

SEED:
  kind: Action
  action: update_blackboard
  args:
    mailbox: "{{input.mailbox}}"
    page_prefix: "outreach"
  transitions:
    - condition: always
      target: COLLECT

Repository actions. repository_diff, repository_commit and repository_land are the workflow's own steps on the repository the run holds, run by the orchestrator.

ActionWhat it doesOutput
repository_diffThe run's change against started_from, as a unified diff. A diff over 1 MiB is refused, never cut off.diff, branch, ref
repository_commitStages every change and commits it on the work branch, as the run's person, with the message args.message.commit_sha, branch, ref
repository_landLands the work branch on the binding's ref as a fast-forward, after the person's approval (see aegis.git.land).commit_sha, branch, ref

A step that does not act fails the state with the orchestrator's sentence, also written as {state_name}.output.sentence, so its on_failure transition takes it: "this run holds no repository" for a run that holds none, "nothing to commit: working tree is clean" for a commit with no change, and a landing's refusals. A run that changed nothing lands nothing.

image_generate generates count images (default 1) from the rendered prompt with the image generation model alias names, or the node's first, and writes each into the run's volume under path (default generated/), numbered on from the files already there, its extension following its type (.jpg, .png, .webp). In a run with an agent state before it, the volume is the one its latest agent execution mounted, and each image is recorded as a file that execution produced; in a run with none, it is a volume the workflow execution owns, found or made for it. The state's output is {files: [{volume_id, path, content_type, size_bytes}]}. An empty prompt fails the state with "'prompt' is required: what the image shows" and a count outside 1 to 4 with "'count' is 1 to 4", before the model is called. A refusal (one of aegis.image.generate's, "'path' must name a directory inside the run's volume" for a path with . or .. in it, "this run has ended", "this run has no volume to write into") fails the state with its sentence as {state_name}.output.sentence, so its on_failure transition takes it.

DRAW:
  kind: Action
  action: image_generate
  args:
    prompt: "{{input.description}}"
    count: "2"
  transitions:
    - condition: on_failure
      target: FAILED
    - condition: on_success
      target: DONE

kind: Human

FieldTypeRequiredDescription
promptstring✓Message displayed to the operator. Handlebars templates supported.
timeoutstringDuration to wait for an answer. Default: 3600s. Without default_response, the workflow fails when it elapses.
default_responsestringSignal value automatically applied when timeout elapses.

The workflow suspends until signalled via the workflow execution API:

POST /v1/workflows/executions/{execution_id}/signal
Content-Type: application/json

{ "response": "yes" }

The signal payload is available as {{human.feedback}} in transition feedback strings and downstream input templates.

kind: ParallelAgents

FieldTypeRequiredDescription
agentsobject[]✓List of parallel agent configurations.
consensusobject✓Consensus aggregation configuration.

agents[]

FieldTypeRequiredDefaultDescription
agentstring✓Deployed agent name or UUID.
inputstringHandlebars template for this agent's task input.
weightnumber1.0Weight for consensus calculation.
timeout_secondsinteger60Per-agent execution timeout in seconds.
poll_interval_msinteger500Polling interval in milliseconds.

When an agent of the state declares spec.input_schema, the state's rendered input is validated against it before the agent starts. The rendered input is text; text that is a JSON object is validated as that object. For an agent that requires an object, render the input as JSON with the json helper in triple braces, so it is not HTML-escaped: input: '{"message": {{{json input.message}}} }'. A plain string is refused with "Input validation failed: the workflow state's input is a string, and the agent's input_schema wants an object; render the state's input as a JSON object".

consensus

FieldTypeRequiredDefaultDescription
strategystring✓weighted_average | majority | unanimous | best_of_n
thresholdnumber0.7Minimum score threshold (0.0–1.0).
min_agreement_confidencenumberMinimum consensus confidence required (0.0–1.0). Also accepted as agreement.
nintegerFor best_of_nNumber of top judges to average.
min_judges_requiredinteger1Minimum judges that must succeed. State fails if fewer complete.
confidence_weighting.agreement_factornumber0.7Weight for inter-judge agreement. Must sum to 1.0 with self_confidence_factor.
confidence_weighting.self_confidence_factornumber0.3Weight for judges' self-reported confidence scores.

Consensus Strategies

StrategyAlgorithmBest For
weighted_averageWeighted mean of scores; confidence penalised by inter-judge variance.General-purpose gradient validation.
majorityBinary vote (score ≥ threshold = pass). Simple majority wins, confidence = vote margin.Approve/reject decisions.
unanimousAll judges must score ≥ threshold. Confidence = minimum confidence across all judges.Critical gates (security audits, production deploys).
best_of_nRank by score × confidence; take top N; compute weighted average of those N.Reduce impact of outlier judges.

State output structure:

{
  "consensus": {
    "score": 0.92,
    "confidence": 0.85,
    "strategy": "weighted_average",
    "metadata": {}
  },
  "individual_results": [
    { "agent_id": "reviewer-v1", "score": 0.9, "confidence": 0.88, "reasoning": "..." }
  ],
  "agents": [
    { "agent_id": "reviewer-v1", "output": "{\"score\": 0.9, ...}", "weight": 1.0 }
  ]
}

Use {{STATE.consensus.score}}, {{STATE.consensus.confidence}}, and {{STATE.agents.N.output}} in downstream transitions and templates.

Without judges. Without judges_for_parallel (the state's own judge agents, distinct from its agents), the state's consensus combines its agents' own verdicts by consensus.strategy, as judges' verdicts are combined. Each agent's output is read as a verdict: the first fenced block of the output, or else the whole output, as a JSON object with a score from 0.0 to 1.0 and an optional confidence (0.8 when absent). Agents that return no verdict are listed in consensus.metadata.agents_without_verdict and not counted. If none returns a verdict, the consensus has no score, and its metadata.reasoning says there is no score to combine.

kind: ContainerRun

Executes a single command in an isolated container without an LLM or iteration loop. Use ContainerRun for deterministic CI/CD steps: compiling, running tests, building images, and deploying artifacts.

FieldTypeRequiredDefaultDescription
namestringHuman-readable label displayed in the Synapse UI and event log.
imagestring✓Container image reference. Accepts any Docker image (e.g. "rust:1.75-alpine", "docker:24-cli") or a private registry image (e.g. "ghcr.io/myorg/builder:v2"), or model:<class>/<name>, a model image of the runtime registry (see A model step below).
image_pull_policystringIfNotPresentAlways | IfNotPresent | Never.
commandstring[]✓Command and arguments to execute (entrypoint override). Handlebars templates supported in each element.
shellbooleanfalseIf true, join all command elements and pass them to sh -c. Use for multi-line scripts.
envmap[string]stringEnvironment variables. Values support Handlebars.
workdirstring/workspaceWorking directory inside the container.
volumesobject[]Volume mounts. Same volumes declared at workflow level or per-state.
volumes[].namestring✓Volume name that matches a workflow-level volume, or repository for the run's repository's working tree (repository:<label> for one of several), mounted read-write, or attachments for the files attached to the run, mounted read-only.
volumes[].mount_pathstring✓Absolute path inside the container.
volumes[].read_onlybooleanfalseMount as read-only.
network_modestringegress: run the step on the node's step network (spec.storage.git.step_network in the node configuration), so it reaches package registries. A node with none refuses the step with "this node has no egress network for steps". Absent: the default network, or none for a model step, which takes no other value.
resourcesobjectCPU, memory, and timeout limits.
resources.cpuintegerCPU millicores (e.g. 2000 = 2 vCPU).
resources.memorystringMemory limit (e.g. "2Gi", "512Mi").
resources.timeoutstring5mHard timeout for the container. Human-readable: "5m", "1h". Activity-level timeout in Temporal.
registry_credentialsstringSecrets vault path for private registry auth (e.g. "secret:cicd/docker-registry"). Resolved by the orchestrator; never exposed to the container.
retryobjectRetry configuration for transient failures.
retry.max_attemptsinteger1Total attempts including the first. 3 = one initial attempt plus two retries.
retry.backoffstring"0s"Initial delay between retries. Subsequent retries double the backoff (exponential).

After the container exits, the Blackboard is updated under the state name:

{
  "exit_code": 0,
  "stdout": "<captured stdout, up to 1 MB>",
  "stderr": "<captured stderr, up to 1 MB>",
  "duration_ms": 4321
}

Use {{STATE.output.exit_code}}, {{STATE.output.stdout}}, and {{STATE.output.stderr}} in downstream states.

Transitions on ContainerRun states use exit_code_zero, exit_code_non_zero, exit_code, on_success, on_failure, and custom. See Condition Types below.

A step on the run's repository. A volume named repository mounts the working tree of the run's first repository at its mount_path, the working tree at the mount's root, through the same storage gateway agent states use, for the step's length; repository:<label> names the one of that label. A step naming a repository its run does not hold is refused before any container: "this step names the run's repository and the run holds none", or "this step names the run's repository and the run holds no repository '<label>'". No credential reaches the step's container. The Forge's test step:

EXECUTE_TESTS:
  kind: ContainerRun
  name: "the-forge-tests"
  image: "{{input.test_image}}"
  shell: true
  command:
    - "eval \"$FORGE_TEST_COMMAND\""
  env:
    FORGE_TEST_COMMAND: "{{{input.test_command}}}"
  workdir: "/workspace"
  volumes:
    - name: repository
      mount_path: "/workspace"
  network_mode: egress
  resources:
    cpu: 2000
    memory: "4Gi"
    timeout: 1800s
  transitions:
    - condition: exit_code_zero
      target: DIFF
    - condition: exit_code_non_zero
      target: CODE

A model step

A ContainerRun state whose image is model:<class>/<name> runs a model of the node's runtime registry: no language model chooses what it does, and its weights are in its image. When the workflow is registered, the reference is resolved to the registry's image, pinned by its digest, before anything is stored or sent to the worker, so the step's container and its ContainerRunStarted event name the digest that runs. The step takes the registry entry's command and resources where the state sets none, and runs with no network.

A model step is refused when the workflow is registered:

RefusalWhen
"unknown model '<class>/<name>'; the models are <list>"The registry has no such model; the list is every model it has, or none.
"a model step runs with no network; remove network_mode or set it to none"network_mode is set to anything but none.
"a model image is named model:<class>/<name>, not '<image>'"The model: image is not of that form.
"model '<class>/<name>' names no command; set command on the step"Neither the state nor the registry entry gives a command.

Each is answered inside "Invalid container state configuration in state '<state>': <refusal>".

The built-in workflow transcribe-audio (labels builtin: "true", type: builtin-model) is a model step, deployed when spec.deploy_builtins is on. Its input audio_path is the name of a file attached to the run: letters, digits and - . _, never .., in any container ffmpeg decodes (wav, mp3, m4a, ogg, flac, webm). It may be left out when one file is attached: the run then reads that file. The step mounts the run's attachments read-only at /input, transcribes /input/{{input.audio_path}} with speech-to-text/whisper-base on the CPU, with no network and no language model, and prints the transcript: the step's stdout is the run's transcript.

Its optional boolean input speakers (default false) is for a recording with more than one voice: "Set it to true when the recording has more than one voice: the transcript then starts a new paragraph at each change of speaker, labelled Speaker 1 and Speaker 2 in turn. English recordings only. The labels mark turns, not who is speaking." With speakers true, the run takes the step TRANSCRIBE_TURNS in place of TRANSCRIBE: the same command on speech-to-text/whisper-small-en-tdrz, an English-only model that marks speaker turns. Its transcript is paragraphs separated by one blank line, the first starting "Speaker 1:", the next "Speaker 2:", and so on in turn; a recording in which no turn is found is one paragraph, "Speaker 1: " and its text. Start it with aegis.workflow.run, name transcribe-audio, the file in attachments and, when several files are attached, input.audio_path the file's name; a person's chat in Zaru Web carries the files attached to the turn into the run. A run with several files attached and no audio_path, or whose audio_path names no attached file, is refused at its start, before any execution exists, with one sentence naming the attached files, for example "This run reads one recording and several files are attached (DIALOGUE.ogg, notes.wav); name the one to transcribe in audio_path." or "No attached file is named 'recording.ogg'; the attached files are: DIALOGUE.ogg."; a run with no attachment keeps the step's own refusal below.

The check holds for any workflow: an input_schema property that carries x-aegis-attachment-name: true names one of the run's attached files, is filled with the name of the run's only attachment when left out, and is checked against the attached names before the run starts. transcribe-audio's audio_path carries it. Its states:

ROUTE:
  kind: System
  command: "echo routed"
  transitions:
    - condition: custom
      expression: "(default input.speakers false)"
      target: TRANSCRIBE_TURNS
    - condition: on_success
      target: TRANSCRIBE
TRANSCRIBE:
  kind: ContainerRun
  name: "Transcribe"
  image: "model:speech-to-text/whisper-base"
  command: ["transcribe", "/input/{{input.audio_path}}", "--out", "/tmp/transcript.txt"]
  volumes:
    - name: attachments
      mount_path: /input
      read_only: true
  shell: false
  transitions:
    - condition: exit_code_zero
      target: DONE
    - condition: exit_code_non_zero
      target: FAILED
      feedback: "The recording could not be transcribed: {{{TRANSCRIBE.stderr}}}"
TRANSCRIBE_TURNS:
  kind: ContainerRun
  name: "Transcribe with speaker turns"
  image: "model:speech-to-text/whisper-small-en-tdrz"
  command: ["transcribe", "/input/{{input.audio_path}}", "--out", "/tmp/transcript.txt"]
  volumes:
    - name: attachments
      mount_path: /input
      read_only: true
  shell: false
  transitions:
    - condition: exit_code_zero
      target: DONE
    - condition: exit_code_non_zero
      target: FAILED
      feedback: "The recording could not be transcribed: {{{TRANSCRIBE_TURNS.stderr}}}"

The run's transcript is {{TRANSCRIBE.stdout}}{{TRANSCRIBE_TURNS.stdout}}: the output of whichever step ran.

A step on the run's attachments

A run started by aegis.workflow.run with attachments carries them in its input as input.attachments. A volume named attachments mounts a copy of those files, each at its name, at the volume's mount_path, read-only whatever read_only says: only read-only is allowed. The copy is made for the step in a volume the workflow run owns, and is removed after the step. A step is refused before any container:

RefusalWhen
"this attachment is not yours"An attachment's volume is not the run's person's, or the run has no person.
"this step reads the run's attachments and the run has none"The run carries no attachments.
"this node does not give steps their run's attachments"The node is not set up to give steps their run's attachments.

kind: ParallelContainerRun

Runs multiple container commands concurrently within a single workflow state. All steps start simultaneously; the state waits until they all finish before evaluating transitions. Use it for parallel test suites, multi-language builds, or concurrent quality gates.

FieldTypeRequiredDefaultDescription
stepsobject[]✓List of container steps to run in parallel. Each step has the same fields as kind: ContainerRun (except retry), plus a required name.
steps[].namestring✓Unique label for this step. Used as the Blackboard output key.
completionstringall_succeedall_succeed | any_succeed | best_effort. See below.

completion Strategies

StrategyBehaviourBest For
all_succeedState succeeds only if every step exits with code 0.CI gates where all checks must pass.
any_succeedState succeeds if at least one step exits with code 0.Multi-platform builds where one target is sufficient.
best_effortState always transitions with on_success; per-step results are available for inspection.Information-gathering steps where failure is non-blocking.

After all steps complete, the Blackboard is updated under the state name with per-step keys:

{
  "unit-tests": { "exit_code": 0, "stdout": "...", "stderr": "", "duration_ms": 12300 },
  "lint":       { "exit_code": 1, "stdout": "", "stderr": "error[E0...]", "duration_ms": 870 },
  "format-check": { "exit_code": 0, "stdout": "", "stderr": "", "duration_ms": 410 }
}

Access per-step output as {{STATE.output.STEPNAME.stdout}}, {{STATE.output.STEPNAME.stderr}}, and {{STATE.output.STEPNAME.exit_code}}.

kind: Subworkflow

Invokes another deployed workflow as a child execution. Use Subworkflow to compose workflows — extract reusable pipelines into standalone workflows and call them from a parent.

FieldTypeRequiredDefaultDescription
workflow_idstring✓Deployed workflow name or UUID of the child workflow to invoke.
modestringblockingblocking | fire_and_forget. Determines whether the parent waits for the child to complete.
result_keystringBlackboard key where the child's final Blackboard is stored (blocking mode only). If omitted in blocking mode, the child result is still available as {{STATE.result}}.
inputstringHandlebars template rendered and passed as the child workflow's start input (--input).

Execution Modes

ModeParent BehaviourBlackboard Output
blockingWaits for the child workflow to reach a terminal state.STATE.status, STATE.result (child's final output), STATE.child_execution_id. If result_key is set, the child's full final_blackboard is also written to blackboard.{result_key}.
fire_and_forgetStarts the child and immediately evaluates transitions.STATE.status ("success" if child was started), STATE.child_execution_id.

Blocking mode example:

RUN_PIPELINE:
  kind: Subworkflow
  workflow_id: data-pipeline-v2
  mode: blocking
  result_key: pipeline_output
  input: "{{workflow.context.task}}"
  timeout: 1800s
  transitions:
    - condition: on_success
      target: PROCESS_RESULT
    - condition: on_failure
      target: HANDLE_ERROR
      feedback: "Child workflow failed: {{RUN_PIPELINE.result}}"

Fire-and-forget example:

START_BACKGROUND_JOB:
  kind: Subworkflow
  workflow_id: nightly-cleanup
  mode: fire_and_forget
  input: |
    {"environment": "{{blackboard.deploy_env}}"}
  transitions:
    - condition: on_success
      target: CONTINUE_MAIN_FLOW

After the state completes, the Blackboard is updated under the state name:

Blocking mode:

{
  "status": "success",
  "result": "<child workflow's final output>",
  "child_execution_id": "wfx-child-a1b2c3d4-..."
}

Fire-and-forget mode:

{
  "status": "success",
  "child_execution_id": "wfx-child-a1b2c3d4-..."
}

Use {{STATE.result}} in downstream states to reference the child's output (blocking mode) and {{STATE.child_execution_id}} to reference the child execution.

Validation Rules

  • workflow_id must reference a deployed workflow. The engine validates this at state entry and fails with a descriptive error if the workflow is not found.
  • result_key is only meaningful in blocking mode; it is ignored in fire_and_forget mode.
  • Circular composition (workflow A calls B which calls A) is detected at runtime. The engine enforces a maximum child depth of 10 and fails with SubworkflowDepthExceeded if exceeded.
  • The child workflow's timeout is independent of the parent state's timeout. If the parent state times out before the child completes, the child is cancelled.

spec.states[*].transitions[]

FieldTypeRequiredDescription
conditionstringNamed condition type (see below). If absent, transition is unconditional.
targetstring✓State to transition to. Must exist in spec.states.
feedbackstringHandlebars string written to {{state.feedback}} for the next state.
thresholdnumberFor score/consensus conditionsScore or consensus threshold (0.0–1.0).
agreementnumberFor consensusMinimum consensus.confidence required.
valuestringFor exit_code, input_equalsExact value to match.
expressionstringFor customHandlebars boolean expression.
min / maxnumberFor score_betweenScore range bounds (inclusive).

Condition Types

ConditionApplicable KindsDescription
(absent)AllUnconditional fallback. Always matches. Place last.
alwaysAllExplicit unconditional. Equivalent to absent condition.
on_successAgent, System, Action, ContainerRun, ParallelContainerRun, SubworkflowState succeeded (exit code 0, agent returned success, or child workflow completed).
on_failureAgent, System, Action, ContainerRun, ParallelContainerRun, SubworkflowState failed.
exit_code_zeroSystem, ContainerRunExit code was 0.
exit_code_non_zeroSystem, ContainerRunExit code was non-zero.
exit_codeSystem, ContainerRunExit code equals value.
score_aboveAgent, ParallelAgentsThe state's score is strictly greater than threshold.
score_belowAgent, ParallelAgentsThe state's score is strictly less than threshold.
score_betweenAgentScore between min and max (inclusive).
confidence_aboveAgentValidation confidence > threshold.
consensusParallelAgentsConsensus score ≥ threshold AND confidence ≥ agreement.
all_approvedParallelAgentsAll agents scored ≥ consensus threshold.
any_rejectedParallelAgentsAt least one agent scored < consensus threshold.
input_equalsHumanSignal payload matches value.
input_equals_yesHumanAnswer is yes, y or 1, in any case.
input_equals_noHumanAnswer is no, n or 0, in any case.
customAllHandlebars expression evaluates to a truthy result.

Scores: score_above and score_below compare the state's score with threshold. The score is the state output's score, else final_score, else consensus.score (a ParallelAgents state). A state that carries no score takes neither; if no other transition then matches, the run fails with State "<name>" carries no score for its score transitions.

Evaluation order: transitions are evaluated top-to-bottom. The first matching transition is taken. Always include an unconditional fallback as the last transition.

Terminal states: a state with transitions: [] is terminal. When reached, the workflow execution completes with status completed.


Field Definitions

spec.context

Global constants accessible in any state's input, command, env, prompt, expression, and feedback fields via {{workflow.context.KEY}}. Use this for values shared across states (iteration limits, thresholds, URLs). Prefer context for scalars and storage for shared file systems.

spec.storage

Volumes are created by the orchestrator at workflow start, before any state executes. States reference them by Handlebars template variable — no UUID threading between states is needed.

ClassLifecycleUse Case
ephemeralAuto-deleted after ttl_hoursBuild artifacts, scratch code, intermediate files
persistentKept until explicitly deleted via APIShared datasets, long-lived outputs, auditable artifacts

All file operations on workflow volumes are intercepted by AegisFSAL — every read and write is authorized against the agent's spec.security.filesystem policy and published as a StorageEvent domain event for the full audit trail.

Handlebars Template Variables

All input, command, env, prompt, expression, and feedback fields support Handlebars templates.

VariableAvailable InDescription
{{intent}}All statesThe caller's natural-language intent string passed at workflow start.
{{input.KEY}}All statesKey from the workflow start --input payload (validated against metadata.input_schema).
{{workflow.context.KEY}}All statesValue from spec.context.
{{workflow.storage.workspace}}volumes[].volumeReference to the shared workspace volume.
{{workflow.storage.shared_volumes.NAME}}volumes[].volumeReference to a named shared volume.
{{STATE.output}}States after STATEFinal output text of an Agent state.
{{STATE.output.stdout}}States after STATEstdout of a System or ContainerRun state.
{{STATE.output.stderr}}States after STATEstderr of a System or ContainerRun state.
{{STATE.output.exit_code}}States after STATEExit code of a System or ContainerRun state.
{{STATE.output.duration_ms}}States after STATEWall-clock duration in milliseconds (ContainerRun states).
{{STATE.output.STEPNAME.stdout}}States after STATEPer-step stdout (ParallelContainerRun states).
{{STATE.output.STEPNAME.stderr}}States after STATEPer-step stderr (ParallelContainerRun states).
{{STATE.output.STEPNAME.exit_code}}States after STATEPer-step exit code (ParallelContainerRun states).
{{STATE.status}}States after STATE"success" or "failed".
{{STATE.score}}States after STATEValidation score (Agent states, 0.0–1.0).
{{STATE.consensus.score}}States after STATEConsensus score (ParallelAgents states).
{{STATE.consensus.confidence}}States after STATEConsensus confidence (ParallelAgents states).
{{STATE.agents.N.output}}States after STATEIndividual judge full output (ParallelAgents, 0-indexed).
{{STATE.agents.N.output.FIELD}}States after STATEField from a judge's JSON output (e.g. {{AUDIT.agents.0.output.score}}, {{AUDIT.agents.1.output.reasoning}}).
{{STATE.result}}States after STATEFinal output of a Subworkflow state (blocking mode).
{{STATE.child_execution_id}}States after STATEChild workflow execution ID (Subworkflow states).
{{blackboard.KEY}}All statesAny key set in spec.context or by a prior update_blackboard action.
{{state.feedback}}All statesfeedback string from the incoming transition.
{{human.feedback}}After Human statesAdditional feedback text from the signal --feedback argument.
{{execution.id}}All statesWorkflow execution UUID.

Blackboard

The Blackboard is a live string → JSON value map shared across all states in a workflow execution. It is owned and managed by the Temporal worker for the duration of the execution.

Lifecycle:

  1. Seed: Before the first state runs, the Blackboard is seeded with all spec.context constants. Callers may additionally supply --blackboard key-value pairs at invocation time; these merge in at the same moment.
  2. Mutation: As each state completes, its output is written to the Blackboard under the state name key. System states, Action states, ContainerRun states, and the update_context built-in all write structured JSON into the Blackboard.
  3. Snapshot: When the workflow completes, the final Blackboard state is captured and stored in PostgreSQL for audit and debugging.

Template access:

  • {{blackboard.KEY}} — resolves from the live Blackboard, updated after each state transition.
  • {{input.KEY}} — resolves from WorkflowExecution.input, which is immutable and not part of the Blackboard.

These two namespaces are distinct: input is what the caller provided at invocation; blackboard is the accumulated state built up during execution.

Example: A three-state workflow where each state reads from the previous:

spec:
  context:
    base_currency: "USD"
  states:
    extract:
      kind: agent
      agent: invoice-extractor
      input_template: '{"text": "{{input.document_text}}", "currency": "{{workflow.context.base_currency}}"}'
      transitions:
        - on: success
          next: validate
    validate:
      kind: agent
      agent: quality-gate
      input_template: '{"artifact": "{{blackboard.extract}}", "criteria": ["amounts-balance", "vendor-exists"]}'
      transitions:
        - on: success
          next: complete
    complete:
      kind: system
      command: "echo done"

In this example, {{input.document_text}} is the caller-supplied input (immutable); {{blackboard.extract}} is the output written by the extract state (mutable, grows with each state).

Handlebars conditionals, loops, and built-in helpers are fully supported:

input: |
  {{#if blackboard.iteration_number}}
  Attempt {{blackboard.iteration_number}} failed: {{state.feedback}}
  {{else}}
  {{intent}}
  {{/if}}

Comparison operators in custom expressions: <, >, <=, >=, ==, !=, &&, ||, !

Built-in helpers:

HelperExampleDescription
{{length array}}{{length AUDIT.agents}}Number of elements in an array.
{{upper string}}{{upper input.task}}Convert to upper case.
{{lower string}}{{lower STATE.status}}Convert to lower case.
{{trim string}}{{trim STATE.output}}Strip leading/trailing whitespace.
{{json object}}{{json AUDIT.agents.0.output}}Pretty-print an object as a JSON string.
{{first_line string}}{{first_line GENERATE.output}}Return only the first line of a multi-line string.
{{default value fallback}}{{default blackboard.lang "python"}}Return value if present and non-empty, otherwise fallback.

Missing key behavior: if a template references a key that doesn't exist in the Blackboard at render time, the engine renders a descriptive placeholder rather than crashing the workflow:

{{{{ ERROR: missing key 'GENERATE.output' — state GENERATE has not yet completed }}}}

This ensures a workflow state receives a clear signal about a misconfigured template rather than silently receiving an empty string or aborting execution.


Judge Agent Output Format

Agents used as judges in ParallelAgents states must output JSON:

{
  "score": 0.85,
  "confidence": 0.92,
  "reasoning": "The code meets requirements with minor style issues.",
  "suggestions": ["Add type hints", "Improve error handling"],
  "verdict": "pass"
}
FieldTypeRequiredDescription
scorefloat (0.0–1.0)✓Quality/correctness score on a continuous gradient.
confidencefloat (0.0–1.0)✓Judge's certainty in its assessment.
reasoningstring✓Explanation for the score (minimum 10 characters).
suggestionsstring[]Improvement recommendations.
verdictstringHuman-readable decision: "pass", "fail", or "warning".

For a complete judge agent manifest, see Agent Manifest Reference — Code Reviewer (Judge Agent).


Examples

100monkeys Classic

The classic iterative refinement loop: generate code, execute it, validate output with a judge agent, refine on failure.

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: 100monkeys-classic
  version: "1.0.0"
  description: "Classic iterative refinement loop"
  labels:
    category: iterative
    pattern: generate-execute-validate-refine

spec:
  context:
    max_iterations: 10
    validation_threshold: 0.95

  initial_state: GENERATE

  states:
    GENERATE:
      kind: Agent
      agent: "{{input.agent_id}}"
      input: |
        {{#if blackboard.iteration_number}}
        Iteration {{blackboard.iteration_number}} — previous attempt failed.

        --- PREVIOUS CODE ---
        {{blackboard.previous_code}}

        --- ERRORS ---
        {{blackboard.validation_errors}}

        Fix the code.
        {{else}}
        {{intent}}
        {{/if}}
      transitions:
        - condition: always
          target: EXECUTE

    EXECUTE:
      kind: System
      command: "{{input.command}}"
      env:
        CODE: "{{GENERATE.output}}"
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

    VALIDATE:
      kind: Agent
      agent: "{{input.judge_id}}"
      input: |
        Task: {{intent}}
        Output: {{EXECUTE.output.stdout}}

        Validate and respond with JSON:
        {"valid": bool, "score": 0.0-1.0, "reasoning": "..."}
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

    REFINE:
      kind: Action
      action: update_blackboard
      args:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        CODE: "{{GENERATE.output}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: echo
      env:
        RESULT: "{{EXECUTE.output.stdout}}"
      transitions: []

    FAILED:
      kind: System
      command: echo
      env:
        REASON: "Max iterations ({{workflow.context.max_iterations}}) reached"
      transitions: []

The Forge

The Forge is a built-in workflow, the-forge 2.0.2 (labels builtin: "true", category: development): it develops one change in one repository of its person's, with requirements and a design each approved by the person, tests written first, the person's test suite run in a container on the clone, a review by three judges, and a commit on the run's work branch. Its manifest uses the repository features above; the states, the agents and how to start it are on The Forge. The parts that carry the shape:

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: "the-forge"
  version: "2.0.2"
  labels:
    builtin: "true"
    category: "development"
  input_schema:
    type: object
    properties:
      task:
        type: string
        description: "What to change. Its first line names the commit."
      test_command:
        type: string
        description: "The test suite, run by /bin/sh -c in the repository's root."
      test_image:
        type: string
        description: "The image the test suite runs in, a reference with a tag."
      context:
        type: string
        description: "Anything else the analyst should know."
      draft_only:
        type: boolean
        default: true
    required:
      - task
      - test_command
      - test_image

spec:
  # The run names exactly one repository by the dispatch key `repositories`.
  repositories: 1

  context:
    max_code_iterations: 5

  initial_state: ANALYZE

  states:
    # ANALYZE, AWAIT_REQUIREMENTS_APPROVAL, ARCHITECT, AWAIT_ARCH_APPROVAL,
    # TEST, CODE (max_state_visits: 5) and EXECUTE_TESTS (above) come first.

    DIFF:
      kind: Action
      action: repository_diff
      transitions:
        - condition: on_success
          target: AUDIT
        - condition: on_failure
          target: FAILED

    AUDIT:
      kind: ParallelAgents
      agents:
        - agent: "code-reviewer-agent"
          weight: 1.0
        - agent: "critic-agent"
          weight: 1.5
        - agent: "security-auditor-agent"
          weight: 2.0
      consensus:
        strategy: weighted_average
        threshold: 0.95
        agreement: 0.8
      transitions:
        - condition: consensus
          threshold: 0.95
          agreement: 0.8
          target: COMMIT
        - condition: score_below
          threshold: 0.95
          target: CODE
        - condition: always
          target: CODE

    COMMIT:
      kind: Action
      action: repository_commit
      args:
        message: "the-forge: {{{first_line input.task}}}"
      transitions:
        - condition: on_failure
          target: FAILED
        - condition: custom
          expression: "(default input.draft_only true)"
          target: COMPLETE
        - condition: on_success
          target: LAND

    LAND:
      kind: Action
      action: repository_land
      transitions:
        - condition: on_success
          target: COMPLETE
        - condition: on_failure
          target: LAND_REFUSED

    # COMPLETE, FAILED and LAND_REFUSED are update_blackboard actions that write
    # outcome, commit_sha, branch and the refusal's sentence.

Each judge of AUDIT is also given the requirements, the design, {{{DIFF.output.diff}}} and the passing suite's output, and answers {score, confidence, reasoning, suggestions}. No state of the Forge runs a shell command in the core process.

Carbon Forge

Carbon Forge is a built-in workflow, carbon-forge 1.2.0 (labels builtin: "true", category: development): the Forge's states on one of its person's Carbon Forge trees, named by the dispatch key trees, with the tree actions in place of the repository actions and one more state, DRIFT. DIFF is tree_diff, COMMIT is tree_write onto the run's own lane, DRIFT is drift_report (the lane's drift report, read with the Carbon Forge tool symbols.drift on the run's lane and tree), LAND is tree_land after the person's approval, and CUT is tree_cut; COMPLETE, FAILED, LAND_REFUSED and CUT_REFUSED are update_blackboard actions. The states and the drift report's place at the gate are on Carbon Forge. The parts that differ from the Forge's:

metadata:
  name: "carbon-forge"
  version: "1.2.0"

spec:
  states:
    DIFF:
      kind: Action
      action: tree_diff
      transitions:
        - condition: on_success
          target: AUDIT
        - condition: on_failure
          target: FAILED

    COMMIT:
      kind: Action
      action: tree_write
      args:
        message: "carbon-forge: {{{first_line input.task}}}"
      transitions:
        - condition: on_failure
          target: FAILED
        - condition: on_success
          target: DRIFT

    # The lane's drift report, advice for the gate: every outcome goes on.
    DRIFT:
      kind: Action
      action: drift_report
      transitions:
        - condition: custom
          expression: "(default input.draft_only true)"
          target: COMPLETE
        - condition: always
          target: LAND

    LAND:
      kind: Action
      action: tree_land
      args:
        message: "carbon-forge: {{{first_line input.task}}}"
      transitions:
        - condition: on_success
          target: CUT
        - condition: on_failure
          target: LAND_REFUSED

    CUT:
      kind: Action
      action: tree_cut
      args:
        cut: "{{input.cut}}"
      transitions:
        - condition: on_success
          target: COMPLETE
        - condition: on_failure
          target: CUT_REFUSED

    # COMPLETE, FAILED, LAND_REFUSED and CUT_REFUSED are update_blackboard
    # actions that write outcome, commit_sha, branch and the refusal's
    # sentence; COMPLETE, LAND_REFUSED and CUT_REFUSED also write drift.

The DRIFT step answers the report's hash in commit_sha, its counts by class in branch, the whole report in diff and a refusal in sentence; the blackboard's drift is "{{{DRIFT.output.diff}}}{{{DRIFT.output.sentence}}}".

Agent-Augmented CI/CD Pipeline

An agent generates code, a ContainerRun compiles it, a ParallelContainerRun runs quality checks concurrently, multi-agent review validates the result, and a final ContainerRun deploys the artifact.

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: agent-cicd-pipeline
  version: "1.0.0"
  description: "AI-augmented delivery pipeline"
  labels:
    pattern: cicd

spec:
  initial_state: GENERATE

  storage:
    shared_volumes:
      - name: workspace
        persistent: true

  states:
    GENERATE:
      kind: Agent
      agent: coder-v2
      input: |
        {{intent}}
      volumes:
        - name: workspace
          mount_path: /workspace
      transitions:
        - condition: on_success
          target: BUILD
        - condition: on_failure
          target: FAILED

    BUILD:
      kind: ContainerRun
      name: "Compile"
      image: "rust:1.75-alpine"
      command: ["cargo", "build", "--release"]
      workdir: "/workspace"
      volumes:
        - name: workspace
          mount_path: /workspace
      resources:
        cpu: 2000
        memory: "4Gi"
        timeout: "10m"
      transitions:
        - condition: exit_code_zero
          target: TEST
        - condition: exit_code_non_zero
          target: FIX_BUILD
          feedback: "{{BUILD.output.stderr}}"

    FIX_BUILD:
      kind: Agent
      agent: coder-v2
      input: |
        Build failed — fix the errors:
        {{state.feedback}}
      volumes:
        - name: workspace
          mount_path: /workspace
      transitions:
        - condition: on_success
          target: BUILD
        - condition: on_failure
          target: FAILED

    TEST:
      kind: ParallelContainerRun
      steps:
        - name: unit-tests
          image: "rust:1.75-alpine"
          command: ["cargo", "test", "--workspace"]
          workdir: "/workspace"
          volumes:
            - name: workspace
              mount_path: /workspace
          resources:
            timeout: "5m"
        - name: lint
          image: "rust:1.75-alpine"
          command: ["cargo", "clippy", "--all-targets", "--", "-D", "warnings"]
          workdir: "/workspace"
          volumes:
            - name: workspace
              mount_path: /workspace
        - name: format-check
          image: "rust:1.75-alpine"
          command: ["cargo", "fmt", "--check"]
          workdir: "/workspace"
          volumes:
            - name: workspace
              mount_path: /workspace
      completion: all_succeed
      transitions:
        - condition: on_success
          target: REVIEW
        - condition: on_failure
          target: FIX_TESTS

    FIX_TESTS:
      kind: Agent
      agent: coder-v2
      input: |
        Tests/lint failed:
        Unit: {{TEST.output.unit-tests.stderr}}
        Lint: {{TEST.output.lint.stderr}}
        Format: {{TEST.output.format-check.stderr}}
      volumes:
        - name: workspace
          mount_path: /workspace
      transitions:
        - condition: on_success
          target: BUILD
        - condition: on_failure
          target: FAILED

    REVIEW:
      kind: ParallelAgents
      agents:
        - agent: security-auditor
          input: "Security audit: /workspace"
          weight: 1.5
          timeout_seconds: 300
        - agent: architecture-reviewer
          input: "Architecture review: /workspace"
          weight: 1.0
          timeout_seconds: 180
      consensus:
        strategy: weighted_average
        threshold: 0.8
        min_judges_required: 2
      transitions:
        - condition: consensus
          threshold: 0.8
          agreement: 0.75
          target: DEPLOY
        - condition: score_below
          threshold: 0.8
          target: FIX_REVIEW
          feedback: "{{REVIEW.consensus.score}} — {{REVIEW.agents.0.output}}"

    FIX_REVIEW:
      kind: Agent
      agent: coder-v2
      input: |
        Review feedback:
        {{state.feedback}}
      volumes:
        - name: workspace
          mount_path: /workspace
      transitions:
        - condition: on_success
          target: BUILD
        - condition: on_failure
          target: FAILED

    DEPLOY:
      kind: ContainerRun
      name: "Push to Registry"
      image: "docker:24-cli"
      command:
        - sh
        - -c
        - |
          docker build -t {{blackboard.registry}}/{{blackboard.app}}:{{blackboard.version}} /workspace
          docker push {{blackboard.registry}}/{{blackboard.app}}:{{blackboard.version}}
      shell: true
      registry_credentials: "secret:cicd/docker-registry"
      volumes:
        - name: workspace
          mount_path: /workspace
      resources:
        timeout: "15m"
      transitions:
        - condition: exit_code_zero
          target: DONE
        - condition: exit_code_non_zero
          target: FAILED

    DONE:
      kind: System
      command: "echo done"
      transitions: []

    FAILED:
      kind: System
      command: "echo failed"
      transitions: []

Security Gate (Unanimous)

All judges must independently approve before promotion to production. A single dissenter blocks the gate.

SECURITY_GATE:
  kind: ParallelAgents
  agents:
    - agent: static-analyzer
      input: "{{CODE.output}}"
      timeout_seconds: 300
    - agent: penetration-tester
      input: "{{CODE.output}}"
      timeout_seconds: 600
    - agent: security-expert
      input: "{{CODE.output}}"
      timeout_seconds: 180
  consensus:
    strategy: unanimous
    threshold: 0.95
    min_judges_required: 3
  transitions:
    - condition: score_above
      threshold: 0.94
      target: PRODUCTION
    - condition: always
      target: SECURITY_FAILED
      feedback: "Security gate failed — not all judges approved at 95%"

Cross-References

TopicSee
Writing judge agents for ParallelAgents statesAgent Manifest Reference
Step-by-step workflow construction guideBuilding Workflows
Building CI/CD pipelines with ContainerRunBuilding CI/CD Pipelines
Conceptual FSM overview and state kindsWorkflows
Gradient scoring and validation confidenceValidation Guide
Storage volumes and AegisFSALStorage Gateway

Version History

VersionDateNotes
v1.02026-02-16Initial canonical format. All four state kinds (Agent, System, Human, ParallelAgents). Named-condition transitions. Handlebars templates. Four consensus strategies.
v1.12026-03-05Added ContainerRun and ParallelContainerRun state kinds for CI/CD pipeline steps. Added completion strategies (all_succeed, any_succeed, best_effort). Extended condition types and Handlebars variables for exit-code-based routing.
v1.22026-03-25Added Subworkflow state kind for workflow-to-workflow composition. Two execution modes: blocking and fire_and_forget. Child workflows use Temporal's native child workflow support.

On this page