workflow-authoring

Workflow Authoring Reference

Deployment & reload

• Bundled templates load from templates/ next to the server's build/ (i.e. ${CLAUDE_PLUGIN_ROOT}/templates) — once, at server boot. Editing them does NOT hot-reload a running server.
• Load order (later overrides earlier by workflow name): bundled templates/ → ~/.claude/workflows/ → project .claude/workflows/.
• ~/.claude/workflows/ and the project dir ARE fs.watch'ed; ANY .yaml change there triggers a FULL reload that also re-reads bundled templates. Hot-reload trick after editing bundled templates (no server restart): echo "# t" > ~/.claude/workflows/_trigger.yaml && sleep 1 && rm ~/.claude/workflows/_trigger.yaml, then verify via list (state counts change).
• Active sessions keep their definition snapshot; only NEW start() sessions see reloaded workflows.

State Types

prompt (default) — Agent reads the prompt and acts. Standard behavior.

exec — Engine runs a shell command automatically. Agent doesn't participate.

run_tests:
  type: exec
  command: "npm test"
  cwd: "{{context.cwd}}"
  timeout: 30000
  env:
    CI: "true"
  on_success: analyze
  on_error: fix
  success_prompt: "Tests passed:\n{{stdout}}"
  error_prompt: "Tests failed (exit {{exit_code}}):\n{{stderr}}"
  context_set:
    last_test_output: "{{stdout}}"

• env: — extra environment variables (map; values are templates), merged over the server's env
• context_set: — after the action succeeds, render each value with the action result vars and store it in session context (e.g. last_test_output above becomes {{context.last_test_output}} in later prompts). Skipped entirely on failure.

fetch — Engine makes an HTTP request automatically.

check_api:
  type: fetch
  url: "http://localhost:8888/ping"
  method: GET
  timeout: 5000
  headers:
    Authorization: "Bearer {{context.token}}"
  body: '{"q": "{{context.query}}"}'
  retry:
    max: 60
    interval: 500
  on_success: ready
  on_error: wait
  success_prompt: "API ready: {{body}}"
  error_prompt: "Not responding: {{error}}"