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 stateField Reference
Top-Level Fields
| Field | Type | Required | Description |
|---|---|---|---|
apiVersion | string | ✓ | Must be 100monkeys.ai/v1. |
kind | string | ✓ | Must be Workflow. |
metadata | object | ✓ | Manifest metadata. |
spec | object | ✓ | Workflow specification. |
metadata
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✓ | Unique workflow name. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$. |
version | string | Manifest semantic version (e.g., "1.0.0"). | |
description | string | Human-readable purpose description. | |
labels | map[string]string | Key-value labels for categorization and discovery. | |
annotations | map[string]string | Arbitrary non-identifying metadata (URLs, changelogs, JSON blobs). | |
input_schema | JSON Schema object | Declares named inputs accepted at execution time. See metadata.input_schema. | |
output_schema | JSON Schema object | Declares the shape of the workflow's structured output. See metadata.output_schema. | |
output_template | map[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.
| Field | Type | Required | Description |
|---|---|---|---|
input_schema | JSON Schema object | Must 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
- environmentThe following JSON Schema property types are supported. The Zaru client context panel renders each type as a specific UI element:
| JSON Schema type | Zaru UI control |
|---|---|
string | Text input |
number / integer | Number spinner |
boolean | Checkbox |
enum | Dropdown select |
object | Nested form group |
array | Repeatable 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_schemavsspec.context:spec.contextholds author-time constants declared in the manifest, accessible via{{workflow.context.KEY}}.metadata.input_schemadeclares 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 userfor personal workflows or--scope globalfor platform-wide workflows (requires operator role). After deployment, useaegis workflow promoteandaegis workflow demoteto change scope. Scope is not a manifest field — it is controlled via the CLI--scopeflag 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.
| Field | Type | Required | Description |
|---|---|---|---|
output_schema | JSON Schema object | Must 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_countmetadata.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.
| Field | Type | Required | Description |
|---|---|---|---|
output_template | map[string, string] | Each key matches a property in output_schema; each value is a Handlebars expression. |
Type coercion rules:
| Schema type | Coercion |
|---|---|
string | Used as-is (no conversion). |
integer | Parsed with parseInt. |
number | Parsed with parseFloat. |
boolean | Compared to "true" (case-sensitive). |
object | Parsed with JSON.parse. |
array | Parsed 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_templateandoutput_schemaare independently optional.output_templatecan be used withoutoutput_schema(no type coercion or validation -- all values remain strings).output_schemacan be used withoutoutput_template. When both are present, the template is rendered first, then coerced and validated against the schema.
spec
| Field | Type | Required | Description |
|---|---|---|---|
initial_state | string | ✓ | Name of the first state to enter. Must exist in spec.states. |
max_total_transitions | integer | Maximum total state transitions before the workflow terminates. Default: 50. Ceiling: 100. | |
context | map[string, any] | Global constants accessible via {{workflow.context.KEY}}. | |
storage | object | Workflow-level shared volume configuration. | |
default_schedule | object | A 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. | |
repositories | integer | The 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. | |
states | map[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:
| Form | Entry |
|---|---|
| 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:
| Refusal | When |
|---|---|
| "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 sentence | The 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:
| Variable | Description |
|---|---|
{{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:
| Refusal | When |
|---|---|
| "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
| Field | Type | Description |
|---|---|---|
workspace | object | Default shared workspace. Auto-created at workflow start. Reference as {{workflow.storage.workspace}}. |
workspace.storage_class | ephemeral | persistent | Volume lifetime. |
workspace.ttl_hours | integer | Hours until auto-deletion (ephemeral only). Counted from workflow start. |
workspace.size_limit_mb | integer | Maximum volume size in MiB. Writes beyond this return ENOSPC. |
shared_volumes | object[] | Additional named shared volumes. |
shared_volumes[].name | string | Unique name. Reference as {{workflow.storage.shared_volumes.NAME}}. |
shared_volumes[].storage_class | ephemeral | persistent | Volume lifetime. |
shared_volumes[].ttl_hours | integer | Hours until auto-deletion (ephemeral only). |
shared_volumes[].size_limit_mb | integer | Maximum volume size in MiB (ephemeral only). |
shared_volumes[].volume_id | string | Pre-created volume UUID (persistent only). |
spec.states[*] — Common Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
kind | string | ✓ | Agent | System | Action | Human | ParallelAgents | ContainerRun | ParallelContainerRun | Subworkflow | |
max_state_visits | integer | 5 | Maximum times this state can be entered before the workflow terminates. Ceiling: 20. | |
timeout | string | 300s | Maximum time in this state. Human-readable: "300s", "5m", "1h". | |
volumes | object[] | Volume mounts for this state (Agent kind). | ||
volumes[].volume | string | ✓ | Volume reference. Supports Handlebars: {{workflow.storage.workspace}}. | |
volumes[].mount_path | string | ✓ | Absolute path inside the container. | |
volumes[].access_mode | read-write | read-only | ✓ | Access mode enforced by AegisFSAL. | |
transitions | object[] | ✓ | Ordered transition rules. Evaluated top-to-bottom; first match wins. |
kind: Agent
| Field | Type | Required | Description |
|---|---|---|---|
agent | string | ✓ | Deployed agent name or UUID. |
intent | string | Handlebars 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. | |
input | string | Handlebars template rendered as the agent's task input. Supports {{intent}}, {{input.KEY}}, {{STATE.output}}, {{blackboard.KEY}}, {{state.feedback}}. | |
isolation | inherit | firecracker | docker | process | Override 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
| Field | Type | Required | Description |
|---|---|---|---|
command | string | ✓ | Shell command to run. Handlebars templates supported. |
env | map[string]string | Environment variables. Values support Handlebars. | |
workdir | string | Working 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.
| Field | Type | Required | Description |
|---|---|---|---|
action | string | ✓ | 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. |
args | map[string]string | The 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: LANDaction | args | Needs | Touches the world | How it runs |
|---|---|---|---|---|
update_blackboard | Any keys: each rendered value is written to the Blackboard under its key. | Nothing | No | In the Temporal worker; no process runs. |
repository_diff | None | The run's repository | No | By the orchestrator, on the repository the run holds. |
repository_commit | message, required | The run's repository | No: the commit stays on the work branch in the person's volume. | By the orchestrator, on the repository the run holds. |
repository_land | None | The run's repository | Yes | By the orchestrator, as the call aegis.git.land, after the person's approval. |
image_generate | prompt, required; alias, size, count (1 to 4), path (default generated/) | An image generation model on the node | No | By 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: COLLECTRepository actions. repository_diff, repository_commit and repository_land are the workflow's own steps on the repository the run holds, run by the orchestrator.
| Action | What it does | Output |
|---|---|---|
repository_diff | The run's change against started_from, as a unified diff. A diff over 1 MiB is refused, never cut off. | diff, branch, ref |
repository_commit | Stages every change and commits it on the work branch, as the run's person, with the message args.message. | commit_sha, branch, ref |
repository_land | Lands 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: DONEkind: Human
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | ✓ | Message displayed to the operator. Handlebars templates supported. |
timeout | string | Duration to wait for an answer. Default: 3600s. Without default_response, the workflow fails when it elapses. | |
default_response | string | Signal 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
| Field | Type | Required | Description |
|---|---|---|---|
agents | object[] | ✓ | List of parallel agent configurations. |
consensus | object | ✓ | Consensus aggregation configuration. |
agents[]
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
agent | string | ✓ | Deployed agent name or UUID. | |
input | string | Handlebars template for this agent's task input. | ||
weight | number | 1.0 | Weight for consensus calculation. | |
timeout_seconds | integer | 60 | Per-agent execution timeout in seconds. | |
poll_interval_ms | integer | 500 | Polling 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
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
strategy | string | ✓ | weighted_average | majority | unanimous | best_of_n | |
threshold | number | 0.7 | Minimum score threshold (0.0–1.0). | |
min_agreement_confidence | number | Minimum consensus confidence required (0.0–1.0). Also accepted as agreement. | ||
n | integer | For best_of_n | Number of top judges to average. | |
min_judges_required | integer | 1 | Minimum judges that must succeed. State fails if fewer complete. | |
confidence_weighting.agreement_factor | number | 0.7 | Weight for inter-judge agreement. Must sum to 1.0 with self_confidence_factor. | |
confidence_weighting.self_confidence_factor | number | 0.3 | Weight for judges' self-reported confidence scores. |
Consensus Strategies
| Strategy | Algorithm | Best For |
|---|---|---|
weighted_average | Weighted mean of scores; confidence penalised by inter-judge variance. | General-purpose gradient validation. |
majority | Binary vote (score ≥ threshold = pass). Simple majority wins, confidence = vote margin. | Approve/reject decisions. |
unanimous | All judges must score ≥ threshold. Confidence = minimum confidence across all judges. | Critical gates (security audits, production deploys). |
best_of_n | Rank 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Human-readable label displayed in the Synapse UI and event log. | ||
image | string | ✓ | 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_policy | string | IfNotPresent | Always | IfNotPresent | Never. | |
command | string[] | ✓ | Command and arguments to execute (entrypoint override). Handlebars templates supported in each element. | |
shell | boolean | false | If true, join all command elements and pass them to sh -c. Use for multi-line scripts. | |
env | map[string]string | Environment variables. Values support Handlebars. | ||
workdir | string | /workspace | Working directory inside the container. | |
volumes | object[] | Volume mounts. Same volumes declared at workflow level or per-state. | ||
volumes[].name | string | ✓ | 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_path | string | ✓ | Absolute path inside the container. | |
volumes[].read_only | boolean | false | Mount as read-only. | |
network_mode | string | egress: 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. | ||
resources | object | CPU, memory, and timeout limits. | ||
resources.cpu | integer | CPU millicores (e.g. 2000 = 2 vCPU). | ||
resources.memory | string | Memory limit (e.g. "2Gi", "512Mi"). | ||
resources.timeout | string | 5m | Hard timeout for the container. Human-readable: "5m", "1h". Activity-level timeout in Temporal. | |
registry_credentials | string | Secrets vault path for private registry auth (e.g. "secret:cicd/docker-registry"). Resolved by the orchestrator; never exposed to the container. | ||
retry | object | Retry configuration for transient failures. | ||
retry.max_attempts | integer | 1 | Total attempts including the first. 3 = one initial attempt plus two retries. | |
retry.backoff | string | "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: CODEA 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:
| Refusal | When |
|---|---|
| "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:
| Refusal | When |
|---|---|
| "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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
steps | object[] | ✓ | List of container steps to run in parallel. Each step has the same fields as kind: ContainerRun (except retry), plus a required name. | |
steps[].name | string | ✓ | Unique label for this step. Used as the Blackboard output key. | |
completion | string | all_succeed | all_succeed | any_succeed | best_effort. See below. |
completion Strategies
| Strategy | Behaviour | Best For |
|---|---|---|
all_succeed | State succeeds only if every step exits with code 0. | CI gates where all checks must pass. |
any_succeed | State succeeds if at least one step exits with code 0. | Multi-platform builds where one target is sufficient. |
best_effort | State 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workflow_id | string | ✓ | Deployed workflow name or UUID of the child workflow to invoke. | |
mode | string | blocking | blocking | fire_and_forget. Determines whether the parent waits for the child to complete. | |
result_key | string | Blackboard 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}}. | ||
input | string | Handlebars template rendered and passed as the child workflow's start input (--input). |
Execution Modes
| Mode | Parent Behaviour | Blackboard Output |
|---|---|---|
blocking | Waits 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_forget | Starts 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_FLOWAfter 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_idmust reference a deployed workflow. The engine validates this at state entry and fails with a descriptive error if the workflow is not found.result_keyis only meaningful inblockingmode; it is ignored infire_and_forgetmode.- 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
SubworkflowDepthExceededif exceeded. - The child workflow's
timeoutis independent of the parent state'stimeout. If the parent state times out before the child completes, the child is cancelled.
spec.states[*].transitions[]
| Field | Type | Required | Description |
|---|---|---|---|
condition | string | Named condition type (see below). If absent, transition is unconditional. | |
target | string | ✓ | State to transition to. Must exist in spec.states. |
feedback | string | Handlebars string written to {{state.feedback}} for the next state. | |
threshold | number | For score/consensus conditions | Score or consensus threshold (0.0–1.0). |
agreement | number | For consensus | Minimum consensus.confidence required. |
value | string | For exit_code, input_equals | Exact value to match. |
expression | string | For custom | Handlebars boolean expression. |
min / max | number | For score_between | Score range bounds (inclusive). |
Condition Types
| Condition | Applicable Kinds | Description |
|---|---|---|
| (absent) | All | Unconditional fallback. Always matches. Place last. |
always | All | Explicit unconditional. Equivalent to absent condition. |
on_success | Agent, System, Action, ContainerRun, ParallelContainerRun, Subworkflow | State succeeded (exit code 0, agent returned success, or child workflow completed). |
on_failure | Agent, System, Action, ContainerRun, ParallelContainerRun, Subworkflow | State failed. |
exit_code_zero | System, ContainerRun | Exit code was 0. |
exit_code_non_zero | System, ContainerRun | Exit code was non-zero. |
exit_code | System, ContainerRun | Exit code equals value. |
score_above | Agent, ParallelAgents | The state's score is strictly greater than threshold. |
score_below | Agent, ParallelAgents | The state's score is strictly less than threshold. |
score_between | Agent | Score between min and max (inclusive). |
confidence_above | Agent | Validation confidence > threshold. |
consensus | ParallelAgents | Consensus score ≥ threshold AND confidence ≥ agreement. |
all_approved | ParallelAgents | All agents scored ≥ consensus threshold. |
any_rejected | ParallelAgents | At least one agent scored < consensus threshold. |
input_equals | Human | Signal payload matches value. |
input_equals_yes | Human | Answer is yes, y or 1, in any case. |
input_equals_no | Human | Answer is no, n or 0, in any case. |
custom | All | Handlebars 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.
| Class | Lifecycle | Use Case |
|---|---|---|
ephemeral | Auto-deleted after ttl_hours | Build artifacts, scratch code, intermediate files |
persistent | Kept until explicitly deleted via API | Shared 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.
| Variable | Available In | Description |
|---|---|---|
{{intent}} | All states | The caller's natural-language intent string passed at workflow start. |
{{input.KEY}} | All states | Key from the workflow start --input payload (validated against metadata.input_schema). |
{{workflow.context.KEY}} | All states | Value from spec.context. |
{{workflow.storage.workspace}} | volumes[].volume | Reference to the shared workspace volume. |
{{workflow.storage.shared_volumes.NAME}} | volumes[].volume | Reference to a named shared volume. |
{{STATE.output}} | States after STATE | Final output text of an Agent state. |
{{STATE.output.stdout}} | States after STATE | stdout of a System or ContainerRun state. |
{{STATE.output.stderr}} | States after STATE | stderr of a System or ContainerRun state. |
{{STATE.output.exit_code}} | States after STATE | Exit code of a System or ContainerRun state. |
{{STATE.output.duration_ms}} | States after STATE | Wall-clock duration in milliseconds (ContainerRun states). |
{{STATE.output.STEPNAME.stdout}} | States after STATE | Per-step stdout (ParallelContainerRun states). |
{{STATE.output.STEPNAME.stderr}} | States after STATE | Per-step stderr (ParallelContainerRun states). |
{{STATE.output.STEPNAME.exit_code}} | States after STATE | Per-step exit code (ParallelContainerRun states). |
{{STATE.status}} | States after STATE | "success" or "failed". |
{{STATE.score}} | States after STATE | Validation score (Agent states, 0.0–1.0). |
{{STATE.consensus.score}} | States after STATE | Consensus score (ParallelAgents states). |
{{STATE.consensus.confidence}} | States after STATE | Consensus confidence (ParallelAgents states). |
{{STATE.agents.N.output}} | States after STATE | Individual judge full output (ParallelAgents, 0-indexed). |
{{STATE.agents.N.output.FIELD}} | States after STATE | Field from a judge's JSON output (e.g. {{AUDIT.agents.0.output.score}}, {{AUDIT.agents.1.output.reasoning}}). |
{{STATE.result}} | States after STATE | Final output of a Subworkflow state (blocking mode). |
{{STATE.child_execution_id}} | States after STATE | Child workflow execution ID (Subworkflow states). |
{{blackboard.KEY}} | All states | Any key set in spec.context or by a prior update_blackboard action. |
{{state.feedback}} | All states | feedback string from the incoming transition. |
{{human.feedback}} | After Human states | Additional feedback text from the signal --feedback argument. |
{{execution.id}} | All states | Workflow 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:
- Seed: Before the first state runs, the Blackboard is seeded with all
spec.contextconstants. Callers may additionally supply--blackboardkey-value pairs at invocation time; these merge in at the same moment. - Mutation: As each state completes, its output is written to the Blackboard under the state name key.
Systemstates,Actionstates,ContainerRunstates, and theupdate_contextbuilt-in all write structured JSON into the Blackboard. - 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 fromWorkflowExecution.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:
| Helper | Example | Description |
|---|---|---|
{{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"
}| Field | Type | Required | Description |
|---|---|---|---|
score | float (0.0–1.0) | ✓ | Quality/correctness score on a continuous gradient. |
confidence | float (0.0–1.0) | ✓ | Judge's certainty in its assessment. |
reasoning | string | ✓ | Explanation for the score (minimum 10 characters). |
suggestions | string[] | Improvement recommendations. | |
verdict | string | Human-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
| Topic | See |
|---|---|
Writing judge agents for ParallelAgents states | Agent Manifest Reference |
| Step-by-step workflow construction guide | Building Workflows |
Building CI/CD pipelines with ContainerRun | Building CI/CD Pipelines |
| Conceptual FSM overview and state kinds | Workflows |
| Gradient scoring and validation confidence | Validation Guide |
| Storage volumes and AegisFSAL | Storage Gateway |
Version History
| Version | Date | Notes |
|---|---|---|
| v1.0 | 2026-02-16 | Initial canonical format. All four state kinds (Agent, System, Human, ParallelAgents). Named-condition transitions. Handlebars templates. Four consensus strategies. |
| v1.1 | 2026-03-05 | Added 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.2 | 2026-03-25 | Added 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. |
Standard Runtime Registry
The complete language-version-to-image mapping table for AEGIS StandardRuntime — supported versions, base images, pre-installed toolchains, and the version support lifecycle.
Node Configuration Reference
Complete specification for the NodeConfig YAML format (v1.0) — schema, field definitions, credential resolution, model alias system, and example configurations.