Spec 0: Project Structure

DWS Spec 0: Project Structure & File Format

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 0 — Foundation Status: Release Candidate Dependencies: All specs (defines the file layout that contains them)

1. Overview

This specification defines the file layout, naming conventions, and directory structure for a job spec. It answers the question every implementor asks first: “What files do I create and where do they go?“

1.1 What is a DWS?

A job spec is a complete specification for a digital worker: an AI-backed role with defined identity, skills, workflows, knowledge, and boundaries. It is the structured equivalent of the job description, authority framework, and standard operating procedures that every human employee operates within.

Everything a hiring manager puts in a job specification has a direct equivalent in DWS:

Job Description Concept	DWS Equivalent
Job title and role	Worker identity: name, domain, role classification
Responsibilities and skills	Skills: composable, versioned units of work
Authority and decision rights	Authority level: from escalate-only to fully autonomous
What’s out of scope	Boundaries: explicit negative scope declarations
How work gets done	Workflow: phased process with verification gates
Current assignments	Intents: structured objectives with success criteria
Company policies and context	Knowledge: conventions, constraints, domain references
Performance reviews	Verification: independent evaluation against codified intent

A job spec can be simple (a single worker with one workflow) or sophisticated, with multiple specialist workers coordinating internally. A “Contract Reviewer” job spec might have an analyst worker and a verifier worker under the hood, but from the outside it is one digital worker with a clear mandate.

1.2 File Structure

A job spec is a directory (typically a git repository) containing definition-time artifacts: worker descriptors, skill definitions, workflow configurations, intent artifacts, outcome contracts, and knowledge snapshots. Runtime artifacts (events, live knowledge entries, verification results) live outside the job spec directory in the event store. The job spec directory contains only what humans author and review.

2. DWS Root

A job spec is identified by a jobspec.json manifest file at the root.

2.1 Manifest Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "version", "dws_version"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "DWS name. Lowercase with hyphens."
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Worker definition version (semver)."
    },
    "dws_version": {
      "type": "string",
      "description": "DWS specification version this project targets (e.g., '1.0.0')."
    },
    "description": {
      "type": "string"
    },
    "domains": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Domains this worker covers (e.g., ['engineering', 'content', 'research'])."
    },
    "default_workflow": {
      "type": "string",
      "description": "Name of the default workflow to use when none is specified."
    },
    "lifecycle": {
      "type": "object",
      "properties": {
        "stage": {
          "type": "string",
          "enum": ["draft", "testing", "staging", "production", "deprecated", "retired"],
          "description": "Current lifecycle stage of this worker. See Spec 14."
        },
        "promoted_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp of the last lifecycle stage transition."
        }
      }
    },
    "compliance": {
      "type": "object",
      "properties": {
        "risk_classification": {
          "type": "string",
          "enum": ["minimal", "limited", "high", "unacceptable"],
          "description": "Risk tier per EU AI Act or equivalent framework. See Spec 12."
        },
        "frameworks": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Regulatory frameworks this worker is subject to (e.g., ['eu-ai-act', 'nist-rmf', 'iso-42001'])."
        },
        "human_oversight_required": {
          "type": "boolean",
          "description": "Whether this worker requires human oversight under applicable regulations."
        },
        "audit_retention_days": {
          "type": "integer",
          "minimum": 30,
          "description": "Minimum number of days event records must be retained for audit."
        }
      }
    },
    "budget": {
      "type": "object",
      "properties": {
        "cost_ceiling_per_run": {
          "type": "object",
          "properties": {
            "amount": { "type": "number" },
            "currency": { "type": "string", "default": "USD" }
          }
        },
        "cost_ceiling_per_day": {
          "type": "object",
          "properties": {
            "amount": { "type": "number" },
            "currency": { "type": "string", "default": "USD" }
          }
        },
        "alerts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "threshold_percent": { "type": "number" },
              "action": { "type": "string", "enum": ["notify", "escalate", "pause"] }
            }
          }
        }
      },
      "description": "Budget constraints for this worker. See Spec 16."
    },
    "runtime": {
      "type": "object",
      "properties": {
        "event_store": {
          "type": "string",
          "description": "URI or path for the event store. Implementation-specific."
        },
        "knowledge_store": {
          "type": "string",
          "description": "URI or path for the knowledge store. Implementation-specific."
        }
      }
    }
  }
}

2.2 Minimal Manifest

{
  "name": "contract-reviewer",
  "version": "0.1.0",
  "dws_version": "1.0.0"
}

3. Directory Layout

jobspec-root/
├── jobspec.json                 # Worker manifest (required)
├── workers/                      # Worker descriptors (Spec 1)
│   ├── {worker-name}.json
│   └── ...
├── skills/                       # Skill definitions (Spec 3)
│   ├── {skill-name}.json
│   └── ...
├── workflows/                    # Workflow definitions (Spec 6)
│   ├── {workflow-name}.json
│   └── ...
├── intents/                      # Intent artifacts (Spec 4)
│   ├── strategic/
│   │   └── {intent-name}.json
│   ├── operational/
│   │   └── {intent-name}.json
│   └── constraints/
│       └── {intent-name}.json
├── outcomes/                     # Outcome artifacts (Spec 5)
│   └── {outcome-name}.json
├── knowledge/                    # Knowledge snapshots (Spec 2)
│   ├── conventions/
│   │   └── {convention-name}.json
│   ├── constraints/
│   │   └── {constraint-name}.json
│   └── exports/                  # Exported knowledge snapshots
│       └── {timestamp}.json
├── contracts/                    # Worker-to-worker contracts (Spec 7)
│   └── {contract-name}.json
└── extensions/                   # Domain-specific extensions
    └── {domain}/
        └── ...

3.1 Directory Rules

All directories are OPTIONAL except the root containing jobspec.json.
Directories are created as needed. A job spec with one worker and one workflow does not need empty skills/ or knowledge/ directories.
File names MUST match the name field inside the JSON file. workers/code-reviewer.json MUST contain "name": "code-reviewer".
All JSON files MUST be valid JSON. YAML is not supported in the core spec. Implementations MAY accept YAML and convert to JSON.
Nested subdirectories within workers/, skills/, and workflows/ are permitted for organisational purposes but have no semantic meaning to the runtime. workers/engineering/code-reviewer.json and workers/code-reviewer.json are equivalent.

3.2 Intent Directory Structure

Intents are organised by type because they have different lifecycles:

intents/strategic/ — High-level objectives. Authored by humans, decomposed into operational intents.
intents/operational/ — Assignable work units. May be human-authored or generated by decomposition.
intents/constraints/ — Cross-cutting rules. Applied across operational intents.

This organisation is RECOMMENDED. Implementations MAY use a flat intents/ directory if the job spec is small.

3.3 Knowledge Directory

The knowledge/ directory contains human-authored knowledge entries and exported snapshots.

knowledge/conventions/ — Organisational conventions (coding standards, brand voice, etc.)
knowledge/constraints/ — Organisational constraints (compliance rules, security policies, etc.)
knowledge/exports/ — Snapshots produced by dws reconcile or manual export.

Human-authored knowledge entries in conventions/ and constraints/ are loaded as institutional knowledge at session start. They are the seed knowledge that workers start with before runtime learning begins.

4. File Naming Conventions

Artifact	File Name Pattern	Example
Project manifest	`jobspec.json`	`jobspec.json`
Worker descriptor	`{worker-name}.json`	`code-reviewer.json`
Skill definition	`{skill-name}.json`	`code-review.json`
Workflow definition	`{workflow-name}.json`	`design-implement-verify.json`
Intent artifact	`{intent-name}.json`	`reduce-api-latency.json`
Outcome artifact	`{outcome-name}.json`	`review-report.json`
Knowledge entry	`{entry-name}.json`	`api-retry-convention.json`
Knowledge export	`{ISO-8601-date}.json`	`2026-03-27.json`
Contract	`{contract-name}.json`	`impl-verify-contract.json`

All names MUST be lowercase with hyphens. No underscores, no spaces, no camelCase.

5. Scaffolding with `dws init`

The dws init command creates a minimal valid job spec. It produces the smallest set of files needed to run a single worker through a single workflow.

5.1 `dws init` Output

my-worker/
├── jobspec.json
├── workers/
│   └── worker.json
├── workflows/
│   └── simple.json
└── intents/
    └── operational/
        └── example.json

Four files. One manifest, one worker, one workflow, one intent.

5.2 Default Files

jobspec.json:

{
  "name": "my-worker",
  "version": "0.1.0",
  "dws_version": "1.0.0",
  "description": "A digital worker defined with DWS.",
  "domains": ["general"],
  "default_workflow": "simple"
}

workers/worker.json:

{
  "identity": {
    "name": "worker",
    "version": "1.0.0",
    "domain": "general",
    "role": "implementor",
    "description": "General-purpose digital worker."
  },
  "authority": {
    "level": "supervised",
    "restricted_operations": [],
    "escalation_target": "human"
  },
  "boundaries": {
    "excluded_domains": [],
    "excluded_artifact_types": [],
    "excluded_operations": []
  },
  "model_requirements": {
    "tool_use": true,
    "structured_output": true,
    "min_context_window": 32000,
    "modalities": ["text"],
    "reasoning_capability": "standard"
  },
  "skills": [],
  "tools": [],
  "artifacts": {
    "produces": ["general-output"],
    "consumes": ["general-input"]
  },
  "delegation_rules": [],
  "dependencies": [],
  "communication": {
    "sends": ["response", "notification", "escalation"],
    "receives": ["request", "notification"]
  },
  "escalation_triggers": {
    "confidence_below": 0.6,
    "timeout_exceeded": "PT30M",
    "scope_exceeded": true,
    "conflict_unresolved": true,
    "human_requested": true
  }
}

workflows/simple.json:

{
  "name": "simple",
  "version": "1.0.0",
  "domain": "general",
  "description": "Single-phase workflow. Worker executes the intent and produces output.",
  "applicable_intent_types": ["operational"],

  "global_constraints": {
    "max_duration": "PT2H"
  },

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

  "phases": [
    {
      "id": "execute",
      "name": "Execute",
      "purpose": "Execute the intent objective and produce the required output.",
      "worker_assignment": {
        "role": "implementor",
        "count": 1,
        "selection_strategy": "any"
      },
      "available_skills": [],
      "loaded_context": {
        "knowledge_layers": ["session", "institutional"]
      },
      "artifact_production": [
        { "type": "general-output", "description": "The output specified by the intent.", "required": true }
      ],
      "exit_conditions": [
        { "field": "$.artifacts.general-output", "operator": "exists", "value": true }
      ],
      "timeout": "PT2H"
    }
  ],

  "transitions": [],

  "exit_conditions": {
    "completion_criteria": [
      { "description": "Output produced.", "field": "$.artifacts.general-output", "operator": "exists", "value": true }
    ],
    "output_artifacts": [
      { "type": "general-output", "required": true }
    ]
  }
}

intents/operational/example.json:

{
  "id": "intent-example-001",
  "type": "operational",
  "objective": "Replace this with a clear statement of what should be accomplished and why.",
  "constraints": [
    {
      "description": "Replace with any boundaries on how the objective may be achieved.",
      "enforcement": "mandatory"
    }
  ],
  "success_criteria": [
    {
      "dimension": "completeness",
      "target": "All requirements addressed",
      "measurement_method": "human_review",
      "evidence_required": true,
      "blocking": true
    }
  ],
  "priority": "medium",
  "owner": "your-name",
  "assigned_workers": [
    { "role": "implementor" }
  ],
  "status": "draft",
  "version": "1.0.0",
  "created_at": "2026-04-10T00:00:00Z",
  "updated_at": "2026-04-10T00:00:00Z",
  "relationships": {
    "parent_intent": null,
    "sibling_intents": [],
    "blocking_intents": []
  }
}

6. Minimal Valid DWS

The absolute minimum for a DWS-compliant definition:

Component	Required?	Minimum Count
`jobspec.json`	Yes	1
Worker descriptor	Yes	1
Workflow definition	Yes	1
Intent artifact	Yes (for execution)	1
Skill definition	No	0
Outcome artifact	No	0
Knowledge entries	No	0
Verification gates	No	0
Guardrails	No	0
Contracts	No	0
Hooks	No	0
Approval gates	No	0

A job spec with one worker, one workflow, and one intent is the smallest executable DWS configuration. Skills, knowledge, verification gates, and outcome contracts add value but are not structural requirements.

The minimal job spec is analogous to a new hire on their first day: they have a title and role (worker), a process to follow (workflow), and a task to do (intent). Over time they gain skills, learn company policies (knowledge), and get performance reviews (verification).

6.1 Growth Path

The minimal job spec grows naturally:

Add verification. Add a verification_gate to the workflow phase and a second worker with role verifier. Output is now independently checked.
Add skills. Define skills that the worker can execute. Reference them in the worker descriptor and workflow phase.
Add knowledge. Create convention and constraint entries in knowledge/. These are loaded at session start.
Add outcomes. Define outcome artifacts that specify delivery contracts, channels, and success criteria for worker output.
Add phases. Split the single-phase workflow into design, implement, verify.
Add workers. Specialist workers for different phases (architect, implementor, verifier).
Add domains. Expand from one domain to multiple (engineering, content, research).
Add guardrails. Define input/output guardrails on worker descriptors and reference them in workflow phases.
Add contracts. Formalise expectations between workers with worker-to-worker contracts.
Add approval gates. Require human sign-off at key decision points in the workflow.
Add hooks. Inject cross-cutting concerns (logging, notifications, policy enforcement) at workflow lifecycle points.
Add compliance. Declare risk classification, applicable frameworks, and audit retention in the manifest.

Each step adds capability without requiring a rewrite of what came before.

7. Validation

7.1 `dws validate`

The dws validate tool checks a job spec for structural validity:

Errors (block execution):

Missing jobspec.json
Worker descriptor missing required fields
Workflow references a worker role that no worker descriptor provides
Workflow phase references a skill that no skill definition exists for
Intent artifact missing required fields
Circular dependencies in intent decomposition
Circular dependencies in workflow transitions (without loop transition type and iteration limits)

Warnings (inform but don’t block):

Workflow has no verification gates
Worker has no boundary declarations
Intent has only human_review measurement methods (creates human bottleneck)
Knowledge conventions directory is empty (workers start with no institutional knowledge)
Worker declares skills but no skill definitions exist in skills/

7.2 Cross-Reference Validation

dws validate MUST check referential integrity across files:

Every role referenced in a workflow worker_assignment MUST match at least one worker descriptor’s role field.
Every skill_ref in a workflow’s available_skills MUST match a skill definition in skills/ (by name and version constraint).
Every intent_ref in a verification gate MUST match an intent artifact in intents/.
Every tool_uri marked required: true in a worker descriptor MUST be resolvable at validation time (or flagged as a warning if the tool server is unavailable).
Every guardrail ID referenced in a workflow phase’s input_guardrails or output_guardrails MUST match a guardrail declared in the assigned worker’s guardrails array (Spec 1, Section 2.5).
Every role in a contract’s parties array MUST match at least one worker descriptor’s role field. Every artifact_type in a contract’s artifact_guarantees MUST match a type in the producer worker’s artifacts.produces array (Spec 7, Section 5.4).
Every hook handler referencing a skill_ref MUST match a skill definition in skills/. Every hook handler referencing a tool_uri MUST be resolvable (Spec 11, Section 5.4).
Every approval gate referenced in a workflow phase MUST have valid approvers configured (Spec 10).

8. Git Integration

8.1 Recommended `.gitignore`

# Runtime artifacts (not git-backed)
.dws/
.dws-events/
.dws-knowledge-live/

# Editor and OS files
.DS_Store
*.swp

8.2 Git Tags

Artifact	Tag Format	Example
Project release	`v{major}.{minor}.{patch}`	`v0.1.0`
Worker version	`worker/{name}/v{version}`	`worker/code-reviewer/v1.2.0`
Skill version	`skill/{name}/v{version}`	`skill/code-review/v1.0.0`
Workflow version	`workflow/{name}/v{version}`	`workflow/design-implement-verify/v1.0.0`

8.3 Branch Conventions

DWS does not mandate a branching strategy. However, for projects where intent artifacts go through review:

Intent artifacts in draft or review status MAY live on feature branches.
Intent artifacts in approved status SHOULD be on the main branch.
The base_version field (Spec 4) is set to the git commit hash when the intent is merged to main and transitions to active.

9. Workspace Support

Large organisations often manage multiple digital workers in a single repository. DWS supports this through a workspace manifest.

9.1 Workspace Manifest

A workspace is identified by a dws-workspace.json file at the repository root. It declares the locations of individual job spec directories within the repository.

{
  "workspace": true,
  "dws_version": "1.0.0",
  "members": [
    "workers/contract-reviewer",
    "workers/compliance-checker",
    "workers/due-diligence-analyst"
  ],
  "shared_knowledge": "shared/knowledge",
  "shared_skills": "shared/skills"
}

9.2 Workspace Rules

Each member path MUST contain a valid jobspec.json manifest.
Workers within a workspace MAY reference each other in coordination contracts (Spec 7).
shared_knowledge and shared_skills are optional paths. When declared, all member workers can reference entries from these directories in addition to their own.
Workspace-level validation (dws validate --workspace) checks referential integrity across all members, including cross-worker contract references.

10. Key Design Decisions

10.1 Resolved

Decision	Resolution	Rationale
File format	JSON only in the core spec	JSON Schema validation is native. YAML introduces parser ambiguity. Implementations MAY accept YAML as a convenience layer.
Directory structure	Convention-based, not enforced	Nested subdirectories have no semantic meaning. This keeps the spec simple while allowing organisational flexibility.
Manifest file	Single `jobspec.json` at root	One file to find, one file to validate. Same pattern as `package.json`, `Cargo.toml`, `pyproject.toml`.
Minimum viable job spec	Four files (manifest, worker, workflow, intent)	Low barrier to entry. A working job spec should take minutes to create, not hours.
Multi-worker monorepos	Workspace manifest (`dws-workspace.json`) with member paths	Follows the Cargo workspace and npm workspace pattern. Shared knowledge and skills prevent duplication.
Environment overrides	Lifecycle stages (Spec 14) replace environment-specific config	A worker’s authority levels and tool URIs change based on lifecycle stage (testing vs production), not arbitrary environment names.

11. References

npm package.json — Structural model for the project manifest. Single file at the root, declares name, version, and project metadata.
Cargo workspace layout — Model for multi-project organisation within a single repository.
Terraform file layout conventions — Convention-based directory structure for infrastructure definitions. Similar philosophy: files are organised by convention, not by enforcement.
All DWS specs (1-16) — This document defines where the artifacts from every other spec live on disk.