Procedure DSL Technical Specification

Complete reference for the Plexus Procedure DSL v4.0.0

Documentation Files

The Procedure DSL documentation is maintained in the codebase at /plexus/procedures/

DSL_SPECIFICATION.md

Complete technical specification (~65KB) covering every aspect of the DSL:

  • Complete document structure and YAML schema
  • All primitives and API reference
  • Human-in-the-Loop patterns and execution contexts
  • Message classification system
  • Idempotent execution model
  • Real-world examples with full code

AGENTS.md

Quick reference guide (~3KB) with common patterns and a pointer to the full spec. Optimized for AI coding agents to load efficiently.

Working Examples

Live, tested procedure examples:

  • limerick_writer.yaml - Basic single-agent loop
  • creative_writer.yaml - Multi-agent sequential pipeline
  • README.md - Example documentation and usage

Key Sections

Document Structure

Every procedure is defined in YAML with these sections:

  • Metadata: name, version, description
  • Parameters: typed input schema
  • Outputs: typed return schema
  • Guards: pre-execution validation
  • HITL: human interaction points
  • Agents: LLM worker configurations
  • Stages: workflow phase tracking
  • Workflow: Lua orchestration code

Primitive Categories

The DSL provides high-level primitives in these categories:

  • Procedure: run, spawn, wait, status, inject, cancel
  • Agent: turn (e.g., Worker.turn())
  • Human: approve, input, review, notify, escalate
  • System: alert
  • State: get, set, increment, append, all
  • Stage: set, current, is, advance, history
  • Tool: called, last_result, last_call
  • Session: append, inject_system, clear, history
  • Control: Stop, Iterations
  • Utility: Log, Sleep, Json, File, Retry

Design Philosophy

  • YAML declares, Lua orchestrates - Separation of configuration and control flow
  • High-level primitives - Simple operations hide complex LLM mechanics
  • Uniform recursion - Procedures work identically at all nesting levels
  • Human-in-the-loop first - Collaboration patterns built into the core
  • Built-in reliability - Retries, validation, and recovery under the hood

Quick Reference

Minimal Procedure

name: simple_task
version: 1.0.0

agents:
  worker:
    system_prompt: "Complete the task"
    tools: [done]

workflow: |
  Worker.turn()

With HITL

workflow: |
  Worker.turn()

  local approved = Human.approve({
    message = "Proceed?",
    timeout = 3600
  })

  if approved then
    execute()
  end

Async Invocation

workflow: |
  -- Spawn in parallel
  local handles = {}
  for _, topic in ipairs(params.topics) do
    local h = Procedure.spawn("researcher", {topic = topic})
    table.insert(handles, h)
  end

  -- Wait for all
  Procedure.wait_all(handles)

  -- Collect results
  local results = {}
  for _, h in ipairs(handles) do
    table.insert(results, Procedure.result(h))
  end