What are Workflows?
Declarative finite state machine workflows backed by Temporal. State types including ContainerRun for CI/CD steps, Blackboard context, transition rules, and the Forge reference pattern.
Workflows
A Workflow in AEGIS is a declarative finite state machine (FSM) defined in YAML. It coordinates multiple agent executions, system commands, and human approval gates into a durable, restartable sequence. Workflows are executed by the Temporal-backed workflow engine, which guarantees that execution state survives orchestrator restarts.
Workflow Types: Temporal vs. ToolWorkflows
It is critical to distinguish between the two types of "Workflows" in the AEGIS ecosystem to avoid namespace collisions and conceptual errors.
| Feature | Temporal Workflows (Workflow) | SEAL ToolWorkflows (Macro-Tools) |
|---|---|---|
| Purpose | Async CI/CD pipelines, long-running multi-agent choreography. | Sync REST API macro-tools, context window compression. |
| Backend | Temporal (Durable, stateful, persistent). | SEAL Tooling Gateway (Stateless, sub-second). |
| Primitives | Agent, ContainerRun, HumanApproval. | Sequential REST calls with JSONPath extractors. |
| Duration | Minutes to weeks. | Milliseconds to seconds. |
| Invoked By | Operator or system trigger. | Agent LLM (via standard tools/call). |
This page documents Temporal Workflows. For documentation on REST macro-tools, see the SEAL Gateway.
Workflow Scope and Visibility
Every workflow has a scope that controls who can discover and execute it:
| Scope | Visibility | Use Case |
|---|---|---|
| User | Only the owning user within their tenant | Personal sandbox, experimentation |
| Tenant | All users within the owning tenant | Team-shared workflows (default) |
| Global | All users across all tenants | Platform-standard workflows managed by operators |
Scope Resolution: When you reference a workflow by name, AEGIS resolves it using a narrowest-first strategy: your User-scoped workflows are checked first, then Tenant-scoped, then Global. This means you can shadow a platform workflow with a personal version of the same name.
Promotion and Demotion: Workflows can be promoted (User → Tenant → Global) or demoted (Global → Tenant → User) via CLI or API:
# Deploy a personal workflow
aegis workflow deploy my-workflow.yaml --scope user
# Promote to tenant-wide visibility
aegis workflow promote my-workflow --to tenant
# Promote to global (operator role required)
aegis workflow promote my-workflow --to global
# List all visible workflows (user + tenant + global)
aegis workflow list --visibleDirect jumps between User and Global are not allowed — you must promote through Tenant first to enforce a review step.
Semantic Discovery (Enterprise)
On nodes with the discovery service configured, registered workflows are automatically indexed for semantic search. Agents and operators can find workflows by natural-language intent (e.g. "deploy Node.js to Kubernetes") using the aegis.workflow.search MCP tool, rather than browsing the full list. This is an enterprise feature; nodes without discovery configured use aegis.workflow.list for enumeration.
Manifest Structure
A workflow manifest declares the FSM states and transitions, along with optional metadata including input_schema (what the workflow accepts), output_schema (the shape of the workflow's structured output), and output_template (Handlebars expressions that extract the final output from the Blackboard at completion).
apiVersion: 100monkeys.ai/v1
kind: Workflow
metadata:
name: code-review-pipeline
version: "1.0.0"
labels:
category: development
spec:
context:
review_threshold: 0.85
initial_state: ANALYZE
states:
ANALYZE:
kind: Agent
agent: code-analyzer
timeout: 120s
transitions:
- condition: on_success
target: REVIEW
- condition: on_failure
target: FAILED
REVIEW:
kind: Agent
agent: code-reviewer
timeout: 180s
transitions:
- condition: score_above
threshold: 0.85
target: APPROVE
- condition: score_below
threshold: 0.85
target: FAILED
feedback: "Score too low ({{REVIEW.score}}): {{REVIEW.output.reasoning}}"
APPROVE:
kind: Human
prompt: |
Review score: {{REVIEW.score}}
Analysis: {{REVIEW.output}}
Approve to merge? (yes/no)
timeout: 86400s
transitions:
- condition: input_equals_yes
target: MERGE
- condition: input_equals_no
target: REJECTED
feedback: "{{human.feedback}}"
MERGE:
kind: System
command: "aegis-merge-tool --pr-id {{input.pr_id}}"
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: []
REJECTED:
kind: System
command: "echo rejected"
transitions: []State Types
Agent
Executes an AEGIS agent using the 100monkeys iterative loop. The state waits for the agent execution to reach completed or failed before evaluating transitions.
ANALYZE:
kind: Agent
agent: code-analyzer # must be a deployed agent name
timeout: 300s # cancels execution if not complete within this time
input: |
{{workflow.task}}
transitions:
- condition: on_success
target: REVIEW
- condition: on_failure
target: FAILEDThe agent's final output is available as {{ANALYZE.output}}. Status is available as {{ANALYZE.status}}.
System
Runs a shell command on the orchestrator host. Useful for triggering external processes, sending notifications, or performing cleanup.
NOTIFY:
kind: System
command: "curl -X POST https://hooks.example.com/notify -d '{\"status\": \"done\"}'"
timeout: 30s
transitions:
- condition: exit_code_zero
target: DONE
- condition: exit_code_non_zero
target: FAILEDHuman
Suspends the workflow and waits for an operator to signal a decision. The workflow persists durably in Temporal — it waits until timeout, 3600s when unset.
APPROVAL_GATE:
kind: Human
prompt: |
Output: {{GENERATE.output}}
Approve to proceed? (yes/no)
timeout: 86400s # 24 hours; default_response taken if not signalled
default_response: "no"
transitions:
- condition: input_equals_yes
target: PROCEED
- condition: input_equals_no
target: REDESIGN
feedback: "{{human.feedback}}"To resume a suspended workflow, send a signal through the workflow execution API:
POST /v1/workflows/executions/{execution_id}/signal
Content-Type: application/json
{
"response": "yes"
}ParallelAgents
Fans out to multiple agent executions simultaneously. All agents run concurrently; the state waits until all have completed (or timeout elapses) before evaluating transitions using the consensus configuration.
PARALLEL_REVIEW:
kind: ParallelAgents
agents:
- agent: security-reviewer
input: "Security audit: {{GENERATE.output}}"
weight: 2.0
timeout_seconds: 300
- agent: performance-reviewer
input: "Performance review: {{GENERATE.output}}"
weight: 1.0
timeout_seconds: 180
- agent: style-reviewer
input: "Style review: {{GENERATE.output}}"
weight: 1.0
timeout_seconds: 60
consensus:
strategy: weighted_average # weighted_average | majority | unanimous | best_of_n
threshold: 0.85
min_agreement_confidence: 0.75
min_judges_required: 2
timeout: 600s
transitions:
- condition: consensus
threshold: 0.85
agreement: 0.75
target: DONE
- condition: score_below
threshold: 0.85
target: FAILED
feedback: "Parallel review failed (score: {{PARALLEL_REVIEW.consensus.score}})"Individual results are available as {{STATENAME.agents.N.output}} (0-indexed). The aggregated score is {{STATENAME.consensus.score}}.
ContainerRun
Executes a deterministic command inside an isolated container — no LLM, no iteration loop. Use ContainerRun for CI/CD steps such as building binaries, running test suites, linting, or pushing deployment artifacts. The container is created, the command runs to completion, and the container is destroyed.
BUILD:
kind: ContainerRun
name: "Compile and Build" # human-readable label for the Synapse UI
image: "rust:1.75-alpine" # any Docker image or standard runtime reference
command: ["cargo", "build", "--release"]
workdir: "/workspace"
volumes:
- name: workspace
mount_path: /workspace
resources:
cpu: 2000 # millicores (2000 = 2 CPU cores)
memory: "4Gi"
timeout: "10m"
env:
CARGO_HOME: "/workspace/.cargo"
transitions:
- condition: exit_code_zero
target: TEST
- condition: exit_code_non_zero
target: FIX_BUILD_ERRORS
feedback: "Build stderr: {{BUILD.output.stderr}}"The step's output is stored on the Blackboard under the state name. Access it with {{BUILD.output.exit_code}}, {{BUILD.output.stdout}}, and {{BUILD.output.stderr}}.
You can also write multi-line scripts using shell: true:
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: NOTIFY_FAILUREParallelContainerRun
Runs multiple container commands concurrently within a single workflow state. All steps share the same volume mounts and complete before transitions are evaluated. Use it for running a test matrix, running lint + unit tests + format checks simultaneously, or building multiple build targets.
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 # all_succeed | any_succeed | best_effort
transitions:
- condition: on_success
target: REVIEW
- condition: on_failure
target: FIX_TEST_ERRORSPer-step output is accessible by name: {{TEST.output.unit-tests.stdout}}, {{TEST.output.lint.stderr}}, etc.
The three completion strategies control how individual step outcomes are aggregated:
| Strategy | Behaviour |
|---|---|
all_succeed | State succeeds only if every step exits with code 0. |
any_succeed | State succeeds if at least one step exits with code 0. |
best_effort | State always transitions with on_success; per-step results are available on the Blackboard regardless. |
Subworkflow
Invokes another deployed workflow as a child execution. Use Subworkflow to compose workflows — extract reusable pipelines (data processing, deployment, validation) into standalone workflows and call them from a parent.
Two execution modes are supported:
| Mode | Behaviour |
|---|---|
blocking | The parent state waits for the child workflow to complete. The child's final Blackboard is written to the parent Blackboard under result_key. |
fire_and_forget | The parent starts the child workflow and immediately transitions to the next state. The child runs independently. |
TRIGGER_CHILD:
kind: Subworkflow
workflow_id: data-pipeline-v2
mode: blocking
result_key: pipeline_output
input: "{{workflow.context.task}}"
transitions:
- condition: on_success
target: PROCESS_RESULT
- condition: on_failure
target: HANDLE_ERRORIn blocking mode, the child workflow's final output is available as {{TRIGGER_CHILD.result}} and the full result object is stored under the result_key on the parent Blackboard (e.g., {{blackboard.pipeline_output}}). In fire_and_forget mode, only the child's execution ID is written to the Blackboard as {{TRIGGER_CHILD.child_execution_id}}.
The Blackboard
The Blackboard is a mutable key-value store shared across all states in a workflow execution. It is seeded from spec.context, can be overridden at workflow start with blackboard, and is updated as states complete.
Lifecycle
The Blackboard has three lifecycle phases:
- Seed — Before the workflow starts, the orchestrator writes all
spec.contextkeys into the Blackboard and then merges any startupblackboardoverrides. Startup overrides must be a JSON or YAML object and win on same-named top-level keys. The reservedworkflowkey cannot be overridden. - Live execution — The Temporal worker owns the Blackboard during execution. It receives the merged startup Blackboard, preserves authoritative
workflow.*metadata, and writes each completed state's output back under the state's name (for exampleREQUIREMENTS.output,REQUIREMENTS.status,REQUIREMENTS.score). All Handlebars templates in subsequent states are resolved against this live state. - Capture — When the workflow finishes, the orchestrator captures the final Blackboard snapshot from Temporal and persists it to PostgreSQL, where it is available via the execution history API.
Startup Overrides
Use startup Blackboard overrides when you want to inject per-run variables without changing the workflow manifest:
aegis workflow run release-pipeline \
--input @input.yaml \
--blackboard @blackboard.yamlExample blackboard.yaml:
review_threshold: 0.92
deploy_env: staging
release:
candidate: rc-4Rules:
--blackboardaccepts inline JSON/YAML or@fileinput.- The value must be an object, not a scalar or array.
- Blackboard overrides are merged on top of
spec.context. workflow.*metadata remains authoritative and cannot be replaced by overrides.- The live Blackboard is passed into downstream Agent states as structured execution context.
Accessing Blackboard Values
Use Handlebars template syntax in input, command, env, prompt, and transition expression/feedback fields:
# Access a prior state's output
command: "process-results --input '{{ANALYZE.output}}'"
# Access a spec.context or startup blackboard override value
command: "run-tests --threshold {{workflow.context.review_threshold}}"
# Access workflow start input
command: "git clone {{input.repo_url}}"
# Access top-level blackboard values used during live execution
command: "deploy --env {{blackboard.deploy_env}}"Available template variables:
| Variable | Description |
|---|---|
{{workflow.task}} | task key from the workflow start --input payload. |
{{workflow.context.KEY}} | Value from spec.context. |
{{STATE.output}} | Final text output of an Agent state. |
{{STATE.output.stdout}} | stdout of a System or ContainerRun state. |
{{STATE.output.stderr}} | stderr of a System or ContainerRun state. |
{{STATE.output.exit_code}} | Exit code of a System or ContainerRun state. |
{{STATE.output.STEPNAME.stdout}} | Per-step stdout of a ParallelContainerRun state. |
{{STATE.output.STEPNAME.stderr}} | Per-step stderr of a ParallelContainerRun state. |
{{STATE.output.STEPNAME.exit_code}} | Per-step exit code of a ParallelContainerRun state. |
{{STATE.status}} | Status: success, failed, or timeout. |
{{STATE.score}} | Validation score of an Agent state (0.0–1.0). |
{{STATE.consensus.score}} | Aggregated score of a ParallelAgents state. |
{{STATE.agents.N.output}} | Individual judge output (ParallelAgents, 0-indexed). |
{{STATE.result}} | Final output of a Subworkflow state (blocking mode). |
{{STATE.child_execution_id}} | Child execution ID of a Subworkflow state. |
{{blackboard.KEY}} | Any key from merged startup Blackboard data or any key written during execution. |
{{state.feedback}} | feedback string from the incoming transition. |
{{human.feedback}} | Feedback text from the Human signal --feedback argument. |
{{input.KEY}} | Key from the workflow start --input payload. |
Workflow Output
Workflows can declare their output shape using metadata.output_schema and metadata.output_template. When the workflow reaches a terminal state, the engine evaluates each output_template value as a Handlebars expression against the final Blackboard, coerces the rendered values to the types declared in output_schema, and stores the result as final_output on the WorkflowExecution. This final_output is returned as last_output in aegis.workflow.wait tool responses, giving callers a structured, typed result without parsing raw agent text.
For full field definitions and type coercion rules, see the Workflow Manifest Reference.
Transition Rules
Each state has a transitions list. Rules are evaluated in order; the first matching condition wins.
transitions:
# Score-based routing (Agent states)
- condition: score_above
threshold: 0.95
target: EXCELLENT
- condition: score_between
min: 0.70
max: 0.95
target: GOOD
# Exit-code routing (System states)
- condition: exit_code_zero
target: SUCCESS
- condition: exit_code_non_zero
target: RETRY
feedback: "Command failed: {{EXECUTE.output.stderr}}"
# Human approval routing (Human states)
- condition: input_equals_yes
target: APPROVED
- condition: input_equals_no
target: REJECTED
feedback: "{{human.feedback}}"
# Consensus routing (ParallelAgents states)
- condition: consensus
threshold: 0.85
agreement: 0.75
target: PASSED
# Custom Handlebars expression
- condition: custom
expression: "{{blackboard.retry_count < workflow.context.max_retries}}"
target: RETRY
# Unconditional fallback — always place last
- condition: always
target: FAILEDA transition with no condition (or condition: always) is an unconditional fallback. Always include one as the last transition to prevent the FSM from stalling. For the complete list of condition types per state kind, see the Workflow Manifest Reference.
The Forge
The Forge is a built-in workflow, the-forge, that develops one change in one of your repositories: requirements and a design, each approved by you, then tests written first, the implementation, your test suite run in a container on the clone, a review by three judges, and a commit on the run's work branch. With draft_only false, the commit then lands on the repository's branch as a fast-forward after your approval. A node deploys it, with its seven agents, when spec.deploy_builtins is on; it is registered under aegis-system with global scope.
ANALYZE → AWAIT_REQUIREMENTS_APPROVAL → ARCHITECT → AWAIT_ARCH_APPROVAL → TEST → CHECK_TESTS
→ CODE → EXECUTE_TESTS → DIFF → AUDIT → COMMIT → COMPLETE (draft_only, the default)
→ LAND → COMPLETE, or LAND_REFUSED| State | Kind | What it does | Transitions |
|---|---|---|---|
ANALYZE | Agent requirements-analyst | Reads the repository at {{repository.path}} and the task; answers numbered functional and non-functional requirements and acceptance criteria. | success: AWAIT_REQUIREMENTS_APPROVAL; failure: FAILED |
AWAIT_REQUIREMENTS_APPROVAL | Human, 3600 s | Asks you to approve the requirements. | yes: ARCHITECT; no: back to ANALYZE |
ARCHITECT | Agent architect-agent | Designs the change in the repository's own conventions and names every file to change. | success: AWAIT_ARCH_APPROVAL; failure: FAILED |
AWAIT_ARCH_APPROVAL | Human, 3600 s | Asks you to approve the design. | yes: TEST; no: back to ARCHITECT |
TEST | Agent tester-agent, at most 3 visits | Writes the tests in the repository's own test layout, failing against the unchanged tree; entered again, it reads the suite's output and fixes the files that did not load. | success: CHECK_TESTS; failure: FAILED |
CHECK_TESTS | ContainerRun | Runs the suite once on the tests as written, as EXECUTE_TESTS does. A test file that did not load (the suite reports a test module it failed to import or collect, and the cause is a SyntaxError, IndentationError or TabError in the clone, or the test's own module missing) ends it with exit code 86. | 86: back to TEST, with stderr and stdout; otherwise: CODE, with the exit code, stderr and stdout |
CODE | Agent coder-agent, at most 5 visits | Changes the implementation, never the tests; entered again, it reads the suite's output or the review's reports. | success: EXECUTE_TESTS; failure: FAILED |
EXECUTE_TESTS | ContainerRun | Runs test_command in test_image on the clone, the repository's working tree mounted at /workspace, where the suite runs, on the node's egress network, with 2000 millicores, 4 GiB and 1800 s. | exit 0: DIFF; otherwise: CODE, with stderr and stdout |
DIFF | Action repository_diff | The change against the commit the work branch started from, as a unified diff. | success: AUDIT; failure: FAILED |
AUDIT | ParallelAgents | code-reviewer-agent (weight 1.0), critic-agent (1.5) and security-auditor-agent (2.0) score the change against the requirements, the design, the diff and the test output; weighted average, threshold 0.95. | 0.95 with agreement 0.8: COMMIT; below 0.95, or agreement under 0.8: CODE, with the three reports |
COMMIT | Action repository_commit | Commits every change on the work branch, as you, with the message the-forge: <the task's first line>. | draft_only true or absent: COMPLETE; false: LAND; failure: FAILED |
LAND | Action repository_land | Lands the work branch on the repository's branch as a fast-forward, after your approval. | success: COMPLETE; failure: LAND_REFUSED |
COMPLETE, FAILED, LAND_REFUSED | Action update_blackboard | Write outcome, commit_sha, branch and the refusal's sentence, where there is one. FAILED's sentence is DIFF's or COMMIT's refusal, else the error that ended ANALYZE, ARCHITECT, TEST or CODE. | none |
A fourth entry into TEST or a sixth into CODE ends the run at its visit limit. No state of the Forge runs a shell command in the core process: the suite runs in a container on the clone, and DIFF, COMMIT and LAND are the workflow's own repository actions. A run that changed nothing ends FAILED at COMMIT with "nothing to commit: working tree is clean".
Its inputs.
| Input | Type | Required | Description |
|---|---|---|---|
task | string | ✓ | What to change. Its first line names the commit. |
test_command | string | ✓ | The test suite, run by /bin/sh -c in the repository's root. |
test_image | string | ✓ | The image the suite runs in, a reference with a tag. |
context | string | Anything else the analyst should know. | |
draft_only | boolean | Default true: the run ends with the commit on the work branch in your volume and nothing pushed. false lands it after your approval. | |
tree_reset | string | How the repository's tree is left before the first state: hard (the default) resets it to the commit the run starts from and removes every untracked and ignored path; list removes untracked paths and the ignored paths purge matches; none removes untracked paths that are not ignored. | |
purge | string array | With tree_reset list, the glob patterns of untracked or ignored paths to remove, as git's pathspec matches them: a directory is matched as dir/ or dir/**. A tracked file is never removed. | |
test_globs | string array | The glob patterns the repository's tracked test files are listed by, for the tester. Default ["**/test/**", "**/tests/**", "**/__tests__/**", "**/test_*", "**/*_test.*", "**/*.test.*"]. |
Every agent is told that the suite runs with the repository mounted at /workspace and the working directory /workspace, and names every path relative to the repository's root, never as an absolute /workspace/... path. The tester is told that the suite runs in the given test image as it is, with nothing installed: a test uses only the runtime's standard library and the repository's own tree, never a third-party module or an external binary the image may lack, and reads a text file in text mode or normalizes \r\n.
Its agents. The five that only read (requirements-analyst, architect-agent and the three judges) list the reading fs.* tools, fs.search before fs.grep so that an agent finds code by its text and structure first (fs.search), aegis.git.status and aegis.git.diff; tester-agent and coder-agent add the writing fs.* tools and cmd.run. None lists aegis.git.commit, aegis.git.push or aegis.git.land: committing and landing are the workflow's. Each agent sees the repository's working tree at {{repository.path}}, /workspace/<label>. A cmd.run runs in /workspace unless the call names cwd, and a call naming an argument cmd.run does not take is refused with a sentence naming cwd (cmd.run). Each judge answers {score, confidence, reasoning, suggestions}, each agent's answer is validated by the built-in code-quality-judge, and all seven run on the model alias smart. The architect names a change as text and the lines it touches, never as bytes or escape sequences such as \r\n; the tester treats a design's line endings and escape sequences as no criterion, and no test asserts on \r, a line ending or a byte sequence, which the tester's judge also checks.
Its tries. Each of the seven agents takes up to 5 tries of 900 s each (iteration_timeout: "900s"), each answer judged by code-quality-judge within 300 s, under an execution bound of 2445 s (resources.timeout: "2445s"): room for two whole tries of 1200 s, try and judge, the 15 s wait between them and 30 s to start a try's container. The judges of AUDIT are bounded at 2445 s too. The first try always starts. A later try starts only when the time left under the bound is at least the 1200 s a try needs; otherwise the agent's execution ends at once with "Execution ended: <n> s left under the 2445 s bound, under the 1200 s a try needs". tester-agent and coder-agent make at most 24 tool calls a try (max_tool_calls: 24), every call the model asks for counted, and the tester's model calls are bounded at 120 s (llm_timeout_seconds: 120). Within a try, a model call is bounded by the lesser of llm_timeout_seconds and the try's time left less 10 s (at most a quarter of the try), kept for the answer's way back; no call is sent with no more than that left, and the try then ends and answers from its facts. A model call that meets the provider's rate limit or unavailability (a 5xx other than its time limit) is retried to the try's time left; a try it still ends is not counted as one of the 5, and the task log reads "The model on alias 'smart' was over its rate limit for <t> of retries; this try ended there and is not counted." (LLM Providers). A try the loop ends by its clock, its call budget or the execution's deadline answers from its facts, "Files written:" then each file the execution created or changed with its bytes and content, or "No file was written or changed in this try.", and that answer goes to the agent's judge as any answer does.
Landing. LAND asks for your approval of aegis.git.land as any approval-gated tool does. Approved, the orchestrator pushes the work branch to origin, then the work branch's HEAD to the repository's branch, never with force, and the run's log gains the line "Landed <commit> of repository <label> on <branch>". When the branch has moved on the remote, nothing is landed: "the remote branch '<ref>' has commits this run does not have; nothing was landed", with the work branch pushed and the branch unchanged. A repository bound to a tag or a commit is refused before any push: "a run lands only on a branch; '<ref>' is not one". A declined approval pushes nothing. A landing is never a merge, a rebase or a squash.
Starting the Forge
Start it as any workflow, naming exactly one of your git repository bindings under the starting call's top-level repositories (a key the model-facing schemas do not list: a client sets it from your choice); a run naming another number is refused before anything is held with "workflow 'the-forge' works on exactly 1 repository; this run names <n>".
// aegis.workflow.run
{
"name": "the-forge",
"input": {
"task": "Add a --json flag to the export command",
"test_command": "cargo test --locked",
"test_image": "rust:1.92"
},
"repositories": [{ "binding_id": "4f6b1c1e-2d3a-4b5c-8d7e-9f0a1b2c3d4e" }]
}Answer its two approval gates yourself, yes or no: in Zaru Web on the gate card under the run, on the Approvals page or on the run's execution page (Human Gates of a Workflow Run); from your own client with aegis.workflow.signal or POST /v1/workflows/executions/{id}/signal (Answering a Gate). Follow the run with aegis.workflow.logs or aegis.workflow.wait. In Zaru, architect mode lists aegis.workflow.run; no mode offers Zaru's companion aegis.workflow.signal: once the run has started, Zaru says each gate appears on the run's card and in Approvals, ends its turn, and never answers a gate. The run's repository needs the node's step network for its test step (spec.storage.git.step_network, see Node Configuration).
Carbon Forge
Carbon Forge is a built-in workflow, carbon-forge 1.2.0, that develops one change in one of your Carbon Forge trees on a lane of the run's own, as the Forge does in a git repository: requirements and a design, each approved by you, then tests written first, the implementation, your test suite run in a container on the tree, a review by three judges, and the change written to the run's lane. With draft_only false, the lane then lands on the trunk as one changeset after your approval, and the landed run becomes a cut. Its states are the Forge's, with the tree actions in place of the repository actions and one more state, DRIFT. The run names its tree under the starting call's trees ([{workspace, path, revision}]) beside its contexts; before the first agent the tree's revision is materialized into the run's volume, every file verified against its SHA-256, and mounted at /workspace in every agent state and step container. Every path in the prompts and in the tests is written relative to the tree's root.
ANALYZE → AWAIT_REQUIREMENTS_APPROVAL → ARCHITECT → AWAIT_ARCH_APPROVAL → TEST → CHECK_TESTS
→ CODE → EXECUTE_TESTS → DIFF → AUDIT → COMMIT → DRIFT → COMPLETE (draft_only, the default)
→ LAND → CUT → COMPLETE, or LAND_REFUSED, or CUT_REFUSEDThe states below are the ones whose definition differs from the Forge's. ANALYZE, AWAIT_REQUIREMENTS_APPROVAL, ARCHITECT, AWAIT_ARCH_APPROVAL, TEST, CHECK_TESTS, CODE, EXECUTE_TESTS and AUDIT are the Forge's, with the tree at /workspace in place of the repository's clone.
| State | Kind | What it does | Transitions |
|---|---|---|---|
DIFF | Action tree_diff | The run's change against the tree's revision. | success: AUDIT; failure: FAILED |
COMMIT | Action tree_write | Writes the run's tree to the run's own lane, with the message carbon-forge: <the task's first line>. | success: DRIFT; failure: FAILED |
DRIFT | Action drift_report | Reads the lane's drift report with the Carbon Forge tool symbols.drift on the run's lane and tree: each definition the change adds, removes or re-signs in a seam the workspace's governed seams declare, and whether a page governing it changed on the lane too. The step answers the report's hash, its counts by class and the whole report, or the sentence of a report that was not read. The report advises and never ends the run: a report, a refusal and a failure all go on. | draft_only true or absent: COMPLETE; otherwise: LAND, whatever the report |
LAND | Action tree_land | Lands the run's lane on the trunk as one changeset, after your approval. The approval request shows you the drift report's counts by class and its first ten findings beside the tree, the lane and the intent; the verdict stays yours. A conflict ends in LAND_REFUSED with Carbon Forge's own sentence. | success: CUT; failure: LAND_REFUSED |
CUT | Action tree_cut | Names a snapshot of the tree's workspace with the input cut, else forge-<execution id>. | success: COMPLETE; failure: CUT_REFUSED |
COMPLETE, FAILED, LAND_REFUSED, CUT_REFUSED | Action update_blackboard | Write outcome, commit_sha, branch and the refusal's sentence, where there is one. COMPLETE, LAND_REFUSED and CUT_REFUSED also write drift, the lane's drift report or the sentence of one not read, and COMPLETE writes the landed run's cut and snapshot_id, empty for a draft. | none |
A draft_only run never reaches LAND, and so never cuts. Its inputs are the Forge's task, test_command, test_image, context and draft_only, with draft_only true (the default) ending the run with the change on the run's lane and the trunk untouched, and one more, cut, the name of the cut the landed run becomes.
Deploying and Managing Workflows
# Deploy a workflow manifest
aegis workflow deploy ./my-workflow.yaml --force
# List all deployed workflows
aegis workflow list
# Start a workflow execution
aegis workflow run <workflow-name> --input '{"key": "value"}'
# Start with startup blackboard overrides from JSON or YAML
aegis workflow run <workflow-name> --blackboard @blackboard.yaml
# Follow workflow logs
aegis workflow logs <execution-id> --follow --verbose
aegis workflow logs <execution-id> --transitions
# Inspect a running or completed execution
aegis workflow executions get <execution-id>Use --force when you are re-deploying the same workflow name and version.
For execution status and Human-state signaling, use the CLI:
aegis workflow executions get <execution-id>
aegis workflow signal <execution-id> --response yesThe underlying REST API remains available for integrations, but the CLI is the preferred operator path.
See the Workflow Manifest Reference for the complete field specification. See CLI Capability Matrix for currently CLI-exposed workflow operations.