Workflow Definition Language

Declarative schema for composing commands and agents into phased workflows with gates, context detection, and aggregation

Format YAML + JSON SchemaExtension .workflow.yamlVersion 3.1.0Status DraftUpdated 2026-06-17

Overview

The Workflow Definition Language (WDL) is a YAML-based specification for defining multi-step orchestrations in the UluOps framework. Workflows compose commands and agents into sequential phases with gate conditions, score aggregation, and parallel execution.

text

ADL (Agent Definition)
     /   \
    /     \ referenced by
   /       \
  v         \
CDL (Command)  \
   \           /
    \         /
     v       v
WDL (Workflow Definition)  <-- YOU ARE HERE
       |
       | staged by
       v
PDL (Pipeline Definition)

Key Characteristics

Aspect	Description
Format	YAML with JSON Schema validation
Extension	`.workflow.yaml`
Scope	Multi-step orchestration with phase-based execution
Phases	Sequential execution with parallel commands within phases
Gates	Score-based pass/fail conditions between phases
Aggregation	Combine scores from multiple commands (min, max, mean, weighted)

Design Principles

💡

Tip

Runtime-Only Content — Every field in the YAML produces operational behavior in the runtime markdown. Documentation-only content belongs in external docs, not in the workflow definition.

💡

Tip

250-Line Runtime Target — Generated markdown commands should not exceed 250 lines. This constraint drives lean phase definitions and eliminates verbose guidance fields.

💡

Tip

Lean Phases — Phase definitions carry only what the runtime needs: identity, steps, gates, conditions, and focus areas. Guidance fields like threshold_rationale, decision_criteria, and capture_note are agent-level concerns.

💡

Tip

Step Orchestration — Workflows compose steps (commands or direct agent references) into phases. Each phase executes its steps in order, and phases themselves are ordered by dependencies and groups.

💡

Tip

Context-Driven Conditional Execution — Detectors evaluate project context (file existence, grep patterns, env vars) at workflow start. Phase conditions reference detector results to skip irrelevant phases.

💡

Tip

Gates Control Flow, Not Logic — Gates define score thresholds between phases. They control whether execution continues, warns, or stops -- but never modify the validation logic itself.

Workflow Concepts

WDL introduces three key orchestration concepts:

Sequential or parallel execution units containing steps (commands or agents)

Output

Phase Score + Findings

Decision Vocabulary

Gate-determined (PASS / WARN / FAIL)

Use Cases

Code validation gates
Security audit phases
Test quality checks
Conditional execution

Requires

idnamesteps

Score thresholds that control flow between phases

Output

Gate Decision (pass / warn / fail)

Decision Vocabulary

threshold + on_fail action

Use Cases

Quality gates between phases
Score-based flow control
Warning thresholds
Abort on critical failures

Requires

threshold

Combine phase results into workflow-level scoring and decisions

Output

Workflow Score + Decision (SHIP / HOLD / BLOCK)

Decision Vocabulary

Configurable (SHIP/HOLD/BLOCK or PASS/WARN/FAIL)

Use Cases

Weighted scoring across phases
Ship/hold/block decisions
Decision expression evaluation
Skip missing phase handling

Requires

Schema Structure

Common Schema

The core workflow structure with interface, phases, and orchestration:

yaml

workflow:
  interface:           # Required: Identity and classification
    name: string
    version: string
    displayName: string
    description: string
    domain: string
    duration: string?
    model: haiku | sonnet | opus

  arguments:           # Optional: CLI argument definitions
    positional: PositionalArg[]
    flags: FlagDef[]
    derived: DerivedVar[]
    examples: UsageExample[]    # max 3

  context:             # Optional: Context detection
    detectors: Detector[]
    variables: ContextVariable[]

  orchestration:       # Required: Phase orchestration
    phases: Phase[]
    execution_mode: ExecutionMode?
    on_failure: stop | continue | abort
    max_parallel: integer
    timeout: integer

  aggregation:         # Optional: Workflow-level scoring
    score: { method, weights, skip_missing }
    decision: { SHIP: expr, HOLD: expr, BLOCK: expr }

  outputs:             # Optional: Artifacts and tracking
    artifacts: Artifact[]
    variables: OutputVariable[]
    verification: { post_save: VerifyCheck[] }
    tracking: { enabled, provider, payload }

  preflight:           # Optional: Pre-execution checks
    checks: PreflightCheck[]
    extraction: PreflightExtraction[]

  postflight:          # Optional: Decision-based actions
    on_ship: { message, exit_code, commands }
    on_hold: { message, exit_code, commands }
    on_block: { message, exit_code, commands }

Phase Configuration

How phases organize commands with parallel execution and dependencies:

yaml

phases:
  - id: validate              # Required: kebab-case identifier
    name: Code Validation      # Required: display name
    type: validate             # validate | execute | mixed
    group: 1                   # Parallel group number
    barrier: true              # Must complete before next group

    steps:                     # command or agent refs
      - command: validate@>=1.0.0
      - agent: code-auditor@1.0.0

    depends_on: [preflight]    # Phase dependencies
    condition: context.has_src  # Run condition
    skip_if: args.dry_run      # Skip condition

    gate:                      # Score gate
      threshold: 70
      warn_threshold: 85
      aggregate: min
      on_fail: stop
      on_warn: warn

    focus:                     # Key areas (max 5)
      - Correctness
      - Error handling

Gate Configuration

Score-based conditions that determine whether to proceed:

yaml

gate:
  threshold: 70              # Score >= 70 to pass
  warn_threshold: 85         # Score 70-84 = warning
  aggregate: min             # min | max | average | weighted_average | all | any
  on_fail: stop              # stop | warn | skip | abort
  on_warn: warn              # Action on warning range

# Gate behavior:
#   score >= warn_threshold  ->  PASS (continue)
#   score >= threshold       ->  WARN (on_warn action)
#   score < threshold        ->  FAIL (on_fail action)

Runtime Flow

text

1. PREFLIGHT       -- Run checks, extract metadata
2. DETECT           -- Evaluate context detectors (file_exists, grep, etc.)
3. RESOLVE          -- Resolve phase dependencies and execution order
4. EXECUTE PHASES   -- Run phases in dependency/group order
   4a. Check condition/skip_if
   4b. Execute steps (commands or agents)
   4c. Evaluate gate threshold
   4d. Apply on_fail/on_warn action
5. AGGREGATE        -- Combine phase scores via configured method
6. DECIDE           -- Map aggregate score to decision (SHIP/HOLD/BLOCK)
7. VERIFY           -- Run post_save verification checks
8. POSTFLIGHT       -- Execute decision-specific handlers

Field Reference

Interface Block

Identifies the workflow. Consistent with ADL and CDL interface pattern.

Field	Type	Required	Description
`name`	`string`	Yes	Kebab-case identifier. Pattern: ^[a-z][a-z0-9](-[a-z0-9]+)$
`version`	`string`	Yes	Semantic version. Pattern: ^\d+\.\d+\.\d+$
`displayName`	`string`	Yes	Human-readable name for UI display (3-50 chars)
`description`	`string`	Yes	When to use + what it does + what phases it runs (20-500 chars)
`domain`	`enum`	Yes	Primary domain (software, security, legal, etc.)
`duration`	`string`	No	Expected duration for the workflow
`model`	`enum`	No	Default LLM model tier: haiku, sonnet, or opus (default: sonnet)
`tags`	`string[]`	No	Searchable tags for discovery (kebab-case, unique). Restored in v3.1.0 for parity with ADL/CDL/PDL.

Arguments Block

Named parameters that configure workflow behavior at invocation time.

Field	Type	Required	Description
`positional`	`PositionalArg[]`	No	Positional arguments in order (name, description, required, default)
`flags`	`FlagDef[]`	No	Named flags (--flag or -f) with type (boolean, string, number, array)
`derived`	`DerivedVar[]`	No	Variables computed from other arguments (e.g., basename(arguments.target))
`examples`	`UsageExample[]`	No	Usage examples showing command invocations and behavior (max 3)

Context Block

Shared context available to all commands within the workflow.

Field	Type	Required	Description
`detectors`	`Detector[]`	No	Context detectors that evaluate to true/false at workflow start
`variables`	`ContextVariable[]`	No	Derived variables computed from detector results

Orchestration Block

Top-level execution configuration — model defaults, timeout, concurrency.

Field	Type	Required	Description
`phases`	`Phase[]`	Yes	List of phases to execute (minItems: 1)
`execution_mode`	`ExecutionMode`	No	User-selectable execution strategy (sequential or parallel)
`on_failure`	`enum`	No	Global failure behavior: stop, continue, or abort (default: stop)
`max_parallel`	`integer`	No	Maximum phases to run in parallel (1-10, default: 1)
`timeout`	`integer`	No	Workflow timeout in milliseconds (max 1 hour)

Phase Block

Phase configuration within the phases array.

Field	Type	Required	Description
`id`	`string`	Yes	Phase identifier (kebab-case)
`name`	`string`	Yes	Human-readable phase name (3-50 chars)
`steps`	`StepRef[]`	Yes	Steps to execute: each is { command: ref } or { agent: ref }
`type`	`enum`	No	Phase type: validate, execute, or mixed (default: validate)
`group`	`integer`	No	Parallel execution group (1-based). Phases in same group can run in parallel.
`barrier`	`boolean`	No	If true, must complete before subsequent groups start (default: false)
`depends_on`	`string[]`	No	Phase IDs that must complete before this phase
`condition`	`string`	No	Expression that must be true for phase to run (e.g., context.typescript_detected)
`skip_if`	`string`	No	Expression that skips this phase if true
`gate`	`Gate`	No	Gate configuration controlling flow to next phase
`inputs`	`object`	No	Input mappings for execute phases (source expressions)
`timeout`	`integer`	No	Phase timeout in milliseconds (max 30 minutes)
`focus`	`string[]`	No	Key areas this phase focuses on (max 5 items)

Gate Block

Gate conditions applied at phase boundaries.

Field	Type	Required	Description
`threshold`	`integer`	No	Score threshold for gate to pass (0-100)
`warn_threshold`	`integer`	No	Score threshold for warning (must be > threshold)
`aggregate`	`enum`	No	How to combine scores: min, max, average, weighted_average, all, any (default: min)
`on_fail`	`enum`	No	Action when gate fails: stop, warn, skip, abort (default: stop)
`on_warn`	`enum`	No	Action when gate passes with warnings: stop, warn, skip, abort

Aggregation Block

Score aggregation configuration for multi-command phases.

Field	Type	Required	Description
`score.method`	`enum`	No	Aggregation method: min, max, average, weighted_average, all, any
`score.weights`	`object`	No	Phase weights for weighted aggregation (must sum to 1.0)
`score.skip_missing`	`boolean`	No	Whether to skip skipped/disabled phases in calculation (default: true)
`decision`	`object`	No	Decision label-to-expression mapping (e.g., { SHIP: "score >= 85", HOLD: "score >= 70", BLOCK: "score < 70" })

Output Block

Workflow output configuration — artifacts, verification, and tracking.

Field	Type	Required	Description
`artifacts`	`Artifact[]`	No	Artifacts to generate (id, type, path, condition, content_template)
`variables`	`OutputVariable[]`	No	Output variables to expose (name, source expression)
`verification.post_save`	`VerifyCheck[]`	No	Post-save integrity verification checks
`tracking`	`TrackingConfig`	No	Integration with tracking systems (enabled, provider, payload)

Preflight Block

Actions executed before the workflow starts.

Field	Type	Required	Description
`checks`	`PreflightCheck[]`	No	Checks to run before workflow execution
`extraction`	`PreflightExtraction[]`	No	Pre-phase metadata gathering steps (frontmatter, command, json_field, yaml_field, regex)

Postflight Block

Actions executed after the workflow completes. Accepts custom decision keys (e.g., on_ship, on_hold) in addition to generic on_pass/on_warn/on_fail.

Field	Type	Required	Description
`on_ship`	`PostflightAction`	No	Actions when decision is SHIP (message, exit_code, commands)
`on_hold`	`PostflightAction`	No	Actions when decision is HOLD
`on_block`	`PostflightAction`	No	Actions when decision is BLOCK
`on_pass`	`PostflightAction`	No	Actions when decision is PASS (generic workflows)
`on_warn`	`PostflightAction`	No	Actions when decision is WARN (generic workflows)
`on_fail`	`PostflightAction`	No	Actions when decision is FAIL (generic workflows)

Migration from v2.0.0

Removed Blocks

Block	Migration
`handoffs`	Remove entirely. Agent data passing is implicit via phase ordering.
`iteration`	Remove entirely. Move to external docs if needed.
`troubleshooting`	Remove entirely. Move to external docs if needed.

Removed Fields

Location	Field	Migration
`interface`	`philosophy`	Remove
`interface`	`legend`	Remove
`interface`	`tags`	Remove
`interface`	`subdomain`	Remove
`interface`	`comparison`	Remove
`interface`	`operational`	Remove
`orchestration`	`diagram`	Remove
`phase`	`capture_note`	Remove; agents capture findings by default
`phase`	`if_failing`	Remove; agents have their own failure guidance
`phase`	`threshold_rationale`	Remove; docs concern
`phase`	`decision_criteria`	Remove; agent-level concern
`phase`	`auto_fail_conditions`	Remove; agent-level concern
`phase`	`skip_conditions`	Remove; use `condition` field instead
`phase`	`alternatives`	Remove; unused in practice
`phase`	`key_outputs`	Remove; never materialized
`phase`	`inline_checks`	Remove; rarely used
`aggregation`	`decision_table`	Remove; `decision` map sufficient
`outputs.verification`	`pre_save`	Remove; post_save only
`preflight`	`banner`	Remove; runtime generates status

Kept with Constraints

Field	Change
`arguments.examples`	Max 3 items (was unlimited)
`phase.focus`	Max 5 items (was unlimited)
`postflight.*.message`	Max 200 chars (was unlimited)

Composition Rules

ℹ

Note

Workflow requires interface and orchestration blocks — Every workflow must include the interface block (identity and classification) and the orchestration block (phase definitions). These are the two mandatory top-level sections.

ℹ

Note

Optional blocks: arguments, context, aggregation, outputs, preflight, postflight — All other top-level blocks are optional and can be included as needed. Handoffs, iteration, and troubleshooting blocks were removed in v3.0.0.

Revision History

Version	Date	Changes
3.1.0	2026-06-17	Additive: Restored interface.tags (kebab-case, unique) for discovery parity with ADL/CDL/PDL Backward compatible — existing tagless workflows still validate
3.0.0	2026-03-26	Breaking: Removed handoffs, iteration, troubleshooting blocks Removed 6 interface fields (subdomain, tags, philosophy, legend, comparison, operational) Removed diagram from orchestration Removed 8 phase fields (auto_fail_conditions, capture_note, if_failing, threshold_rationale, decision_criteria, skip_conditions, alternatives, key_outputs, inline_checks) Removed decision_table from aggregation; decision map is sufficient Removed pre_save from verification; post_save only Removed banner from preflight; runtime generates status Added maxItems constraints: examples (3), focus (5), message (200 chars) Design goal: runtime-only content, 250-line target, lean phases
2.0.0	2026-03-01	Added step references (command: or agent: in phases), replacing command-only phases Added inline_checks, key_outputs, alternatives, decision_criteria on phases Added comparison and operational guidance on interface Added preflightExtraction for metadata gathering Added handoffs and iteration blocks
1.2.0	2026-02-20	Added execution_mode with parallel_groups Added phase.focus, phase.capture_note, phase.if_failing, phase.threshold_rationale, phase.skip_conditions Added aggregation.report_template and decision_table
1.1.0	2026-02-08	Added phase.barrier for synchronization Added context.variables for derived context Added outputs.verification with pre_save/post_save checks Added phase.inputs for execute phase data mapping
1.0.2	2026-02-01	Added aggregation.score.skip_missing Added phase.auto_fail_conditions Added preflight.extraction for metadata gathering
1.0.1	2026-01-30	Added gate.warn_threshold for two-tier gate evaluation Added orchestration.timeout for workflow-level timeout Added outputs.tracking for provider integration
1.0.0	2026-01-28	Initial WDL specification Phase-based orchestration with gates, context detection, aggregation, and postflight decision handlers
0.3.0	2026-01-20	Added aggregation block with score methods and decision expressions Added postflight handlers for ship/hold/block decisions
0.2.0	2026-01-15	Added context detection with detectors and conditional phases Added gate configuration on phases
0.1.1	2026-01-13	Added preflight checks and banner template Added arguments block with positional args and flags
0.1.0	2026-01-11	Initial draft Basic workflow structure with interface, orchestration, and phases