Registry↗Dashboard↗

Pipeline Definition Language

A YAML-based specification for defining multi-workflow orchestrations with triggers, approvals, rollback, and external notifications.

Format YAML + JSON SchemaExtension .pipeline.yamlVersion 1.6.0Status DraftUpdated 2026-10-26

Overview

The Pipeline Definition Language (PDL) is a YAML-based specification for defining multi-workflow orchestrations in the UluOps validation framework. Pipelines compose workflows and commands into stages with explicit dependencies, triggers, approvals, rollback strategies, and external notifications.

PDL is the top-level orchestration layer in the UluOps definition hierarchy:

text
ADL (Agent Definition)
       │
       │ wrapped by
       ▼
CDL (Command Definition)
       │
       │ orchestrated by
       ▼
WDL (Workflow Definition)
       │
       │ staged by
       ▼
PDL (Pipeline Definition)  ◄── YOU ARE HERE

What Pipelines Do

CapabilityDescription
Stage orchestrationOrganize workflows/commands into stages with explicit dependencies
Event triggersExecute on git push, PR events, schedules, webhooks, or manually
Approval gatesRequire human authorization before critical stages
Environment managementVariables and secrets scoped to pipeline or stage
Failure recoveryAutomatic rollback strategies on deployment failures
External notificationsSlack, email, GitHub status, webhooks
Artifact preservationConfigurable retention policies for build outputs
Cross-run statePersist state across pipeline runs
Postflight trackerPersist results to validation tracker with token metrics

Pipeline vs Workflow

AspectWorkflow (WDL)Pipeline (PDL)
ContainsCommands in phasesWorkflows and/or commands in stages
TriggersNone (invoked by caller)Git events, webhooks, schedules, manual
ApprovalsNoneHuman gates before stages
RollbackNoneAutomatic failure recovery
NotificationsNoneExternal system integration
StatePer-run onlyPersisted across runs
PostflightDecision handlers (on_ship, etc.)Tracker persistence + conditional actions

Design Principles

💡
Tip
Stages Orchestrate Workflows, Commands and Agents — A stage references workflows, commands, agents, or inline steps. Workflows and commands are referenced by name@version; agents by their subagent_type identifier, with no CDL wrapper. (Until 1.6.0 this principle read "Workflow/Command Orchestration, Not Agent Orchestration", though PDL 1.2.0 had added agents as an execution primitive and most corpus stages use it; 1.6.0 withdrew it.)
💡
Tip
Event-Driven Execution — Pipelines define when they should run via triggers. Unlike workflows which are invoked programmatically, pipelines respond to external events (git push, PR, schedule, webhook, manual).
💡
Tip
Human-in-the-Loop Approvals — Critical stages can require human approval before execution. This enables safe deployment workflows with mandatory review checkpoints.
💡
Tip
Fail-Safe with Rollback — Pipelines can define automatic rollback strategies to recover from failures. This ensures production stability even when deployments fail.
💡
Tip
Declarative Stage Dependencies — Stages declare explicit dependencies, each on a stage declared earlier. Independent stages may run in parallel (the pdl-executor skill does; core runs them in array order), with the same statuses either way.
💡
Tip
Consistent Interface Pattern — Pipelines use the same interface block structure as Agents (ADL), Commands (CDL), and Workflows (WDL) for consistency across the definition language family.

Schema Structure

CI/CD Pipeline

A complete CI/CD pipeline with validation, staging, production deployment, rollback, and postflight tracker integration:

yaml
pipeline:
  interface:
    name: release-pipeline
    version: 1.0.0
    displayName: Release Pipeline
    description: Complete CI/CD pipeline from validation to deployment
    domain: software
    subdomain: ci-cd
    tags: [release, ci-cd, deployment]

  triggers:
    - type: git_push
      branches: [main, master]
      paths:
        include: ["src/**", "package.json"]
        exclude: ["**/*.md", "docs/**"]
    - type: manual
      allowed: true
      parameters:
        - name: environment
          type: string
          options: [staging, production]
          default: staging

  environment:
    variables:
      - name: NODE_ENV
        value: "production"
    secrets:
      - name: DEPLOY_KEY
        required: true
        stages: [deploy-staging, deploy-prod]

  stages:
    - id: preflight
      name: Pre-Flight Checks
      parallel: true
      steps:
        - name: Install dependencies
          command: npm ci
      gate:
        on_failure: abort

    - id: validate
      name: Core Validation
      depends_on: [preflight]
      workflows:
        - ref: ship@>=1.0.0
          args:
            target: "."
      gate:
        threshold: 70
        on_failure: abort

    - id: deploy-staging
      name: Deploy to Staging
      depends_on: [validate]
      steps:
        - name: Deploy
          command: npm run deploy:staging

    - id: deploy-prod
      name: Deploy to Production
      depends_on: [deploy-staging]
      approval:
        required: true
        approvers: ["@release-team"]
        timeout_hours: 24
      steps:
        - name: Deploy
          command: npm run deploy:prod

  rollback:
    enabled: true
    strategy: revert_to_last_success
    triggers:
      - condition: "stages.deploy-prod.failed"
        action: rollback_production

  notifications:
    channels:
      - type: slack
        webhook: "{{ secrets.SLACK_WEBHOOK }}"
        events: [started, success, failure, rollback]
      - type: github_status
        enabled: true

  postflight:
    tracker:
      enabled: true
      project: "{{ pipeline.interface.name }}"
      include_token_metrics: true
    on_success:
      - description: Notify release channel
        command: echo "Release pipeline succeeded"
    on_failure:
      - description: Alert on-call
        command: echo "Release pipeline failed"

Multi-Workflow Orchestration

A simpler pipeline that orchestrates multiple validation workflows:

yaml
pipeline:
  interface:
    name: full-validation
    version: 1.0.0
    displayName: Full Validation Pipeline
    description: Comprehensive validation running multiple specialized workflows
    domain: software

  triggers:
    - type: pull_request
      actions: [opened, synchronize]
    - type: manual
      allowed: true

  stages:
    - id: pre-implementation
      name: Pre-Implementation Review
      workflows:
        - ref: pre-implementation@>=1.0.0
          args:
            target: "."
      gate:
        threshold: 70
        on_failure: warn

    - id: post-implementation
      name: Post-Implementation Validation
      depends_on: [pre-implementation]
      workflows:
        - ref: post-implementation@>=1.0.0
          args:
            target: "."
      gate:
        threshold: 75
        on_failure: abort

    - id: ship-gate
      name: Ship Readiness Gate
      depends_on: [post-implementation]
      workflows:
        - ref: ship@>=1.0.0
          args:
            target: "."
            strict: true
      gate:
        threshold: 80
        on_failure: abort

Hybrid Pipeline (Workflows + Commands)

A pipeline that mixes workflows with direct command invocations:

yaml
pipeline:
  interface:
    name: audit-and-fix
    version: 1.0.0
    displayName: Audit and Fix Pipeline
    description: Run validation audit then attempt automatic fixes
    domain: software

  triggers:
    - type: schedule
      cron: "0 3 * * *"
    - type: manual
      allowed: true
      parameters:
        - name: auto_fix
          type: boolean
          default: true

  stages:
    - id: audit
      name: Full Audit
      workflows:
        - ref: ship@>=1.0.0
          args:
            target: "."
      gate:
        threshold: 90               # passed = scored 90 or more
        on_failure: warn

    - id: auto-fix
      name: Automatic Fixes
      depends_on: [audit]
      condition: "params.auto_fix && !stages.audit.passed"
      commands:
        - ref: lint-fix@>=1.0.0
          args:
            target: "."
        - ref: type-fix@>=1.0.0
          condition: "context.typescript_detected"
      sequential: true

    - id: verify
      name: Verify Fixes
      depends_on: [auto-fix]
      condition: "stages.auto-fix.passed"
      workflows:
        - ref: ship@>=1.0.0
          args:
            target: "."
      gate:
        threshold: 80
        on_failure: warn

Field Reference

Interface Block

The interface block identifies the pipeline and is consistent with ADL, CDL, and WDL.

FieldTypeRequiredDescription
namestringYesKebab-case identifier. Pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
versionstringYesSemantic version. Pattern: ^\d+\.\d+\.\d+$
displayNamestringYesHuman-readable name (3-50 characters)
descriptionstringYesPipeline purpose and scope (20-500 characters)
domainDomainYesPrimary domain classification
subdomainstringNoDomain refinement (kebab-case)
tagsstring[]NoSearchable discovery tags

Triggers Block

Triggers define when the pipeline executes. Six trigger types are supported.

FieldTypeRequiredDescription
typeenumYesTrigger type: git_push, pull_request, schedule, webhook, manual, pipeline
branchesstring[]NoBranch patterns (glob supported). For git_push and pull_request triggers
tagsstring[]NoTag patterns. For git_push trigger
pathsobjectNoFile path filters with include/exclude arrays (glob patterns)
actionsstring[]NoPR actions: opened, synchronize, reopened, closed, labeled, etc.
cronstringNoCron expression for schedule trigger
timezonestringNoTimezone for schedule (default: UTC)
eventstringNoEvent name for webhook trigger
secretstringNoHMAC verification secret for webhook
allowedbooleanNoEnable manual triggering
parametersParameter[]NoInput parameters for manual trigger (name, type, options, default)

Trigger Types:

TypeDescriptionKey Fields
git_pushTriggered on push to branchbranches, tags, paths
pull_requestTriggered on PR eventsactions, branches, paths
scheduleCron-based schedulingcron, timezone
webhookExternal HTTP webhookevent, secret, payload_filter
manualManual invocationallowed, parameters
pipelineTriggered by another pipelinepipeline, condition

Environment Block

Environment variables and secrets for the pipeline.

FieldTypeRequiredDescription
variablesVariable[]NoEnvironment variables with name, value, and optional stage scoping
secretsSecret[]NoSecret references with name, required flag, stage scoping, and provider config

Stages Block

Stages are the primary execution units in a pipeline. Since 1.6.0, stage, gate and agentRef are closed: any key not listed is a load error (unknown_key). skip_if is not a stage key; write a condition.

FieldTypeRequiredDescription
idstringYesUnique stage identifier (kebab-case)
namestringYesHuman-readable stage name
descriptionstringNoWhat the stage does and what its gate decides (1.6.0)
depends_onstring[]NoStages that must reach a terminal status first, whatever it is; each must be declared earlier (a forward reference is a load error). Empty = root stage
conditionstringNoRun condition in the 1.6.0 condition language, at most 512 code points: params.<name>, stages.<id>.passed, stages.<id>.steps['<name>'].output, compared with == / != against a string, combined with !, &&, || and parentheses. False skips the stage
forwardenumNoWhat the stage's results forward to its dependents: auto (default), none, full (1.6.0)
receivesenumNoWhether the stage's agents receive forwarded results: auto (default), none (1.6.0)
timeoutnumberNoTimeout in milliseconds
parallelbooleanNoRun items in parallel (default: false)
workflowsWorkflowRef[]NoWorkflow references with ref, args, condition, timeout
commandsCommandRef[]NoCommand references with ref, args, condition, timeout
agentsAgentRef[]NoDirect agent references by subagent_type identifier (ref, model, args, threshold, condition, timeout)
stepsStep[]NoInline shell steps with name, command, env, retries
sequentialbooleanNoForce sequential execution of items
gateGateNoPass/fail gate with threshold, aggregate, decision, on_failure (see Gate)
artifactsArtifact[]NoStage-specific artifact preservation
approvalApprovalNoHuman approval requirement for this stage
envRecordNoStage-specific environment overrides
inputsobjectNoInput parameters from dependency stage outputs
outputsOutput[]NoStage outputs (name, value or command expression)
artifacts_fromstring[]NoImport artifacts from other stages by stage ID

Agent Reference

FieldTypeRequiredDescription
refstringYesAgent subagent_type identifier (kebab-case, no version)
modelstringNoModel alias override: sonnet, opus, or haiku
argsobjectNoArguments passed to the agent
thresholdintegerNoPer-agent score threshold, 0-100 (1.6.0). Any agent declaring one puts the stage gate in per-agent mode: each agent must reach its own threshold, falling back to gate.threshold; gate.aggregate is then a load error, and so is an agent with neither
conditionstringNoRun condition in the condition language; false skips the agent. One that reads a step that did not pass makes the agent ERRORED
timeoutnumberNoAgent timeout in milliseconds (minimum 1000). An agent that does not return in time is unjudgeable and its stage ends ERRORED

Gate

FieldTypeRequiredDescription
thresholdintegerNoAggregate mode: aggregate(scores) must reach it. Per-agent mode: the fallback for agents without their own threshold. Absent in aggregate mode: the gate is decision-only
aggregateenumNoHow scores combine in aggregate mode: min (default), max, average. A load error in per-agent mode
decisionenumNoHow each agent's decision class is compared (1.6.0): not_negative (a negative fails; a conditional passes, and at a blocking gate all_gates_passed becomes false), positive (only a positive passes), ignore. Default: not_negative on blocking gates, ignore on warn. A neutral or absent decision never fails a gate; the score decides
on_failureenumNoabort (default): the stage FAILS and its transitive dependents are skipped, every other stage still runs; fail (1.6.0): FAILS and the run continues; warn: WARNED, continues; skip: deprecated alias of fail
on_successenumNocontinue (default) or skip_remaining; skip_remaining is not specified by the 1.6.0 execution semantics

Convergence Block

Pipeline-level, optional (PDL 1.3.0+). Turns the one-pass stage DAG into an iterative fix loop: the listed loop_stages re-execute until the convergence gate is satisfied or max_iterations is reached; stages not listed run exactly once after the loop exits.

The gate is one of two kinds (schema-enforced mutually exclusive). A score gate (threshold + aggregate) exits when the aggregated raw agent score meets the threshold. Since 1.5.0, a decision gate (gate.satisfied_by, a set of completion Decision tokens such as [DRAINED]) exits when the gate stage's Decision is one of them — for loops whose gate stage is a decision-only executor (e.g. issue-remediation, gated on the batcher reporting DRAINED). A decision-only loop carries no numeric score: it is headlined by convergence.decision, and a loop that updates issue lifecycle in place submits no postflight recommendations.

The gate is evaluated immediately after the gate stages complete within an iteration — a converging run exits on a fresh post-fix score and never runs an investigate/fix cycle it doesn't need. Reaching max_iterations without converging is a first-class UNCONVERGED outcome, not an error.

Since 1.4.0 the loop also stall-exits: after stall_iterations consecutive iterations applying zero mechanical fixes (default 2), the score provably cannot move by the loop's own mechanism, so it exits UNCONVERGED with exit_reason: stalled instead of burning the remaining budget — a success of triage, handing the contextual/human-gated residue over. And loop-stage agent prompts carry a tracker no-save contract (tracker.suppress_agent_saves, default true): postflight is the single owner of run persistence, with an executor exception for issue-level updates on pre-existing issues.

FieldTypeRequiredDescription
loop_stagesstring[]YesStage IDs re-executed each iteration, in dependency order. Stages not listed run exactly once after the loop exits (post-loop stages)
gate.stagesstring[]YesStage IDs whose agent scores feed the convergence score. Must be a subset of loop_stages; must not declare a condition. Evaluated immediately after these stages complete — a converging run exits on a fresh score
gate.aggregateenumNoHow raw agent scores across the gate stages combine: min, max, average (default: average). Independent of stage-level gate aggregates
gate.thresholdnumberNoScore gate. Convergence score threshold (0-100). The loop exits when the aggregated score meets or exceeds this value and min_iterations is satisfied. Mutually exclusive with gate.satisfied_by — exactly one of the two is required (since PDL 1.5.0)
gate.satisfied_bystring[]NoDecision gate (PDL 1.5.0). Completion Decision tokens that converge the loop (uppercase, e.g. [DRAINED]). The gate stage must be a single decision-only executor emitting a Decision, not a score. Mutually exclusive with threshold/aggregate. A decision-gated loop of decision-only agents carries no score — headlined by convergence.decision, not average_score
max_iterationsnumberYesHard iteration cap (1-20). Reaching it without convergence triggers on_max_iterations
min_iterationsnumberNoIterations that must complete before the gate can exit the loop (default: 1)
on_max_iterationsenumNowarn: loop stages exit WARNED and the run decision is UNCONVERGED, post-loop stages still run (default); abort: fail the pipeline
stall_iterationsnumberNoExit the loop early after this many consecutive iterations applying zero mechanical fixes (1-10, default: 2) — the score cannot move without fixes, so remaining iterations are triage residue. Counter resets on any applied fix
on_stallenumNowarn: proceed to post-loop stages as UNCONVERGED with exit_reason stalled (default); abort: fail the pipeline
tracker.suppress_agent_savesbooleanNoInject a no-save contract into every loop-stage agent prompt — postflight is the single owner of run persistence, preventing orphaned sub-run rows (default: true)
tracker.allow_executor_issue_updatesbooleanNoExecutor exception: issue-level updates (update_status, add_issue_note) on pre-existing tracker issues its fixes resolve remain allowed (default: true)
carry_contextbooleanNoPass prior-iteration context (score trajectory, investigator classifications, executor fix summary) into each loop-stage agent prompt under a "Prior Iteration Context" heading (default: true)

Approvals Block

Human approval requirements for stages.

FieldTypeRequiredDescription
requiredbooleanNoWhether approval is required (default: false)
approversstring[]NoList of approvers (team mentions, emails, platform-specific)
min_approvalsnumberNoMinimum approvals needed (default: 1)
timeout_hoursnumberNoHours before auto-reject (default: 72)
auto_reject_on_changebooleanNoReject if source code changes (default: true)
allow_self_approvalbooleanNoAllow triggerer to approve (default: false)
notificationNotificationNoApproval request notification configuration

Approval Timeout Behavior:

BehaviorDescription
rejectAuto-reject after timeout (default)
approveAuto-approve after timeout
extendNotify and extend timeout
pausePause pipeline indefinitely

Rollback Block

Automatic failure recovery configuration.

FieldTypeRequiredDescription
enabledbooleanNoEnable automatic rollback (default: false)
strategyenumNoRollback strategy: revert_to_last_success, revert_to_previous, custom, none
triggersRollbackTrigger[]NoConditions that trigger rollback (condition + action pairs)
actionsRecord<string, Action>NoNamed rollback actions with steps
preserve_logsbooleanNoPreserve logs on rollback (default: true)
notify_on_rollbackbooleanNoSend notification on rollback
max_rollback_attemptsnumberNoMaximum rollback retry count

Rollback Strategies:

StrategyDescription
revert_to_last_successRestore last successful deployment
revert_to_previousRestore immediate previous state
customExecute custom rollback actions
noneNo automatic rollback

Notifications Block

External system notification configuration.

FieldTypeRequiredDescription
channelsChannel[]NoNotification channels: slack, email, github_status, webhook, pagerduty, teams
templatesRecord<string, string>NoMessage templates for events (started, success, failure, rollback)
rate_limitobjectNoRate limiting with max_per_hour and deduplicate options

Channel Types:

TypeDescription
slackSlack webhook notifications
emailEmail notifications
github_statusGitHub commit status checks
webhookGeneric HTTP webhook
pagerdutyPagerDuty incident creation
teamsMicrosoft Teams notifications

Notification Events: started, stage_started, stage_complete, approval_required, approved, rejected, success, failure, rollback, timeout

Artifacts Block

File preservation configuration.

FieldTypeRequiredDescription
namestringYesArtifact identifier
pathstringNoFile glob pattern
sourcestringNoStage output reference
formatstringNoOutput format: json, yaml, raw
retention_daysnumberNoDays to retain (default: 30)
compressionstringNoCompression type: gzip, none
requiredbooleanNoFail if artifact missing
conditionstringNoConditional preservation expression

State Block

Cross-run state persistence.

FieldTypeRequiredDescription
persistencebooleanNoEnable state persistence
ttlstringNoTime to live (e.g., "30d", "168h")
trackedstring[]NoAutomatically tracked values (timestamps, counters)
customCustomState[]NoUser-defined state values with name, value, and trigger condition
conditionsConditionsNoState-based behavior (pause_on_consecutive_failures, require_manual_after_rollback)

Postflight Block

Actions executed after all stages complete. Handles tracker persistence, token metric collection, and conditional handlers.

FieldTypeRequiredDescription
trackerPostflightTrackerNoValidation tracker integration for persisting pipeline results (project, workflow_type, token metrics, field mappings)
on_successPostflightAction[]NoActions to run when all gates pass (description, command, condition)
on_failurePostflightAction[]NoActions to run when any gate fails (description, command, condition)
alwaysPostflightAction[]NoActions to run regardless of outcome (description, command, condition)

Postflight Tracker

Configuration for saving pipeline results to the UluOps validation tracker.

FieldTypeRequiredDescription
enabledbooleanNoEnable tracker persistence (default: true)
projectstringNoTracker project name. Supports template expressions (e.g., {{ pipeline.interface.name }})
workflow_typestringNoWorkflow type identifier for the tracker run. Defaults to pipeline.interface.name
include_token_metricsbooleanNoCollect token usage metrics from agent-metrics buffer (default: true)
token_metrics_commandstringNoCommand to extract token metrics. Must output tracker-compatible format
field_mappingsFieldMappingsNoMaps pipeline output fields to tracker fields (score_source, status_source, model_source, recommendations_source)
verify_savebooleanNoAfter saving, verify that total_issues matches the saved count (default: true)

Execution Semantics (1.6.0)

PDL 1.6.0 makes the run normative, so the pdl-executor skill, rendered pipeline commands and @uluops/core read the same pipeline the same way. The full text, with every rule and code, is in the PDL 1.6.0 specification (Execution Semantics); 163 conformance fixtures in uluops-agent-workflows/udl/pdl/conformance/ hold each runtime to it. In brief:

TopicRule
Stage statusExactly one of PASSED, WARNED, FAILED, SKIPPED, ERRORED. ERRORED means the stage could not be judged: an agent was unjudgeable (no score and no classifiable decision, no score at a gate with a threshold, or an absent decision behind a blocking gate), a condition read a step that did not pass, or it was in flight at a stop.
Run verdictall_gates_passed is false when a stage FAILED, a stage ERRORED behind a blocking gate, a blocking gate accepted a conditional decision, or the run was stopped; otherwise true. Every runtime saves exactly this value.
Failure modesabort (and an absent on_failure) FAILS the stage and skips its transitive dependents only; every other stage still runs. fail FAILS and continues. warn WARNS. skip is a deprecated alias of fail. A stage with no gate never fails the run: a failed step or a negative decision makes it WARNED (D43).
Reading a decisionresult.decision, then decision, then the agent's Decision: line, reduced by a token rule that fails toward neutral (**REVISE** (Score: 85) is REVISE; NOT SECURE and SECURE WITH CONDITIONS are neutral). The token is classified through the agent's declared vocabulary, then the 13-token core register (PASS SHIP COMPLETE EXPLORED APPROVED PROCEED / FAIL FAILED BLOCK BLOCKED / WARN HOLD PARTIAL). Synonyms do not classify. The JSON read is the agent's output envelope, the object that carries result; an object without it (a fragment of a cut-off JSON block) is read for neither decision nor score.
Reading a scoreresult.score, then score, then a Score: line; a number from 0 to 100, or a string that is exactly one. Anything else is no score.
Neutral and absentA neutral decision never blocks: the score decides, with a warning. An absent decision (ABSENT_DECISION) is handled the same way at a warn gate or in a stage with no gate; behind a blocking gate it makes the agent unjudgeable whatever its score, so the stage is ERRORED (D12, measured at 10.56 absent per 100 against a threshold of 1 fixed in advance). Rendered agents are told to write one Decision: <TOKEN> line. Before launch, every agent in a blocking-gated stage must declare a vocabulary or be an explorer (VOCABULARY_MISSING).
ConditionsA closed language with three roots, validated at load; see below.
DependenciesAny terminal status satisfies depends_on; a depends_on entry naming a later stage (or the stage itself) is a load error.
StepsRun in the target directory, or a file target's parent. A {{ params.x }} template must be a whole double-quoted word or a whole bare word, and reaches the shell as an environment variable, never as text.

Conditions (stage and agentRef condition; conditions elsewhere stay free strings):

  • three roots: params.<name> (declared defaults bound first), stages.<id>.passed, and stages.<id>.steps['<name>'].output;
  • a comparison is a reference, == or !=, and a string literal; !, &&, || and parentheses combine them, && binding tighter;
  • '', false and 0 are false, and an absent parameter equals nothing;
  • reading a step that did not pass gives an error value: false && … and true || … absorb it, otherwise the stage or agent is ERRORED;
  • ordering operators, number and boolean literals, trigger.*, context.*, stage.<id> and a bare <id>.<field> are load errors; at most 512 code points.

Stage Dependency Graph

Pipelines build a DAG (Directed Acyclic Graph) from stage dependencies. Independent stages may run in parallel: the pdl-executor skill does, core runs them one at a time in array order, and statuses and all_gates_passed are the same either way.

yaml
stages:
  - id: lint          # Root
  - id: test          # Root
  - id: typecheck     # Root
  # All three may run in parallel (core runs them in array order)

  - id: build
    depends_on: [lint, test, typecheck]
    # Waits for all three to reach a terminal status, whatever it is
text
  lint    test    typecheck
    \      |      /
     \     |     /
        build

Conditions create runtime-determined paths:

yaml
stages:
  - id: validate
  - id: deploy-staging
    depends_on: [validate]
    condition: "params.environment != 'production'"
  - id: deploy-prod
    depends_on: [validate]
    condition: "params.environment == 'production'"

Before 1.6.0 this example read trigger.branch, which no runtime ever resolved; a condition reads only the three roots above.

⚠
Warning

No cycles — A depends_on entry must name a stage declared earlier in the array. A forward reference is a load error (forward_reference), which rules out cycles: A → C → B → A cannot be written.

Runtime Enforcement

How the execution engine (@uluops/core) enacts the spec at run time. These behaviors landed in core 0.29.0–0.32.0 (July 2026); earlier engines parsed the same fields without enforcing them.

PDL 1.6.0 in core. Core enforces the 1.6.0 execution semantics from 0.54.0 (2026-10-27). Core 0.53.x and earlier differ: an unreadable condition ran its stage (fail-open), only on_failure: abort | warn | skip was read, and an abort halted every remaining stage. The sections below say which engines each behavior applies to.

Stage Gates (core 0.54.0+)

Stage gate blocks are enforced, not advisory:

Gate directiveRuntime behavior
on_failure: abortThe stage is FAILED and its transitive dependents are skipped (skipReason: 'gate_abort'); every other stage still runs
on_failure: failThe stage is FAILED and the run continues; dependents still run
on_failure: warnThe stage is WARNED and the run continues
on_failure: skipDeprecated alias of fail (load warning SKIP_DEPRECATED)
on_success: skip_remainingEarly-exit — remaining stages are skipped (gate_early_exit)

A gate that omits on_failure defaults to abort, and so does any value outside the list — declaring a gate means declaring a hard stop unless you say otherwise. A stage with no gate never fails the run: a failure there is WARNED. An abort-gated stage that cannot execute (for example, a steps:-only stage while step execution is disabled) fails the run loudly with a remedy instead of auto-passing.

Core 0.32.0–0.53.x enforced gates differently: abort halted the whole pipeline, skip skipped the gated stage's dependents (gate_skip), and there was no fail.

Stage Output Forwarding (core 0.31.0+)

Multi-stage pipelines forward upstream results into downstream agents' prompts by default. An inline-agent stage with depends_on receives an ## Upstream Analysis section containing each dependency's decision, score, summary, and top recommendations (severity-sorted). Control it per stage:

  • Producer side: forward: auto | none | full
  • Consumer side: receives: auto | none

Size is capped deterministically (8K per upstream slice, 32K total, with a three-step reduction when over budget). Kill switch: ULUOPS_DISABLE_STAGE_FORWARDING=1.

Steps Execution (core 0.29.0+, opt-in)

steps: blocks execute as sequential shell commands only when explicitly enabled (ULUOPS_ALLOW_STAGE_STEPS=true; default off). The executor honors the full step contract — timeout, retries, retry_delay, continue_on_error, always_run, expect_empty, expect_match, per-step env, working_dir — with hardened confinement: secret-class environment variables are scrubbed, loader-variable overrides (PATH, LD_*, NODE_OPTIONS, …) are rejected, and working_dir is realpath-contained. Steps-only stages pass through as decision: PASS with a null score and are excluded from pipeline score aggregation — they do not fabricate scores.

Condition Semantics (core 0.29.1–0.53.x)

Stage and per-agent condition expressions evaluate over params.* and stages.* paths. Absent params are false, not unknown — params.frontend unset means a condition: "params.frontend" agent is not dispatched (no fabricated result). Absent stage paths remain fail-open so a skipped upstream stage does not silently veto downstream conditions. PDL 1.6.0 replaces this with the closed condition language above: an unreadable condition is a load error, not a stage that runs.

Convergence Loops (PDL 1.3.0/1.4.0 — not yet core-enforced)

The convergence block is validated by @uluops/definition-factory 0.45.0+ (six semantic rules: loop-stage existence, gate-subset, no gate-stage conditions, min ≤ max, no post-loop dependencies, advisory-gate warning) and enacted by the Claude-harness PDL executor (the pdl-executor skill), which owns the loop protocol: fresh-score gate evaluation, ERRORED (never 0) for missing gate scores, iteration-namespaced artifacts, carry-context prompt injection, WARNED (not FAILED) loop-stage status on UNCONVERGED exit so post-loop stages still run, the stall exit (1.4.0: stall_iterations consecutive fixless iterations), and the tracker no-save contract injected into loop-stage agent prompts (1.4.0). The harness executor lives as the pdl-executor skill (formerly /pipelines:run).

The programmatic engine (@uluops/core) currently parses the field without enforcing it — a convergence pipeline run through core executes as a one-pass DAG. Engine-side loop enforcement is an open follow-up; until it lands, run convergence pipelines through the harness executor.

Composition Rules

ℹ
Note
Pipelines can reference Workflows (WDL), Commands (CDL), and Agents (ADL) — Pipeline stages can contain workflow references, command references, and direct agent references (by subagent_type), composing them into multi-stage orchestrations.
ℹ
Note
Pipelines can contain inline shell steps — Simple operations can be expressed as inline steps without requiring a formal CDL command definition.
ℹ
Note
Stages form a DAG via depends_on — Each depends_on entry names a stage declared earlier in the array; a forward reference is a load error, which rules out cycles. Any terminal status of a dependency satisfies it, except that a stage downstream of one that failed behind abort is skipped.
ℹ
Note
Triggers are exclusive to pipelines — Only PDL definitions have triggers. Workflows and commands are invoked programmatically or by a pipeline.
ℹ
Note
Approvals and rollback are pipeline-level concerns — Human approval gates and automatic rollback strategies exist only in PDL, not in WDL or CDL.
ℹ
Note
Postflight handles tracker persistence — The postflight block integrates with the UluOps validation tracker to persist pipeline results, collect token metrics, and run conditional cleanup actions.

Revision History

VersionDateChanges
1.6.02026-10-26
  • Execution Semantics (normative): one run model and stage status set (PASSED, WARNED, FAILED, SKIPPED, ERRORED) and all_gates_passed as the saved verdict, the same in every runtime (the pdl-executor skill, rendered commands, @uluops/core)
  • Gates read decisions: gate.decision (not_negative, positive, ignore); a fixed output contract (result.decision, then decision, then a Decision: line; result.score, then score, then a Score: line); a token rule that fails toward neutral; classification through the agent's vocabulary, then a 13-token core register. Neutral and absent decisions never block; the score decides
  • Per-agent thresholds (agentRef.threshold); on_failure: fail (the run continues); abort skips only the aborting stage's dependents; a stage with no gate never fails the run (it is WARNED instead)
  • A closed condition language for stage and agentRef conditions: three roots (params, stages.<id>.passed, step output), string equality, truthiness, parentheses, Kleene error propagation for reads of a step that did not pass; validated at load, at most 512 code points
  • One dependency rule: any terminal status satisfies depends_on; a forward reference is a load error. Steps run in the target directory (a file target's parent); a {{ params.x }} template must be a whole double-quoted or bare word and reaches the shell as an environment variable
  • Schema: gate, stage and agentRef closed; stage description, forward and receives declared; pipeline.scoring declared. Warning, refusal and load-error codes; 154 conformance fixtures in uluops-agent-workflows udl/pdl/conformance
  • Corrected: Design Principle 1 forbade direct agent references, which 1.2.0 had added; examples used trigger.*, context.* and ordering comparisons in conditions, which no runtime resolves
1.5.02026-07-15
  • Decision-gated convergence: convergence.gate accepts satisfied_by (completion Decision tokens, e.g. [DRAINED]) as a schema-enforced mutually-exclusive alternative to threshold; aggregate is permitted only with threshold
  • A decision gate terminates the loop on the gate stage's Decision (a single decision-only executor): terminal-complete converges, continue-class runs remaining loop stages, failure-class is ERRORED
  • Decision-only loops carry no score — headlined by convergence.decision, average_score omitted; a loop that updates issue lifecycle in place submits no postflight recommendations (re-reporting would fingerprint-reopen resolved issues)
  • Validator rule 8 (threshold XOR satisfied_by, schema-enforced) + rule 9 (a decision gate should name a single stage, warning)
1.4.02026-07-11
  • Convergence hardening from the first live run: stall_iterations (default 2) + on_stall — the loop exits UNCONVERGED / exit_reason stalled after N consecutive iterations applying zero mechanical fixes
  • Tracker policy: suppress_agent_saves (default true) injects a no-save contract into loop-stage agent prompts — postflight is the single owner of run persistence; allow_executor_issue_updates keeps issue-level updates on pre-existing issues allowed
  • convergence.exit_reason postflight expression (converged | max_iterations | stalled | user_pause)
  • Validation rule 7 (warning): stall_iterations must be less than max_iterations
1.3.02026-07-11
  • Added pipeline-level convergence block for iterative fix loops: designated loop_stages re-execute until a score gate passes or max_iterations is reached
  • Convergence gate evaluates immediately after gate stages complete — fresh-score exit, no wasted fix cycle after passing
  • Non-loop stages run once post-loop; UNCONVERGED is a first-class outcome (on_max_iterations: warn)
  • Carry context: prior-iteration findings, dispositions, and fix summaries injected into loop-stage agent prompts
  • Missing gate scores recorded as ERRORED (never coerced to 0); cross-iteration artifacts namespaced by iteration index
  • Six semantic validation rules enforced by the PDL validator (loop-stage existence, gate subset, no gate-stage conditions, min<=max, no post-loop dependencies, advisory-gate warning)
1.2.02026-03-26
  • Added postflight block with tracker integration (project, workflow_type, token metrics, field mappings)
  • Added postflight conditional handlers: on_success, on_failure, always
  • Added direct agent references in stages (agents field with subagent_type identifiers)
  • Added stage inputs, outputs, and artifacts_from for cross-stage data flow
1.0.02026-01-14
  • Initial PDL specification
  • Trigger types: git_push, pull_request, schedule, webhook, manual, pipeline
  • Stage orchestration with DAG-based dependency resolution
  • Human approval workflows with multi-level support
  • Rollback strategies: revert_to_last_success, revert_to_previous, custom
  • Notification channels: slack, email, github_status, webhook, pagerduty, teams
  • Artifact preservation with retention policies
  • Cross-run state persistence