Command Definition Language

CDL defines single-agent invocation envelopes that wrap ADL agents with execution context, preflight checks, overrides, iteration loops, and postflight actions.

Format YAML + JSON SchemaExtension .command.yamlVersion 2.0.0Status DraftUpdated 2026-03-02

Overview

The Command Definition Language (CDL) is a YAML-based specification for defining executable commands in the UluOps framework. Commands wrap agents with execution context — preflight checks, argument overrides, iteration loops, and postflight actions. CDL is the bridge between atomic agents (ADL) and multi-command workflows (WDL).

text

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

Key Characteristics

Aspect	Description
Purpose	Single-agent invocation envelope with execution context
Scope	Preflight, overrides, iteration, postflight, tracking
Agents	References exactly one ADL agent per command
Invocation	CLI (`ulu exec command`), SDK, or within WDL workflows

Design Principles

💡

Tip

One Command, One Purpose — Each command has a single purpose determined by its commandType. Agent-backed commands wrap exactly one agent. Utility commands execute procedural steps directly.

💡

Tip

Thin Wrapper Philosophy — Commands add context but not logic. The agent contains all validation/execution logic; the command provides the invocation envelope.

💡

Tip

Override, Don't Replace — Commands can override agent defaults (model, threshold, timeout) but cannot fundamentally alter agent behavior.

💡

Tip

Consistent Interface Pattern — All commands use the same interface block structure as Agents (ADL) for consistency across the definition language family.

💡

Tip

Agent-Type Agnostic — The agent command type wraps any ADL agent regardless of agentType (validator, executor, analyst, generator, explorer, forecaster). Decision vocabulary and output semantics are determined by the wrapped agent, not the command.

Command Types

CDL defines three command types:

Wrap any ADL agent with execution context and decision tracking

Output

Agent-determined (Score, Artifacts, Analysis)

Decision Vocabulary

Determined by wrapped agent's agentType

Use Cases

Code quality validation
Prompt scaffolding and generation
Security auditing
Iterative remediation loops

Requires

interfaceinvokes

Agent-less procedural commands for direct execution

Output

Procedural Result

Decision Vocabulary

COMPLETE / FAILED

Use Cases

Git commit workflows
Issue resolution checking
Environment setup
File operations

Requires

interface

All-optional escape hatch for advanced use cases

Output

User-defined

Decision Vocabulary

User-defined

Use Cases

Experimental command patterns
Custom tool integrations
Non-standard agent wrappers
Prototype commands

Requires

interface

Schema Structure

Agent Command

The most common type — wraps an ADL agent with full execution context:

yaml

command:
  interface:
    commandType: agent

  invokes:               # Required
    agent: AgentRef        # name@version format

  execution:             # Optional
    model:
      default: Model
      allowed: Model[]
    timeout: number

  preflight:             # Optional
    checks: PreflightCheck[]
    banner:
      template: string

  overrides:             # Optional
    threshold: number
    timeout: number
    temperature: number

  iteration:             # Optional
    max_attempts: number
    exit_threshold: number
    target_agent: AgentRef
    fix_patterns: boolean

  postflight:            # Optional
    steps: PostflightStep[]
    on_success: { message, exit_code }
    on_partial: { message, exit_code }
    on_failure: { message, exit_code }

  output:                # Optional
    schema: string
    format: structured | summary | minimal

Execution Flow:

text

1. PREFLIGHT     -- Display banner, run checks
2. RESOLVE       -- Fetch agent definition, apply overrides
3. EXECUTE       -- Invoke agent, capture result
   (If iteration block: loop until exit_threshold or max_attempts)
4. POSTFLIGHT    -- Persist to tracker, present decision

Utility Command

Agent-less procedural command for direct execution:

yaml

command:
  interface:
    commandType: utility

  # No invokes block -- utility commands have no agent

  execution:             # Optional
    model:
      default: Model
    timeout: number

  preflight:             # Optional
    checks: PreflightCheck[]

  tracking:              # Optional
    enabled: boolean
    variant: custom | none
    custom:
      persistence_tool: string
      field_mappings: object

  postflight:            # Optional
    on_success: { message, exit_code }
    on_failure: { message, exit_code }

  output:                # Optional
    schema: string
    format: summary | minimal

Execution Flow:

text

1. PREFLIGHT     -- Display banner, run checks
2. EXECUTE       -- Follow procedural steps (no agent)
3. POSTFLIGHT    -- Execute steps, present result

Custom Command

All-optional escape hatch for advanced use cases:

yaml

command:
  interface:
    commandType: custom

  invokes:               # Optional
    agent: AgentRef

  execution:             # Optional
    model:
      default: Model
    timeout: number

  preflight:             # Optional
    checks: PreflightCheck[]

  overrides:             # Optional
    threshold: number

  iteration:             # Optional
    max_attempts: number
    exit_threshold: number

  postflight:            # Optional
    on_success: { message, exit_code }
    on_failure: { message, exit_code }

  output:                # Optional
    schema: string
    format: structured | summary | minimal

Field Reference

Interface Block

Identifies the command. Consistent with ADL 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)
`commandType`	`enum`	Yes	Command type: agent, utility, or custom
`description`	`string`	Yes	When to use + what it does (20-500 chars)
`domain`	`enum`	Yes	Primary domain (software, security, legal, etc.)
`subdomain`	`string`	No	Optional refinement of domain
`tags`	`string[]`	No	Searchable tags for discovery

Invokes Block

Specifies which ADL agent the command wraps.

Field	Type	Required	Description
`agent`	`AgentRef`	Yes	Agent reference in name@version format (e.g., code-validator@>=1.0.0)

Execution Block

Controls runtime behavior — model, timeout, directories.

Field	Type	Required	Description
`model.default`	`Model`	Yes	Default model for invocation (haiku, sonnet, opus)
`model.allowed`	`Model[]`	No	Models users can override to
`timeout`	`number`	No	Timeout in milliseconds (default: 300000)
`max_retries`	`number`	No	Number of retry attempts on failure (0-5, default: 0)
`retry_delay`	`number`	No	Delay between retries in milliseconds (default: 1000)

Preflight Block

Actions executed before the agent runs.

Field	Type	Required	Description
`checks`	`PreflightCheck[]`	No	List of preflight checks to run before execution
`banner.template`	`string`	No	Banner template to display before execution

Overrides Block

Dynamic modifications to the wrapped agent's configuration.

Field	Type	Required	Description
`threshold`	`number`	No	Override agent's default decision threshold (0-100)
`timeout`	`number`	No	Override agent's default timeout in milliseconds
`temperature`	`number`	No	Override model temperature (0.0-1.0)

Arguments Block

Named parameters that configure command behavior at invocation time.

Field	Type	Required	Description
`examples`	`string[]`	No	Example argument values for documentation (1-5 items)

Iteration Block

Configures the iterative review-fix loop pattern.

Field	Type	Required	Description
`max_attempts`	`integer`	Yes	Maximum fix-review iterations before escalation (1-20)
`exit_threshold`	`number`	Yes	Score >= this value ends the loop (0-100)
`target_agent`	`AgentRef`	No	Agent to re-run each cycle (defaults to invokes.agent)
`fix_patterns`	`boolean`	No	Whether to include fix pattern guidance (default: true)

Postflight Block

Actions executed after the agent completes.

Field	Type	Required	Description
`steps`	`PostflightStep[]`	No	Ordered list of postflight actions to execute
`on_success`	`PostflightAction`	No	Action when agent succeeds (score >= threshold, or task completed)
`on_partial`	`PostflightAction`	No	Action when agent partially succeeds (CONDITIONAL result)
`on_failure`	`PostflightAction`	No	Action when agent fails (score < threshold, or task failed)

Tracking Block

Integration with the UluOps validation tracker.

Field	Type	Required	Description
`enabled`	`boolean`	No	Whether to include tracking section (default: true)
`required`	`boolean`	No	Whether tracker persistence is mandatory before presenting results (default: true)
`variant`	`enum`	No	Tracking implementation: claude-code, sdk, custom, or none (default: claude-code)
`custom`	`CustomTracking`	No	Custom tracking configuration (required when variant is 'custom')

Output Block

Defines the command's structured output format.

Field	Type	Required	Description
`schema`	`string`	Yes	Output schema reference (e.g., validator-output-v1.1)
`format`	`enum`	No	Output format: structured, summary, or minimal (default: structured)

Composition Rules

ℹ

Note

Agent commands require interface + invokes — Agent commands must include the interface and invokes blocks. Optional blocks: execution, preflight, overrides, inputs, arguments, iteration, postflight, tracking, output. No blocks are forbidden.

ℹ

Note

Utility commands require interface only — Utility commands must include the interface block. Optional blocks: execution, preflight, inputs, arguments, postflight, tracking, output. Forbidden blocks: invokes, iteration, overrides.

ℹ

Note

Custom commands require interface only — Custom commands must include the interface block. Optional blocks: invokes, execution, preflight, overrides, inputs, arguments, iteration, postflight, tracking, output. No blocks are forbidden.

Revision History

Version	Date	Changes
2.0.0	2026-03-01	Collapsed validator/executor/fixer command types into unified agent type Added custom type Unified postflight handlers: on_success/on_partial/on_failure (replacing on_pass/on_fail/on_complete/on_failed/on_warn) Iteration block now optional for agent/custom types Removed forbidden block lists in favor of recommendations
1.3.0	2026-02-08	Added interface.commandType (required enum: validator, executor, utility, fixer) Made invokes conditional Added iteration block for fixer commands New templates: utility-command.md.njk, fixer-command.md.njk
1.2.0	2026-01-30	Added tracking.required field for mandatory persistence before presenting results Added postflight.steps array for ordered post-agent actions
1.1.1	2026-01-18	Added arguments.examples field for custom usage examples in generated documentation
1.1.0	2026-01-18	Added tracking block for configurable metrics collection and persistence Supports claude-code, sdk, custom, and none variants
1.0.1	2026-01-14	Updated agent reference format to name@version syntax Added arg input source type for CLI argument passthrough
1.0.0	2026-01-13	Initial CDL specification Single-agent invocation model with preflight checks, execution config, overrides, and postflight actions