Pipeline Definition Language

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:

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

What Pipelines Do

Pipeline vs Workflow

Design Principles

Schema Structure

CI/CD Pipeline

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

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:

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:

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: 0
        on_failure: warn

    - id: auto-fix
      name: Automatic Fixes
      depends_on: [audit]
      condition: "params.auto_fix && stages.audit.score < 90"
      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.completed"
      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.

Triggers Block

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

Trigger Types:

Environment Block

Environment variables and secrets for the pipeline.

Stages Block

Stages are the primary execution units in a pipeline.

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.

Approvals Block

Human approval requirements for stages.

Approval Timeout Behavior:

Rollback Block

Automatic failure recovery configuration.

Rollback Strategies:

Notifications Block

External system notification configuration.

Channel Types:

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

Artifacts Block

File preservation configuration.

State Block

Cross-run state persistence.

Postflight Block

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

Postflight Tracker

Configuration for saving pipeline results to the UluOps validation tracker.

Stage Dependency Graph

Pipelines build a DAG (Directed Acyclic Graph) from stage dependencies. Independent stages run in parallel automatically.

stages:
  - id: lint          # Root
  - id: test          # Root
  - id: typecheck     # Root
  # All three run in parallel

  - id: build
    depends_on: [lint, test, typecheck]
    # Waits for all three

  lint    test    typecheck
    \      |      /
     \     |     /
        build

Conditions create runtime-determined paths:

stages:
  - id: validate
  - id: deploy-staging
    depends_on: [validate]
    condition: "trigger.branch != 'main'"
  - id: deploy-prod
    depends_on: [validate]
    condition: "trigger.branch == 'main'"

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.

Stage Gates (core 0.32.0+)

Stage gate blocks are enforced, not advisory:

A gate that omits on_failure defaults to abort — declaring a gate means declaring a hard stop unless you say otherwise. 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.

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+)

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.

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

Revision History