Definitions

ADL, CDL, WDL, PDL — the four definition languages that encode expert judgment as versioned YAML.

Overview

UluOps uses four definition languages to describe AI agents, commands, workflows, and pipelines as versioned YAML specs. Definitions are the unit of reuse — they encode expert judgment once, and that judgment is executed repeatedly. Precisely speaking, the YAML definition is not itself what runs: it is the source from which a runtime prompt is rendered, and the rendered artifact is what executes. The two-stage model matters when you audit or improve a definition — see Recursive Appreciation for why the YAML→render seam is where improvements land.

Every definition follows the same lifecycle: draft → published → deprecated → archived (see the full table below). Each version is immutable once published. The Registry API stores, versions, and serves definitions — browse the published catalog in the Registry app.

Agent Definition Language (ADL)

ADL defines validation agents — their scoring criteria, output format, decision thresholds, and execution context. An ADL spec tells the AI model what to evaluate and how to score it.

agent:
  interface:
    name: code-validator
    version: 3.2.0
    agentType: validator
    domain: software
  scoring:
    maxScore: 100
    categories:
      - id: correctness
        name: "Code Correctness"
        weight: 30
  decisions:
    vocabulary:
      positive: PASS
      negative: FAIL
    preset: quality_gate

Key ADL fields:

• interface — Name, version, domain classification, epistemic nature
• scoring — Score range and decision thresholds (configured via presets like quality_gate, high_stakes, low_risk)
• criteria — What the agent evaluates (checklist items with weights)
• output — Response format and required sections
• context — Files, directories, and patterns the agent should read
• epistemic_nature — Multi-axis classification: verifiability, determinism, and claim type (v1.13.0)

Command Definition Language (CDL)

CDL defines executable commands — invocation envelopes that wrap agents or utilities with execution context, preflight checks, and postflight actions. CDL supports three command types: agent commands (wrapping an ADL agent), utility commands (agent-less procedural execution), and custom commands (escape hatch for advanced use cases). Agent commands are the most common type.

# Agent command — wraps an ADL validator with execution context
command:
  interface:
    name: validate-code
    version: 1.0.0
  invokes:
    agent: code-validator
    version: ">=3.0.0"
  execution:
    model: sonnet
    timeout: 120000

Workflow Definition Language (WDL)

WDL defines multi-phase validation workflows — sequential or parallel execution of agents and commands with gate conditions between phases.

workflow:
  interface:
    name: ship
    version: 2.0.0
  phases:
    - name: validate
      parallel: true
      commands:
        - ref: code-validator
        - ref: type-safety-validator
      gate:
        condition: all_pass
        threshold: 75
    - name: test
      commands:
        - ref: run-tests
      gate:
        condition: coverage_above
        value: 80

Phases execute sequentially. Within a phase, commands can run in parallel. Gate conditions determine whether to proceed to the next phase.

Pipeline Definition Language (PDL)

PDL defines multi-workflow pipelines — orchestrating multiple workflows with shared context and cross-workflow dependencies. Pipelines add triggers (git push, PR, schedule, webhook, manual), human approval gates, automatic rollback on failure, external notifications, artifact preservation, and cross-run state.

Definition Lifecycle

Definitions are versioned using semantic versioning. The Registry API enforces version ordering and provides latest resolution for each definition.

Working with Definitions

Use the Registry SDK for programmatic access:

// Fetch the latest published version
const def = await client.definitions.get('agent', 'code-validator');

// Create a new draft
await client.definitions.create('agent', 'my-validator', { yaml });

// Publish a version
await client.versions.publish('agent', 'my-validator', '1.0.0');

Or use the Registry MCP client from Claude Code for interactive definition management.