Spec 6: Workflow & Phases

DWS Spec 6: Workflow & Phase Model

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 2 — Orchestration Status: Release Candidate Dependencies: Spec 1 (Worker Identity), Spec 3 (Skill Specification), Spec 4 (Intent Artifacts), Spec 8 (Verification & Evaluation)

---

1. Overview

This specification defines how work flows through phases, how phases are structured, and how verification gates control progression. A workflow takes intent artifacts (Spec 4), assigns workers (Spec 1) with skills (Spec 3), structures their work into phases, and gates progression with verification (Spec 8).

Workflows are the layer where DWS’s structural guarantees become concrete. Without workflows, workers execute skills in isolation. With workflows, skills compose into auditable, repeatable sequences with defined checkpoints and failure handling.

---

2. Workflow Schema

2.1 Workflow Identity

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "version", "description", "phases", "transitions", "entry_phase", "exit_conditions"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "domain": { "type": "string" },
    "description": { "type": "string" },
    "applicable_intent_types": {
      "type": "array",
      "items": { "type": "string", "enum": ["strategic", "operational", "constraint"] }
    },
    "hooks": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["hook_id", "hook_point", "handler"],
        "properties": {
          "hook_id": { "type": "string" },
          "hook_point": {
            "type": "string",
            "enum": ["pre_phase", "post_phase", "pre_tool_call", "post_tool_call", "pre_verification", "post_verification", "pre_workflow", "post_workflow"]
          },
          "handler": {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": { "type": "string", "enum": ["skill_ref", "tool_uri", "webhook"] },
              "ref": { "type": "string" }
            }
          },
          "timeout": { "type": "string" },
          "on_failure": { "type": "string", "enum": ["abort", "skip", "warn"], "default": "warn" },
          "order": { "type": "integer", "default": 0 }
        }
      }
    }
  }
}

2.2 Phase Graph

The workflow’s phases and transitions form a directed graph. Phases are nodes; transitions are edges.

The graph MUST have exactly one entry phase and at least one exit path. Cycles are permitted only through explicit loop transitions (Section 4.4) with mandatory iteration limits.

2.3 Global Constraints

{
  "global_constraints": {
    "max_duration": "PT4H",
    "cost_ceiling": { "amount": 50.00, "currency": "USD" },
    "max_iterations": 10,
    "cost_tracking": {
      "enabled": true,
      "worker_budgets": [
        {
          "role": "implementor",
          "budget": { "amount": 30.00, "currency": "USD" },
          "alert_threshold": 0.8
        }
      ],
      "alerts": [
        { "threshold": 0.5, "action": "notify" },
        { "threshold": 0.8, "action": "escalate" },
        { "threshold": 1.0, "action": "pause" }
      ],
      "attribution": "per_phase"
    }
  }
}

Global constraints MUST be checked by the runtime at every phase boundary. If a global constraint is violated, the workflow MUST transition to its failure handling path or escalate.

Cost tracking attribution determines how costs are bucketed: per_worker, per_phase, per_intent, or all.

---

3. Phase Definition

Each phase is a bounded unit of work with defined inputs, outputs, and worker assignments.

3.1 Phase Schema

Field	Type	Required	Description
id	string	MUST	Unique phase identifier within the workflow.
name	string	MUST	Human-readable name.
purpose	string	MUST	Description of what this phase accomplishes.
worker_assignment	object	MUST	Role, count, and selection strategy.
entry_conditions	array	MAY	Conditions that MUST be true before phase begins.
available_skills	array	MAY	Skills accessible during this phase (Spec 3).
loaded_context	object	MAY	Knowledge layers and entries to load (Spec 2).
active_constraints	array	MAY	Phase-specific constraints.
artifact_production	array	MAY	Artifacts this phase is expected to produce.
exit_conditions	array	MUST	Conditions that MUST be true for phase completion.
verification_gate	object	MAY	Verification checkpoint at phase completion (Spec 8).
approval_gate	object	MAY	Human sign-off gate (Spec 10).
input_guardrails	array	MAY	Guardrail IDs applied to inputs (Spec 1 Section 2.5).
output_guardrails	array	MAY	Guardrail IDs applied to outputs.
interaction_mode	object	MAY	Human-worker interaction mode (Spec 9).
timeout	string	MAY	ISO 8601 duration.

3.2 Worker Assignment

{
  "worker_assignment": {
    "role": "implementor",
    "count": 1,
    "selection_strategy": "any"
  }
}

Selection strategies: any (any worker with the role), specific (named worker), round_robin (rotate among available workers).

3.3 Gate Ordering

When a phase has both verification and approval gates:

1. Worker produces artifacts.
2. Output guardrails are evaluated.
3. Exit conditions are checked.
4. Verification gate runs (if present).
5. Approval gate runs (if present and placement is after_verification).

Input guardrails are evaluated after entry conditions pass but before the worker begins work.

---

4. Phase Transitions

4.1 Sequential

One phase completes, the next begins.

{ "type": "sequential", "from": "design", "to": "implement" }

4.2 Conditional

Next phase is determined by evaluating conditions against the current phase’s output.

{
  "type": "conditional",
  "from": "triage",
  "branches": [
    { "condition": { "field": "$.output.severity", "operator": "eq", "value": "critical" }, "to": "urgent-fix" },
    { "condition": { "field": "$.output.severity", "operator": "eq", "value": "low" }, "to": "backlog" }
  ],
  "default": "standard-fix"
}

4.3 Parallel (Fork/Join)

Multiple phases execute concurrently with a configurable join strategy.

{
  "type": "parallel",
  "from": "analysis",
  "branches": ["security-review", "performance-review", "style-review"],
  "join": {
    "strategy": "all",
    "to": "synthesize",
    "timeout": "PT1H"
  }
}

Join strategies:

• all — wait for all branches to complete before proceeding.
• any — proceed when any branch completes; cancel remaining.
• n_of_m — proceed when N branches complete. Requires min_branches field.

When a parallel branch fails, the runtime SHOULD attempt to complete remaining branches before evaluating the join condition, unless the failure is critical.

4.4 Loop

Cycle back to a previous phase with a mandatory iteration limit.

{
  "type": "loop",
  "from": "verify",
  "to": "implement",
  "condition": { "field": "$.verification.verdict", "operator": "eq", "value": "fail" },
  "max_iterations": 3,
  "on_exhaustion": "escalate"
}

Loop transitions MUST declare max_iterations. The runtime MUST enforce the limit. When iterations are exhausted, the on_exhaustion action is taken: escalate, abort, or proceed_with_warning.

4.5 Handoff

Agent-to-agent transfer with full context. See Spec 10 (Approval & Handoff) for context transfer details.

{
  "type": "handoff",
  "from": "initial-review",
  "to": "specialist-review",
  "handoff_config": {
    "context_transfer": {
      "artifacts": true,
      "conversation_history": false,
      "summary": true
    }
  }
}

4.6 Delegation

Assigns a subtask to another worker and expects a result back. The delegating phase pauses until the delegated work completes.

{
  "type": "delegation",
  "from": "review",
  "delegate_to": {
    "role": "test-runner",
    "intent_template": "run-tests-for-review"
  },
  "on_complete": "continue",
  "timeout": "PT30M"
}

4.7 Failure Transitions

Every transition type supports failure paths:

Field	Type	Description
on_verification_fail	string	Phase to transition to when verification fails.
on_timeout	string	Phase to transition to when the phase times out.
on_escalation	string	Phase to transition to when escalation is triggered.

---

5. Workflow Composition

5.1 Sub-Workflows

A phase MAY reference a sub-workflow instead of directly assigning a worker. The sub-workflow executes as an atomic unit within the parent phase.

{
  "id": "deep-analysis",
  "name": "Deep Analysis",
  "purpose": "Run the full analysis sub-workflow.",
  "sub_workflow": "deep-analysis-workflow",
  "exit_conditions": [
    { "field": "$.sub_workflow.status", "operator": "eq", "value": "completed" }
  ]
}

5.2 Workflow Templates

Workflows MAY define parameterised templates for reuse across multiple job specs.

---

6. Execution Semantics

6.1 Phase Lifecycle

1. Entry: Runtime evaluates entry conditions. If all pass, the phase begins. If any fail, the phase is skipped or the workflow enters a failure path.
2. Setup: Runtime loads knowledge context, applies input guardrails, and assembles the worker harness (prompt, tools, context).
3. Execution: The worker executes with its assigned skills and tools. The runtime monitors for escalation triggers, timeouts, and cost thresholds.
4. Output: Worker produces artifacts. Runtime applies output guardrails.
5. Verification: If a verification gate is defined, the verifier evaluates output against intent (Spec 8).
6. Approval: If an approval gate is defined, the workflow pauses for human decision (Spec 10).
7. Exit: Exit conditions are evaluated. If all pass, the phase transitions to the next phase.

6.2 Checkpoint and Recovery

The runtime MUST persist execution state at phase boundaries. If the runtime crashes or restarts during a phase, it MUST be able to resume from the last completed phase rather than restarting the entire workflow.

6.3 Cost Accumulation

Phase cost includes all worker invocations, tool calls, verification runs, and retries within the phase. Verification cost is tracked separately from execution cost but counts toward the global cost_ceiling.

---

7. Key Design Decisions

Decision	Resolution	Rationale
Workflow routing is deterministic	JSONPath rule evaluation against workflow context	The model never touches routing decisions. Deterministic routing is auditable and predictable.
Phase transitions support branching	Conditional, parallel, loop, handoff, delegation	Real business processes need more than sequential execution. Each transition type solves a specific coordination pattern.
Verification gates are optional	RECOMMENDED but not REQUIRED	Mandating verification for every phase creates unnecessary overhead for simple workflows. The validate tool warns when gates are absent.
Cost tracking is built-in	Part of global constraints	Cost is a first-class concern. Workers that overspend are as much a governance failure as workers that produce bad output.

---

8. Example

A three-phase workflow: design, implement, verify.

{
  "name": "design-implement-verify",
  "version": "1.0.0",
  "domain": "engineering",
  "description": "Three-phase workflow: design the approach, implement the solution, verify the result.",
  "applicable_intent_types": ["operational"],

  "global_constraints": {
    "max_duration": "PT4H",
    "cost_ceiling": { "amount": 25.00, "currency": "USD" }
  },

  "entry_phase": "design",
  "entry_conditions": [
    { "field": "$.intent.status", "operator": "eq", "value": "active" }
  ],

  "phases": [
    {
      "id": "design",
      "name": "Design",
      "purpose": "Analyse the intent and produce a design document.",
      "worker_assignment": { "role": "coordinator", "count": 1, "selection_strategy": "any" },
      "available_skills": [{ "skill_ref": "design-analysis@1.0.0", "required": true }],
      "loaded_context": { "knowledge_layers": ["session", "institutional"] },
      "artifact_production": [{ "type": "design-document", "required": true }],
      "exit_conditions": [
        { "field": "$.artifacts.design-document", "operator": "exists", "value": true }
      ],
      "timeout": "PT1H"
    },
    {
      "id": "implement",
      "name": "Implement",
      "purpose": "Implement the solution according to the design.",
      "worker_assignment": { "role": "implementor", "count": 1, "selection_strategy": "any" },
      "available_skills": [{ "skill_ref": "code-implementation@1.0.0", "required": true }],
      "loaded_context": { "knowledge_layers": ["session", "institutional", "domain"] },
      "artifact_production": [{ "type": "code-change", "required": true }],
      "exit_conditions": [
        { "field": "$.artifacts.code-change", "operator": "exists", "value": true }
      ],
      "timeout": "PT2H"
    },
    {
      "id": "verify",
      "name": "Verify",
      "purpose": "Independently verify the implementation against the intent.",
      "worker_assignment": { "role": "verifier", "count": 1, "selection_strategy": "any" },
      "verification_gate": {
        "gate_id": "implementation-review",
        "blocking": true,
        "on_fail": "reject"
      },
      "exit_conditions": [
        { "field": "$.verification.verdict", "operator": "eq", "value": "pass" }
      ],
      "timeout": "PT30M"
    }
  ],

  "transitions": [
    { "type": "sequential", "from": "design", "to": "implement" },
    { "type": "sequential", "from": "implement", "to": "verify" },
    {
      "type": "loop",
      "from": "verify",
      "to": "implement",
      "condition": { "field": "$.verification.verdict", "operator": "eq", "value": "fail" },
      "max_iterations": 2,
      "on_exhaustion": "escalate"
    }
  ],

  "exit_conditions": {
    "completion_criteria": [
      { "description": "Verification passed.", "field": "$.verification.verdict", "operator": "eq", "value": "pass" }
    ],
    "output_artifacts": [
      { "type": "code-change", "required": true }
    ]
  }
}

---

9. References

• BPMN (Business Process Model and Notation) — Design influence for phase graph concepts. DWS phases are analogous to BPMN activities; transitions are analogous to sequence flows.
• CMMN (Case Management Model and Notation) — Design influence for adaptive, context-driven workflow behaviour. DWS’s conditional transitions and runtime knowledge loading reflect CMMN’s event-driven model.
• Spec 1: Worker Identity — Worker roles referenced in phase assignments.
• Spec 3: Skill Specification — Skills referenced in phase available_skills.
• Spec 4: Intent Artifacts — Workflows execute intents.
• Spec 5: Outcome Artifacts — Workflow phases produce outcomes.
• Spec 8: Verification Framework — Verification gates control phase progression.
• Spec 9: Human-Worker Interaction — Interaction modes defined per phase.
• Spec 10: Approval & Handoff — Approval gates and handoff transitions.
• Spec 11: Events & Telemetry — Workflow lifecycle events.