Spec 4: Intent Artifacts

DWS Spec 4: Intent Artifacts

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 1 — Core Primitive Status: Release Candidate Dependencies: Spec 3 (Skill Specification)

---

1. Overview

Intent artifacts are the structured representation of what should be done and why. They replace ad hoc prompting with codified, verifiable, living intent that bridges human direction and worker execution.

An intent artifact captures an objective, its constraints, its success criteria, and its relationships to other intents. It is the unit against which verification (Spec 8) evaluates worker output. Without structured intent, verification has nothing to verify against, and worker output is indistinguishable from unguided generation.

Intent artifacts are the only DWS primitive that crosses the definition-time / runtime boundary. They begin as git-committed definitions and evolve through event-sourced mutations during execution. This dual nature is central to DWS’s model of disciplined-but-adaptive worker execution.

---

2. Intent Artifact Schema

2.1 Common Fields

All intent artifacts share these fields:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "success_criterion": {
      "type": "object",
      "required": ["dimension", "target", "measurement_method"],
      "properties": {
        "dimension": { "type": "string" },
        "target": { "type": ["string", "number"] },
        "measurement_method": {
          "type": "string",
          "enum": ["automated", "human_review", "metric_threshold"]
        },
        "evidence_required": { "type": "boolean", "default": true },
        "blocking": { "type": "boolean", "default": true }
      }
    }
  },
  "type": "object",
  "required": ["id", "type", "objective", "success_criteria", "priority", "owner", "status"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "type": {
      "type": "string",
      "enum": ["strategic", "operational", "constraint"]
    },
    "objective": {
      "type": "string",
      "description": "Clear statement of what should be accomplished and why."
    },
    "constraints": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["description", "enforcement"],
        "properties": {
          "description": { "type": "string" },
          "enforcement": { "type": "string", "enum": ["mandatory", "advisory"] }
        }
      }
    },
    "trade_offs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimension_a": { "type": "string" },
          "dimension_b": { "type": "string" },
          "preference": { "type": "string" },
          "rationale": { "type": "string" }
        }
      }
    },
    "success_criteria": {
      "type": "array",
      "items": { "$ref": "#/$defs/success_criterion" },
      "minItems": 1
    },
    "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
    "owner": { "type": "string", "description": "Human owner responsible for this intent." },
    "assigned_workers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": { "type": "string" },
          "worker_id": { "type": "string" }
        }
      }
    },
    "source_channel": {
      "type": "string",
      "enum": ["manual", "email", "slack", "api", "webhook", "worker", "scheduled"],
      "description": "Channel through which this intent was created. Enables tracking of how work enters the system."
    },
    "sla": {
      "type": "object",
      "properties": {
        "response_time": {
          "type": "string",
          "description": "ISO 8601 duration. Maximum time from intent creation to first worker action."
        },
        "resolution_time": {
          "type": "string",
          "description": "ISO 8601 duration. Maximum time from intent activation to completion."
        },
        "on_breach": {
          "type": "string",
          "enum": ["notify", "escalate", "auto_reassign"],
          "default": "notify"
        }
      },
      "description": "Service level agreement for this intent. See Spec 16 for cost implications."
    },
    "status": {
      "type": "string",
      "enum": ["draft", "review", "approved", "active", "completed", "superseded", "archived"]
    },
    "version": { "type": "string" },
    "base_version": {
      "type": "string",
      "description": "Git commit hash of the approved version. Set on approved->active transition."
    },
    "created_at": { "type": "string", "format": "date-time" },
    "updated_at": { "type": "string", "format": "date-time" }
  }
}

2.2 Relationship Fields

Field	Type	Description
parent_intent	string or null	ID of the parent intent this was decomposed from.
sibling_intents	array of strings	IDs of intents at the same decomposition level.
blocking_intents	array of strings	IDs of intents that must complete before this one can begin.

2.3 Domain Extension Mechanism

Domain-specific fields live in an extensions object keyed by domain name. The base schema validates common fields; extension schemas are registered per domain and validated separately.

{
  "extensions": {
    "engineering": {
      "design_doc_ref": "doc-2026-0451",
      "affected_services": ["auth-service", "user-service"],
      "test_requirements": {
        "unit_coverage_minimum": 0.8,
        "integration_tests_required": true
      }
    }
  }
}

---

3. Intent Type Taxonomy

3.1 Strategic Intent

High-level objectives that decompose into multiple operational intents. Strategic intents are owned by humans and define the “what” and “why” at the broadest level.

Strategic intents MUST have at least one target_outcome. They SHOULD define a decomposition_strategy to guide how they break into operational intents.

3.2 Operational Intent

Specific, assignable units of work with clear success criteria. Operational intents are the level at which workers execute and verification evaluates.

Every operational intent MUST have at least one success_criterion that is testable.

3.3 Constraint Intent

Cross-cutting rules that apply to multiple operational intents. Constraint intents are not executed directly; they are loaded as context that shapes how operational intents are executed.

The applies_to field uses either explicit intent_ids or a pattern expression. Runtimes MUST apply constraint intents to matching operational intents during execution.

3.4 Type Relationships

• Strategic decomposes into one or more Operational intents.
• Constraint applies across one or more Operational intents.
• Operational intents reference their parent Strategic intent via relationships.parent_intent.

---

4. Intent Lifecycle & Versioning

4.1 States

State	Description	Allowed Transitions
draft	Initial authoring.	-> review, -> archived
review	Under review by stakeholders.	-> approved, -> draft
approved	Reviewed and accepted. Ready for execution.	-> active, -> superseded, -> archived
active	Currently being executed by workers.	-> completed, -> superseded
completed	Execution finished. Success criteria evaluated.	-> archived
superseded	Replaced by a newer version.	-> archived
archived	Retained for audit. No longer active.	(terminal state)

4.2 Dual Versioning Model

Pre-execution (git-backed): States draft, review, and approved. Intent artifacts in these states are authored, committed, and reviewed through standard git workflows.

Activation bridge: When an intent transitions from approved to active, the git commit hash becomes the base_version field.

During execution (event-sourced): In the active state, intent artifacts may evolve as verification findings reveal gaps. These mutations are events, not git commits.

4.3 Runtime Mutations

Each mutation during execution is recorded as an intent.mutated event (Spec 11):

{
  "event_type": "intent.mutated",
  "intent_id": "intent-2026-0451",
  "base_version": "abc123def456",
  "mutation": {
    "field_path": "$.success_criteria[2]",
    "previous_value_ref": "evt-2026-0890",
    "new_value": {
      "dimension": "latency",
      "target": "< 200ms",
      "measurement_method": "metric_threshold"
    },
    "cause_type": "verification_finding",
    "cause_ref": "vf-2026-0445"
  }
}

4.4 Reconciliation

When execution completes, the dws reconcile tool proposes a new git commit that updates the intent artifact to reflect runtime learning. This is a deliberate human act. Runtime mutations do not auto-commit.

---

5. Intent Decomposition

5.1 Coverage Assertion

Runtimes SHOULD validate decomposition completeness:

• Every target_outcome in the parent strategic intent MUST be covered by at least one child operational intent.
• Circular dependencies MUST be rejected.

5.2 Dependency Mapping

Operational intents within a decomposition MAY have dependencies. Dependency types follow Spec 7 (Coordination Protocol): hard, soft, and output.

5.3 Recomposition

When all child operational intents reach completed status, the parent’s target_outcomes are re-evaluated against aggregated results. The parent transitions to completed only if all target_outcomes are satisfied.

---

6. Success Criteria Structure

Every operational intent MUST have at least one success criterion with measurement_method set to automated or metric_threshold. Intents with only human_review criteria are valid but SHOULD be flagged during authoring as they create human bottlenecks.

---

7. Intent Authoring Conventions

7.1 Good Intent Artifacts

• Specific objectives. “Reduce P95 latency of /api/users below 200ms” over “improve API performance.”
• Testable success criteria. Every criterion should have a clear pass/fail boundary.
• Explicit constraints. State what workers must NOT do, not just what they should do.
• Trade-off documentation. When the author has made a deliberate trade-off, record it.

7.2 Anti-Patterns

Anti-Pattern	Problem	Fix
Vague objectives	”Make the system better” gives workers no direction.	State a measurable outcome.
Missing constraints	Workers may take unexpected approaches.	Add boundary constraints.
Untestable success criteria	Verification becomes subjective.	Add measurement method and target.
Over-decomposition	Creates coordination overhead.	Match granularity to task complexity.

---

8. Key Design Decisions

Decision	Resolution	Rationale
Intent versioning model	Dual: git-backed pre-execution, event-sourced during execution, reconciled post-execution	Intents must be stable enough for verification but flexible enough for execution.
Success criteria structure	Structured with dimension, target, and measurement method	Freeform prose is too ambiguous for automated verification.
Schema prescriptiveness	Moderate: required common fields, optional domain extensions	Enough structure to enable cross-domain tooling, enough flexibility for diverse domains.

---

9. References

• BDD (Behaviour-Driven Development) — Success criteria structure informed by given/when/then syntax.
• Amazon “Working Backwards” PR/FAQ — Intent-first design: define success before workers begin.
• Spec 3: Skill Specification — Operational intents reference skills via assigned_skill.
• Spec 6: Workflow & Phases — Workflows execute intents through phases.
• Spec 8: Verification Framework — Verification gates evaluate worker output against intent success criteria.
• Spec 11: Events & Telemetry — Intent lifecycle transitions and runtime mutations produce events.
• Spec 16: Cost & Budget — SLA breach actions may have cost implications.