Skip to content

Workflows

A Sandbox Loom workflow turns an objective into a sequence of bounded, verifiable tasks.

The definition describes what should happen. It does not grant authority by itself: the selected session profile and policy still control every capability.

Validate a workflow

From the repository root:

bin/sandbox-loom workflow check examples/workflow.yml

Expected output:

valid workflow: quickstart-workflow

Preview the task graph

bin/sandbox-loom workflow plan examples/workflow.yml

plan validates the workflow and emits a deterministic dependency order. It does not execute tasks or mutate a sandbox.

Treat the commands as separate review stages:

  • check validates the workflow shape and policy/profile compatibility;
  • plan makes ordering and dependencies visible without side effects;
  • execution performs only the capabilities authorized by the selected policy;
  • verification and checkpoint tasks produce the evidence used for acceptance or escalation.

Authoring and review

Workflow files use the versioned schema at specifications/workflows/v0.1/workflow.schema.json. Add this header to a YAML file for editors that support the YAML language server:

# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json

The repository includes a complete example at examples/workflow.yml:

version: "0.1"
workflow: quickstart-workflow
profile: autonomous-development

tasks:
  - id: inspect
    action: gateway.git.status

  - id: verify
    after: [inspect]
    action: verify
    checks: [test, build, lint]

  - id: checkpoint
    after: [verify]
    action: checkpoint

Validation rules

The validator rejects:

  • missing required workflow fields;
  • unsupported actions;
  • duplicate task IDs;
  • missing task dependencies;
  • dependency cycles;
  • unavailable capability/profile combinations;
  • invalid workflow limits.

Safe composition

YAML is the canonical workflow format because it is reviewable, versioned, and supported by schema-based editor validation.

A Ruby composition DSL is available for application code and produces the same workflow shape. Neither format bypasses policy or creates unrestricted shell access.

The model is broader than autonomous development: future workflow types can reuse the same objective, authority, verification, and evidence boundaries.

Verify all examples

Run the progressive examples matrix from the repository root:

bin/sandbox-loom examples check

The command executes temporary-workspace Ruby examples, plans YAML examples, and confirms that the intentionally invalid workflow is rejected. The complete matrix is maintained in the repository examples/README.md.