Purpose

Defines the standard structure and governance rules for workflows running on Synedrix OS. Workflow contracts make execution predictable, testable, and observable by forcing each workflow to declare its trigger, inputs, outputs, side effects, approvals, and error behavior.

Why contracts matter

Multi-agent systems become brittle when workflows rely on implicit assumptions, undocumented side effects, or free-form outputs. A workflow contract turns each workflow into a typed business capability that orchestration, policy, and observability layers can reason about consistently.

Canonical workflow fields

Every field a workflow contract must declare, and what each one is for.

FieldDescription
workflow_idStable identifier such as WF-COM-001-PRODUCT-CREATION
nameHuman-readable name
domainDomain pack or cross-domain scope
purposeBusiness outcome the workflow exists to produce
trigger_typeEvent, schedule, human command, API call, or callback
trigger_sourceSystem or actor that initiates the workflow
input_contractExpected normalized input schema
validation_rulesRequired fields, enums, thresholds, schema checks
execution_patternHow tasks within the workflow are sequenced and coordinated (see § Execution patterns)
agent_rolesAgents expected to participate. Only agent-driven steps are listed here; deterministic steps are listed in the execution_pattern step declarations.
tool_dependenciesTools, APIs, and adapters required
side_effectsExternal writes and persistent changes
approval_requirementsPolicy or HITL gates
output_contractDeclares result_schema (shape of outcome.result), emitted_events, outcome_status_on_success, and partial_failure_conditions. The full outcome envelope shape is governed by Synedrix OS Outcome Spec.
idempotency_strategyDuplicate prevention rules
retry_policyRetry count, backoff, compensation behavior
error_policyFailure handling and escalation
observability_signalsLogs, metrics, trace fields, correlation IDs
security_scopeSystems and permissions touched
versionContract version

Workflow versioning

Workflow contracts use semantic versioning for the version field:

  • version is a SemVer string (MAJOR.MINOR.PATCH) that tracks contract changes over time.
  • The workflow_id (for example, WF-TRD-MASTER-ORCHESTRATION-001, WF-OS-APPROVAL-ROUTING-001) is a stable identity and does not include version information.
  • Backwards-compatible changes (for example, stricter validation, additional optional fields, improved observability) increment MINOR or PATCH.
  • Backwards-incompatible changes to the input or output contract, side effects, or approval behavior require a MAJOR version bump and explicit migration notes.
  • Legacy IDs (such as WF-01, WF-HEARTBEAT) may be recorded in a legacy_id header field during migration but are not treated as canonical identities.

Spec files like this one use vX.Y in their headers to track spec evolution. That spec version is independent of individual workflow contract versions.

Required workflow sections

  1. Metadata - ID, name, owner domain, version.
  2. Purpose statement - one-paragraph business outcome.
  3. Trigger definition - type, source, sync/async, event or API path.
  4. Input contract - typed, normalized, validated before logic executes.
  5. Validation rules - required fields, enums, ranges, auth/signature validation, policy preconditions.
  6. Execution pattern - primary pattern, plus any pattern-specific parameters (iterations, quorum, branches, sub-workflow IDs).
  7. Agent participation model - which agents analyze, decide, validate, execute, escalate. Covers agent-driven steps only.
  8. Tool dependency declaration - all external adapters and internal services the workflow may call.
  9. Side-effect declaration - every persistent or external write.
  10. Approval requirements - autonomous, policy-approved, HITL-approved, or both.
  11. Output contract - structured final status, emitted events, IDs, exception payloads.
  12. Idempotency strategy - duplicate prevention key and handling.
  13. Retry and compensation policy - tool-call failures, partial writes, timeouts, missing callbacks.
  14. Error policy - fatal vs recoverable, escalation targets, dead-letter behavior, manual review.
  15. Observability specification - correlation IDs, log events, metric names, trace requirements, policy decision records. Workflows that produce user-visible responses MUST declare response_finalized as an emitted event and are subject to the os.response.sampled_for_review pipeline defined in Synedrix OS Observability Metrics Spec §7.5. Workflows MAY declare requires_observability_families as an optional metadata field listing the canonical metric families (e.g. [retrieval, groundedness, cost, risk_alignment, user_trust]) that must be collected for any agent invocation within the workflow.

Step types

A step in a workflow contract is either agent-drivenordeterministic. The step_type field is the canonical discriminator.

agent-driven

An agent-driven step invokes an LLM-backed agent. The agent interprets its input, may invoke tools, and returns an outcome. All LLM inference, tool calls, policy evaluations, and decisions happen inside agent-driven steps.

- step_id: string              # Unique within the workflow
  step_type: agent-driven      # Explicit declaration (may be omitted when agent_role is set; agent-driven is the default)
  agent_role: string           # Required. Must match an entry in agent_roles.
  task_class: string           # The task type this agent should perform (e.g., validate-input, analyse-risk)
  depends_on: []               # Optional. List of step_ids that must complete before this step runs.
Illustrative example, not a production implementation. Review and test before use.

Rules for agent-driven steps:

  • agent_role is required and must reference a declared entry in the workflow’s agent_roles field.
  • All tool calls, LLM inference, policy gates, and outcomes are governed by the referenced agent’s spec and runtime policy.
  • Agent-driven steps must return a structured outcome conforming to the Outcome Envelope (Outcome Spec v0.1).

deterministic

A deterministic step executes fixed, non-inferential logic: schema validation, format conversion, data joins, rule-based transforms, event publishing, lookup table resolution. No LLM inference occurs. The step is implemented as a native n8n node, a registered function, or a direct tool call that does not require agent reasoning.

- step_id: string              # Unique within the workflow
  step_type: deterministic     # Required. Marks the step as non-inferential.
  transform: string            # What the step does (e.g., schema-validate, format-convert, data-join, publish-event)
  function_ref: string         # Optional. Pointer to the specific implementation:
                               #   n8n node type (e.g., n8n-nodes-base.set)
                               #   registered function ID
                               #   tool_id from tool_dependencies
  agent_role: null             # Must be null or absent. An agent_role on a deterministic step is a config error.
  depends_on: []               # Optional. List of step_ids that must complete before this step runs.
Illustrative example, not a production implementation. Review and test before use.

Rules for deterministic steps:

  • agent_role must be null or absent. Setting an agent_role on a deterministic step is a contract validation error.
  • No LLM endpoint may be invoked. Deterministic steps must not call any model inference API.
  • transform is required. A deterministic step without a declared transform is underspecified.
  • Deterministic steps do not produce an Outcome Envelope. They pass their output directly to the next step as structured data. Only agent-driven steps produce outcomes.
  • Retry behavior for deterministic steps is governed by the workflow’s retry_policy, not by an agent runtime policy.

When to use each

SituationStep type
Schema validation, format conversion, data normalisationdeterministic
Lookup table resolution, data join, record enrichment from a databasedeterministic
Event publishing, webhook dispatch, queue writedeterministic
Rule-based routing where the condition is a fixed field comparisondeterministic
LLM inference, reasoning, language generationagent-driven
Risk assessment, policy evaluation, decision-makingagent-driven
Tool calls that require agent judgment about which tool to useagent-driven
Any step that may escalate, require HITL, or produce a quality signalagent-driven

Execution patterns

The execution_pattern field declares how the orchestration layer sequences and coordinates tasks and agent invocations within the workflow. Nine canonical patterns are defined. Patterns may be composed: a hierarchical workflow may contain child sub-workflows that are sequential or consensus. When a workflow uses a composed structure, primary names the top-level pattern and a composition_notes field describes the nesting.

The nine patterns are derived from agentic design pattern literature and the Synedrix OS architecture.

sequential

Definition: Tasks execute strictly in order. Each task must complete successfully before the next begins. Execution halts on failure unless the error policy specifies compensation.

When to use: Any workflow where task B depends on the output of task A, or where ordering is required for correctness — data enrichment pipelines, multi-step approvals, ordered write sequences.

Pattern-specific fields:

execution_pattern:
  primary: sequential
  steps:
    - step_id: step-1
      step_type: deterministic
      transform: schema-validate
      function_ref: n8n-nodes-base.set
    - step_id: step-2
      step_type: agent-driven
      agent_role: enrichment-agent
      task_class: enrich-record
      depends_on: [step-1]
    - step_id: step-3
      step_type: agent-driven
      agent_role: validator
      task_class: validate-enriched-record
      depends_on: [step-2]
    - step_id: step-4
      step_type: deterministic
      transform: publish-event
      function_ref: n8n-nodes-base.httpRequest
      depends_on: [step-3]
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1[step-1 schema-validate]:::term
  n2[step-2 enrichment-agent enrich-record]:::agent
  n3[step-3 validator validate-enriched-record]:::agent
  n4[step-4 publish-event]:::term
  n1 --> n2
  n2 --> n3
  n3 --> n4

This example shows a mixed sequential workflow: deterministic validation → agent enrichment → agent validation → deterministic event publish.

Source: Gulli, Agentic Design Patterns, Ch. 1 (Prompt Chaining — sequential decomposition into focused sub-tasks).

parallel

Definition: All tasks launch simultaneously. The workflow waits for every task to complete (or fail) before proceeding. No aggregation logic is required; tasks are fully independent.

When to use: Independent enrichment or analysis tasks that do not share state and whose outputs do not need to be voted on or merged before the next step — for example, parallel data-quality checks on independent data sources.

Pattern-specific fields:

execution_pattern:
  primary: parallel
  tasks:
    - step_type: agent-driven
      agent_role: data-quality-agent
      task_class: validate-ohlcv
    - step_type: agent-driven
      agent_role: data-quality-agent
      task_class: validate-sentiment
  wait_for: all          # all | first-success | first-completion
  timeout_ms: 2000
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1((parallel)):::term
  n2{wait for all timeout ms 2000}:::check
  n3[data-quality-agent validate-ohlcv]:::agent
  n1 --> n3
  n3 --> n2
  n4[data-quality-agent validate-sentiment]:::agent
  n1 --> n4
  n4 --> n2

Note: Parallel tasks are agent-driven. If you need a deterministic pre-processing or post-processing step around a parallel fan-out, model the workflow as sequential with a parallel child via composition_notes, or use hierarchical.

Source: Gulli, Agentic Design Patterns, Ch. 3 (Parallelization — concurrent independent tasks).

conditional

Definition: Execution follows one of N branches based on a condition evaluated at runtime — typically an agent decision, a policy result, or a field in the incoming payload. Exactly one branch executes per invocation.

When to use: Workflows that must route to different agent paths depending on risk tier, entity type, signal class, or approval outcome — for example, routing low-risk tasks directly to execution while routing high-risk tasks through HITL.

Pattern-specific fields:

execution_pattern:
  primary: conditional
  condition_source: policy-guard-output   # agent role or field path
  branches:
    - condition: allow
      next_step: execute-action
    - condition: escalate
      next_step: hitl-review
    - condition: block
      next_step: dead-letter
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1{policy-guard-output}:::check
  n2[execute-action]:::agent
  n1 -- allow --> n2
  n3[hitl-review]:::agent
  n1 -- escalate --> n3
  n4[dead-letter]:::agent
  n1 -- block --> n4

Source: Gulli, Agentic Design Patterns, Ch. 2 (Routing — LLM-based, embedding-based, rule-based, and ML-based routing mechanisms).

fan-out-fan-in

Definition: A single trigger fans out to N parallel sub-tasks. After all sub-tasks complete, an aggregation step merges their outputs before the workflow continues. Aggregation logic is explicit (merge, reduce, or select). Distinguished from parallel by the required aggregation step. Distinguished from consensus by the absence of voting quorum semantics.

When to use: Workflows that need to collect outputs from multiple specialised agents and combine them — for example, enriching a record with outputs from three independent analysis agents before persisting the enriched result.

Pattern-specific fields:

execution_pattern:
  primary: fan-out-fan-in
  fan_out:
    tasks:
      - step_type: agent-driven
        agent_role: risk-analyser
        task_class: analyse-risk
      - step_type: agent-driven
        agent_role: compliance-checker
        task_class: check-compliance
      - step_type: agent-driven
        agent_role: pricing-agent
        task_class: price-asset
    timeout_ms: 3000
    on_partial_failure: proceed-with-available  # proceed-with-available | abort
  fan_in:
    aggregation: merge-all   # merge-all | first-wins | custom-reducer-ref
    aggregator_agent_role: synthesis-agent
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1((fan out timeout ms 3000)):::term
  n2{fan in}:::check
  n3[synthesis-agent aggregation merge-all]:::agent
  n4[risk-analyser analyse-risk]:::agent
  n1 --> n4
  n4 --> n2
  n5[compliance-checker check-compliance]:::agent
  n1 --> n5
  n5 --> n2
  n6[pricing-agent price-asset]:::agent
  n1 --> n6
  n6 --> n2
  n2 --> n3
  n7([proceed-with-available]):::warn
  n2 -. on partial failure .-> n7

Source: Gulli, Agentic Design Patterns, Ch. 3 (Parallelization — concurrent tasks with sequential synthesis step) + Ch. 7 (Multi-Agent — parallel fan-out with aggregation).

iterative

Definition: A task or task set repeats in a loop until a convergence condition is satisfied or a maximum iteration count is reached. Each iteration may refine, extend, or evaluate the result of the previous one.

When to use: Workflows driven by the ReAct (Reason + Act + Observe) loop — where an agent acts, observes the result, and decides whether to act again. Also appropriate for any workflow that polls an external state until a condition is met (for example, waiting for an async job to complete).

Pattern-specific fields:

execution_pattern:
  primary: iterative
  max_iterations: 10
  convergence_condition: "output.confidence >= 0.85 OR output.status == 'complete'"
  loop_agent_role: react-agent
  task_class: reason-act-observe
  on_max_iterations_exceeded: escalate   # escalate | accept-last | abort
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1[react-agent reason-act-observe]:::agent
  n2{convergence condition max iterations 10}:::check
  n1 --> n2
  n2 -.-> n1
  n3([escalate]):::warn
  n2 -. on max iterations exceeded .-> n3

Source: Gulli, Agentic Design Patterns, Ch. 17 (ReAct — iterative loop).

consensus

Definition: Multiple agents independently evaluate the same input. A quorum rule (e.g., 4-of-7) must be satisfied within a timeout window before the workflow continues. If quorum is not met, the workflow aborts or escalates. A specialisation of fan-out-fan-in with explicit quorum semantics; the aggregation step is a voting function, not a merge.

When to use: Workflows where no single agent’s judgment should be trusted alone — multi-agent signal validation, collective risk assessment, distributed approval voting. Provides fault tolerance: minority agent failures do not block execution as long as quorum is preserved.

Pattern-specific fields:

execution_pattern:
  primary: consensus
  voters:
    - step_type: agent-driven
      agent_role: strategy-agent-1
    - step_type: agent-driven
      agent_role: strategy-agent-2
    - step_type: agent-driven
      agent_role: strategy-agent-3
    - step_type: agent-driven
      agent_role: strategy-agent-4
    - step_type: agent-driven
      agent_role: strategy-agent-5
  quorum:
    required: 3          # minimum votes needed to proceed
    of_total: 5
  timeout_ms: 500
  voting_function: majority   # majority | weighted | unanimous
  on_quorum_failure: abort    # abort | escalate | accept-plurality
  conflict_resolution: silo-enforcement   # majority | silo-enforcement | escalate
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1{quorum required 3 of total 5 voting function majority}:::check
  n2[strategy-agent-1]:::agent
  n2 --> n1
  n3[strategy-agent-2]:::agent
  n3 --> n1
  n4[strategy-agent-3]:::agent
  n4 --> n1
  n5[strategy-agent-4]:::agent
  n5 --> n1
  n6[strategy-agent-5]:::agent
  n6 --> n1
  n7[silo-enforcement]:::term
  n1 -- conflict resolution --> n7
  n8([abort]):::warn
  n1 -. on quorum failure .-> n8

Source: Gulli, Agentic Design Patterns, Ch. 7 (Multi-Agent Orchestration — consensus); Bellemare, Building Event-Driven Microservices, Ch. 10.

hierarchical

Definition: The parent workflow delegates to one or more named sub-workflows. Sub-workflows are full workflow contracts in their own right. The parent proceeds only after the declared sub-workflows complete. Sub-workflow execution may itself be sequential, parallel, or any other pattern.

When to use: Complex goals that must be decomposed across multiple bounded workflows — for example, an onboarding workflow that delegates to a KYC sub-workflow, a provisioning sub-workflow, and a notification sub-workflow. Also the correct pattern when a workflow spans multiple domain packs.

Pattern-specific fields:

execution_pattern:
  primary: hierarchical
  sub_workflows:
    - workflow_id: WF-COM-002-KYC-CHECK
      phase: pre-execution
      wait_for: completion
    - workflow_id: WF-COM-003-ACCOUNT-PROVISION
      phase: execution
      wait_for: completion
      depends_on: [WF-COM-002-KYC-CHECK]
    - workflow_id: WF-COM-004-WELCOME-NOTIFICATION
      phase: post-execution
      wait_for: none       # fire-and-forget
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1((hierarchical)):::term
  subgraph pre-execution
    n2[WF-COM-002-KYC-CHECK wait for completion]:::agent
  end
  subgraph execution
    n3[WF-COM-003-ACCOUNT-PROVISION wait for completion]:::agent
  end
  subgraph post-execution
    n4[WF-COM-004-WELCOME-NOTIFICATION wait for none]:::agent
  end
  n1 --> n2
  n2 --> n3
  n3 --> n4

The parent and its sub-workflows, as in the example above:

flowchart LR
    P["Parent workflow: hierarchical"]
    K["WF-COM-002-KYC-CHECK: pre-execution"]
    A["WF-COM-003-ACCOUNT-PROVISION: execution"]
    W["WF-COM-004-WELCOME-NOTIFICATION: post-execution"]
    P --> K
    K -->|"depends_on, wait for completion"| A
    A -.->|"post-execution, fire-and-forget"| W

Source: Gulli, Agentic Design Patterns, Ch. 6 (Plan-and-Execute — hierarchical decomposition).

pipeline

Definition: A strict left-to-right data-flow chain. Each step’s structured output is the next step’s input. No branching, no aggregation, no loops. Optimised for throughput and low-latency data transformation. Conceptually similar to sequential but semantically distinct: pipeline emphasises data flow and transformation, where each step is a pure transform on its input rather than a stateful task with side effects.

When to use: Signal processing chains, data transformation and normalisation pipelines, enrichment chains where each step augments a record and passes it forward. Appropriate when steps are lightweight, stateless, or near-deterministic.

Pattern-specific fields:

execution_pattern:
  primary: pipeline
  steps:
    - step_id: ingest
      step_type: deterministic
      transform: schema-normalise
      function_ref: n8n-nodes-base.set
    - step_id: enrich
      step_type: agent-driven
      agent_role: enrichment-agent
      task_class: add-regime-context
    - step_id: validate
      step_type: deterministic
      transform: schema-validate
    - step_id: emit
      step_type: deterministic
      transform: publish-event
      function_ref: n8n-nodes-base.httpRequest
  streaming: false   # true enables step-level streaming before full pipeline completes
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1[ingest schema-normalise]:::term
  n2[enrich enrichment-agent add-regime-context]:::agent
  n3[validate schema-validate]:::term
  n4[emit publish-event]:::term
  n1 --> n2
  n2 --> n3
  n3 --> n4

Note: agent_role: null on a pipeline step is a supported shorthand for step_type: deterministic. When both are present, step_type takes precedence. New workflow contracts should use step_type: deterministic explicitly.

Source: Gulli, Agentic Design Patterns, Ch. 1 (Prompt Chaining — Gulli explicitly names this the “Pipeline pattern”; introduces deterministic processing logic between LLM steps); Kleppmann, Designing Data-Intensive Applications, Ch. 11 (stream processing semantics); Bellemare, Building Event-Driven Microservices, Ch. 4.

reflect-and-revise

Definition: An agent produces a candidate output. A critic agent (or the same agent in a self-critique role) evaluates the output against a quality threshold. If the threshold is not met, the producer revises and the critic re-evaluates. The loop continues until the threshold is met or max_iterations is exhausted. The key distinction from iterative is the explicit producer/critic role split and quality-threshold convergence criterion.

When to use: Workflows where output quality must be enforced before the result is accepted — content generation, risk narrative synthesis, code generation, plan evaluation. Appropriate when a single LLM pass is insufficient and structured self-improvement is required.

Pattern-specific fields:

execution_pattern:
  primary: reflect-and-revise
  producer_agent_role: generator-agent
  critic_agent_role: evaluator-agent    # may be same agent_id as producer (self-critique)
  quality_threshold:
    metric: confidence_score
    minimum: 0.85
  max_iterations: 5
  on_threshold_not_met: escalate   # escalate | accept-last | abort
  critique_output_field: critique_notes  # field passed back to producer on each revision
Illustrative example, not a production implementation. Review and test before use.
flowchart LR
  n1[generator-agent]:::agent
  n2[evaluator-agent]:::agent
  n3{quality threshold confidence score minimum 0.85 max iterations 5}:::check
  n1 --> n2
  n2 --> n3
  n3 -. critique notes .-> n1
  n4([escalate]):::warn
  n3 -. on threshold not met .-> n4

Source: Gulli, Agentic Design Patterns, Ch. 4 (Reflection / Critique).

Composition rules

  1. Declare the primary pattern. Every workflow contract must declare exactly one execution_pattern.primary value.
  2. Composed workflows declare nesting. If the workflow uses multiple patterns (for example, a hierarchical parent with consensus children), the composition_notes field describes the nesting. Each child sub-workflow declares its own execution_pattern independently.
  3. Deterministic steps are valid in sequential and pipeline patterns. Steps with step_type: deterministic may appear in any position within sequential and pipeline pattern step arrays. In all other patterns (parallel, conditional, fan-out-fan-in, iterative, consensus, hierarchical, reflect-and-revise), every task node must be agent-driven. If a workflow using these patterns requires deterministic pre- or post-processing, model the deterministic chain as a separate stage with composition_notes, or wrap it in a sequential parent.
  4. Quorum and convergence conditions are mandatory for their patterns. A consensus workflow without quorum.required is invalid. An iterative workflow without max_iterations is invalid.
  5. execution_pattern is observable. Every workflow invocation record must log the declared primary pattern and any pattern-specific parameters used at runtime (quorum achieved, iterations used, branch taken, sub-workflow completions). These fields are required in observability_signals.

Workflow classes

Workflow classDescription
OperationalDeterministic workflows for fulfillment, reconciliation, onboarding, support
Decision-supportProduce recommendations, no high-impact writes directly
Approval-gatedRequire policy or HITL approval before external side effects
Asynchronous callbackSubmit-then-callback for external job completion
Monitoring and alertingDetection workflows emitting incidents, anomalies, or risk alerts

Contract rules

  • Rule 1: No implicit side effects. Undeclared writes make the workflow non-compliant.
  • Rule 2: No free-form production outputs. Workflows feeding downstream automation must output structured payloads.
  • Rule 3: High-impact workflows require policy awareness. Financial transactions, price changes, refunds, supplier switches, and legal or financial messaging must declare explicit policy and approval sections.
  • Rule 4: Contracts are versioned artifacts.
  • Rule 5: Execution pattern must be declared. A workflow contract without execution_pattern.primary is incomplete. The orchestration layer cannot reason about sequencing without this declaration.
  • Rule 6: Every step must declare its type. Each step in a sequential or pipeline pattern must carry step_type: deterministic or step_type: agent-driven. A step with agent_role set and no step_type is implicitly agent-driven. A step with agent_role: null and no step_type is implicitly deterministic (pipeline shorthand). In new contracts, explicit step_type declaration is required — implicit inference is supported only for backwards compatibility with contracts written against v0.3.

Suggested workflow spec template 


# <Workflow Name>

- Workflow ID:
- Domain:
- Version:
- Purpose:
- Trigger:
- Input Contract:
- Validation Rules:
- Execution Pattern:
  - primary:                    # sequential | parallel | conditional | fan-out-fan-in | iterative | consensus | hierarchical | pipeline | reflect-and-revise
  - steps:                      # for sequential and pipeline patterns
    - step_id:
      step_type:                # deterministic | agent-driven
      # if deterministic:
      transform:
      function_ref:             # optional
      # if agent-driven:
      agent_role:
      task_class:
      depends_on: []
  - [other pattern-specific fields]   # quorum, max_iterations, branches, sub_workflows, etc.
- Agent Roles:                  # agent-driven steps only
- Tool Dependencies:
- Side Effects:
- Approval Requirements:
- Output Contract:
- Idempotency Strategy:
- Retry Policy:
- Error Policy:
- Observability Signals:
- Security Scope:
Illustrative example, not a production implementation. Review and test before use.

Initial reference implementations should cover both high-impact and operational patterns, selected by each onboarding domain pack. Typical first candidates include a high-impact approval-gated workflow, an operational deterministic workflow, and an asynchronous callback workflow.

Versioning

  • Version: 0.4
  • Supersedes: v0.3

Canonical Reference

Naming and Taxonomy

Events and Governance

  • Synedrix OS - Event Taxonomy Standard — Event standard; workflows emit events conforming to the shared envelope defined there.
  • Synedrix OS - Core Principles — Principles 4 (Governance before execution) and 8 (Event-driven execution) are the governing constraints for workflow design.
  • Synedrix OS Observability Metrics Spec — Observability metrics spec; defines response_finalized handling, the requires_observability_families metadata convention, and the response sampling pipeline that all user-visible workflows must participate in.

Output and Outcomes

  • Synedrix OS Outcome Spec — Canonical outcome envelope; output_contract.result_schema declares the domain-specific shape of outcome.result. The envelope governs status, errors, policy, escalation, quality, timing, and execution context fields shared across all workflows. Note: deterministic steps do not produce outcome envelopes — only agent-driven steps do.

Agent Specifications

Knowledge Base Sources

  • Gulli, Antonio. Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems. 2024 (424 pages, 21 chapters). — Primary source for all nine execution patterns:
    • Ch. 1 Prompt Chaining → pipeline, sequential (Gulli explicitly names Ch. 1 the “Pipeline pattern”)
    • Ch. 2 Routing → conditional (LLM-based, embedding-based, rule-based, ML-based routing)
    • Ch. 3 Parallelization → parallel, fan-out-fan-in
    • Ch. 4 Reflection → reflect-and-revise
    • Ch. 6 Planning → hierarchical (Plan-and-Execute decomposition)
    • Ch. 7 Multi-Agent → consensus, fan-out-fan-in (aggregation)
    • Ch. 17 Reasoning Techniques → iterative (ReAct loop)
  • Bellemare, Adam. Building Event-Driven Microservices. O’Reilly, 2020. — consensus choreography semantics (Ch. 10); pipeline event-driven semantics (Ch. 4).
  • Kleppmann, Martin. Designing Data-Intensive Applications. O’Reilly, 2017. — pipeline stream processing semantics (Ch. 11).

Domain Pack

Synedrix OS · May 2026