Aegis Orchestrator
Workflows

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.

FeatureTemporal Workflows (Workflow)SEAL ToolWorkflows (Macro-Tools)
PurposeAsync CI/CD pipelines, long-running multi-agent choreography.Sync REST API macro-tools, context window compression.
BackendTemporal (Durable, stateful, persistent).SEAL Tooling Gateway (Stateless, sub-second).
PrimitivesAgent, ContainerRun, HumanApproval.Sequential REST calls with JSONPath extractors.
DurationMinutes to weeks.Milliseconds to seconds.
Invoked ByOperator 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:

ScopeVisibilityUse Case
UserOnly the owning user within their tenantPersonal sandbox, experimentation
TenantAll users within the owning tenantTeam-shared workflows (default)
GlobalAll users across all tenantsPlatform-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 --visible

Direct 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: FAILED

The 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: FAILED

Human

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_FAILURE

ParallelContainerRun

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_ERRORS

Per-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:

StrategyBehaviour
all_succeedState succeeds only if every step exits with code 0.
any_succeedState succeeds if at least one step exits with code 0.
best_effortState 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:

ModeBehaviour
blockingThe 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_forgetThe 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_ERROR

In 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:

  1. Seed — Before the workflow starts, the orchestrator writes all spec.context keys into the Blackboard and then merges any startup blackboard overrides. Startup overrides must be a JSON or YAML object and win on same-named top-level keys. The reserved workflow key cannot be overridden.
  2. 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 example REQUIREMENTS.output, REQUIREMENTS.status, REQUIREMENTS.score). All Handlebars templates in subsequent states are resolved against this live state.
  3. 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.yaml

Example blackboard.yaml:

review_threshold: 0.92
deploy_env: staging
release:
  candidate: rc-4

Rules:

  • --blackboard accepts inline JSON/YAML or @file input.
  • 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:

VariableDescription
{{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: FAILED

A 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
StateKindWhat it doesTransitions
ANALYZEAgent requirements-analystReads 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_APPROVALHuman, 3600 sAsks you to approve the requirements.yes: ARCHITECT; no: back to ANALYZE
ARCHITECTAgent architect-agentDesigns the change in the repository's own conventions and names every file to change.success: AWAIT_ARCH_APPROVAL; failure: FAILED
AWAIT_ARCH_APPROVALHuman, 3600 sAsks you to approve the design.yes: TEST; no: back to ARCHITECT
TESTAgent tester-agent, at most 3 visitsWrites 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_TESTSContainerRunRuns 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
CODEAgent coder-agent, at most 5 visitsChanges the implementation, never the tests; entered again, it reads the suite's output or the review's reports.success: EXECUTE_TESTS; failure: FAILED
EXECUTE_TESTSContainerRunRuns 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
DIFFAction repository_diffThe change against the commit the work branch started from, as a unified diff.success: AUDIT; failure: FAILED
AUDITParallelAgentscode-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
COMMITAction repository_commitCommits 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
LANDAction repository_landLands the work branch on the repository's branch as a fast-forward, after your approval.success: COMPLETE; failure: LAND_REFUSED
COMPLETE, FAILED, LAND_REFUSEDAction update_blackboardWrite 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.

InputTypeRequiredDescription
taskstring✓What to change. Its first line names the commit.
test_commandstring✓The test suite, run by /bin/sh -c in the repository's root.
test_imagestring✓The image the suite runs in, a reference with a tag.
contextstringAnything else the analyst should know.
draft_onlybooleanDefault true: the run ends with the commit on the work branch in your volume and nothing pushed. false lands it after your approval.
tree_resetstringHow 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.
purgestring arrayWith 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_globsstring arrayThe 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_REFUSED

The 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.

StateKindWhat it doesTransitions
DIFFAction tree_diffThe run's change against the tree's revision.success: AUDIT; failure: FAILED
COMMITAction tree_writeWrites the run's tree to the run's own lane, with the message carbon-forge: <the task's first line>.success: DRIFT; failure: FAILED
DRIFTAction drift_reportReads 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
LANDAction tree_landLands 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
CUTAction tree_cutNames 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_REFUSEDAction update_blackboardWrite 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 yes

The 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.

On this page