Skip to content
DWS Specification

Architecture Overview

DWS is Not a Runtime

DWS defines WHAT a worker is. Runtimes define WHERE and HOW it runs.

A job spec definition compiles to multiple runtimes. The same contract-reviewer job spec can target Claude Managed Agents, CrewAI, AWS Bedrock Agents, or a custom Docker deployment. The definition is portable. The runtime is not.

The Protocol Stack

DWS operates as the governance layer in a layered protocol stack:

LayerStandardDWS’s Role
Tool accessMCPDWS skills reference MCP tools. The runtime dispatches calls. DWS guardrails wrap invocations with authority checks.
Inter-worker commsA2ADWS handles internal coordination. A2A handles cross-organisational communication. Worker Descriptors map to A2A Agent Cards.
IdentityIETF AIMS / W3C DIDDWS defines worker identity. The runtime maps it to AIMS or DID for cross-boundary authentication.
ObservabilityOpenTelemetryDWS events are an OTel superset. Workflows map to traces, phases to spans.
GovernanceDWSAuthority levels, verification gates, knowledge management, compliance mapping, cost controls.

No other standard in this stack addresses structured worker governance. MCP connects workers to tools. A2A connects workers to each other. DWS defines what a worker is and how it is held accountable.

Definition-Time vs Runtime

DWS draws a hard line between definition-time and runtime:

Definition-time artifacts are authored by humans, committed to git, and reviewed through pull requests. They are inert files until a runtime instantiates them.

  • jobspec.json (manifest)
  • workers/*.json (worker descriptors)
  • skills/*.json (skill definitions)
  • workflows/*.json (workflow definitions)
  • intents/*.json (intent artifacts, pre-execution)
  • outcomes/*.json (outcome contracts)
  • knowledge/conventions/*.json (seed knowledge)
  • contracts/*.json (worker-to-worker contracts)

Runtime artifacts are produced during execution and stored in the event stream. They are not git-committed.

  • Events (every action produces a typed event)
  • Live knowledge entries (session-scoped observations, promoted institutional knowledge)
  • Verification findings
  • Intent mutations (changes to intents during execution)
  • Cost records

The bridge between the two is the base_version field: a git commit hash that anchors every runtime event to a specific, immutable set of definitions. And the dws reconcile tool closes the loop by proposing git commits that incorporate runtime learning back into definitions.

Runtime Architecture

When a runtime instantiates a job spec, the execution follows this flow:

  1. Intent ingestion. A work order arrives (email, Slack, webhook, API, another worker). The runtime normalises it into a validated intent artifact.

  2. Intake decision. Should this worker handle it? Can it? Which workflow? This is pure rule evaluation against intent fields. No model is involved.

  3. Pre-execution authority gate (Level 1). The runtime checks the worker’s authority level against the intent before the harness is assembled.

  4. Workflow engine. The runtime traverses the phase graph, evaluates transition conditions, tracks cost, manages approval gates, and enforces timeouts. Deterministic. No model involvement.

  5. Worker harness. For each phase, the runtime assembles a fresh harness: prompt (with role context, authority level, knowledge layers, phase purpose), available tools (via MCP), and output schema.

  6. Execution. The model receives the composed prompt and may call tools iteratively via the runtime’s tool router before producing phase output. The tool router (Level 3 authority) intercepts every tool call and checks authority before dispatching.

  7. Verification gate. An independent verifier worker evaluates the output against the intent. Fresh model invocation. No shared memory with the executor.

  8. Outcome delivery. The runtime routes output through defined delivery channels (source reply, CRM write, downstream worker, webhook, event stream).

  9. Event store. Every layer writes to the append-only event store. This feeds the knowledge lifecycle and compliance audit trail.

Compile Targets

The dws compile command translates a job spec definition into runtime-specific configuration:

Terminal window
dws compile ./my-worker --target managed-agents   # Anthropic Claude Managed Agents
dws compile ./my-worker --target claude-agent-sdk  # Claude Agent SDK
dws compile ./my-worker --target crewai            # CrewAI
dws compile ./my-worker --target bedrock           # AWS Bedrock Agents
dws compile ./my-worker --target docker            # Self-hosted

Each compile target maps DWS primitives to the target runtime’s concepts (e.g., Worker Descriptor to Managed Agents agent config, Knowledge entries to memory stores, authority levels to permission policies).