workflow

Workflow Skill

Use this skill when a job is repeatable, scheduled, event-driven, or has several durable phases. A Workflow is the reusable HOW. Workflow runs are durable records, not Sessions. A Workflow invocation never creates, links, transitions, approves, or mutates a Todo. For deliberately tracked one-off work, use a Todo or delegate_task; for a quick untracked question, use spawn_session.

Names and discovery

• The public workflow name is the stable agent-facing command name. It must be unique kebab-case, such as release-candidate-review. Do not use a display title as an identifier.
• Call list_workflows to discover definitions, then get_workflow with the returned workflowId when you need the full graph and current version.
• Treat a definition's version as editable configuration. Each run freezes its own definition snapshot and invocation input, so later edits do not rewrite run history.

Create a workflow

Prefer the SOP authoring shape for a normal ordered procedure. Use the raw graph only when you need branches, gates, bounded loops, or other graph-level options.

1. Design explicit phases and acceptance evidence. A strong default is PLAN -> IMPLEMENT -> VERIFY, with different employees or engines where independent review matters.
2. Call plan_workflow with an SOP to compile and inspect it without saving:

{
  "sop": {
    "id": "release-candidate-review",
    "name": "release-candidate-review",
    "title": "Release candidate review",
    "wakeUp": { "kind": "manual" },
    "steps": [
      { "id": "plan", "employee": "a-lead", "role": "PLAN", "instruction": "Produce an implementation plan and risks." },
      { "id": "implement", "employee": "a-builder", "role": "IMPLEMENT", "instruction": "Implement the approved plan and report artifacts." },
      { "id": "verify", "employee": "a-reviewer", "role": "VERIFY", "instruction": "Verify the result against the acceptance criteria." }
    ]
  }
}

1. Call validate_workflow with the same sop or raw definition. Fix every structured validation error.
2. Call create_workflow. Record the returned definition id, canonical name, and version.
3. For an edit, read the current definition first and call update_workflow with workflowId, sop or patch, and expectedVersion. Never assume a stale version is safe to overwrite.