durable-workflow-runtime

Files (200)

• SKILL.md
• SKILL.md · delete/
• delete-cli-spec.md · delete/references/
• delete_workflow.py · delete/scripts/
• evals.json · evals/
• SKILL.md · inject/
• inject-cli-spec.md · inject/references/
• inject.py · inject/scripts/
• SKILL.md · pack/
• pack-cli-spec.md · pack/references/
• pack.py · pack/scripts/
• bridge-cli-spec.md · references/
• environment-setup.md · references/
• host-loop.md · references/
• index.md · references/
• observation-format.md · references/
• prompt-asset-template.md · references/
• prompt-placeholder-spec.md · references/
• runtime-layout.md · references/
• skill-host-python-spec.md · references/
• step-contract-spec.md · references/
• workflow-authoring-guide.md · references/
• workflow-input-contract-spec.md · references/
• workflow-selection-spec.md · references/
• SKILL.md · register/
• register-cli-spec.md · register/references/
• register.py · register/scripts/
• requirements.txt
• bridge.py · scripts/
• host_io.py · scripts/
• workflow_shortcut_skill.py · scripts/
• SKILL.md · setup/
• setup-cli-spec.md · setup/references/
• setup.py · setup/scripts/
• test_durable_workflow_runtime.py · tests/
• test_runtime_hardening.py · tests/
• workflow-binding.json
• SKILL.md · workflow-creator/
• workflow-creator-cli-spec.md · workflow-creator/references/
• create_workflow.py · workflow-creator/scripts/
• __init__.py · workflow-runtime/adapters/
• skill_host.py · workflow-runtime/adapters/
• __init__.py · workflow-runtime/runtime/
• artifacts.py · workflow-runtime/runtime/
• dependency_preflight.py · workflow-runtime/runtime/
• engine_graphbuilder.py · workflow-runtime/runtime/
• errors.py · workflow-runtime/runtime/
• history.py · workflow-runtime/runtime/
• limits.py · workflow-runtime/runtime/
• models.py · workflow-runtime/runtime/
• module_loader.py · workflow-runtime/runtime/
• persistence.py · workflow-runtime/runtime/
• redaction.py · workflow-runtime/runtime/
• retention.py · workflow-runtime/runtime/
• telemetry.py · workflow-runtime/runtime/
• transport.py · workflow-runtime/runtime/
• validation.py · workflow-runtime/runtime/
• verifier_runner.py · workflow-runtime/runtime/
• workflow_identity.py · workflow-runtime/runtime/
• README.md · workflow-runtime/templates/workflow_skeleton/
• …and 140 more

SKILL.md (first lines)

# Durable Workflow Runtime

This skill is an explicit entrypoint into the bundled runtime. Once it is
invoked, treat that as the decision to use the runtime contract instead of
re-evaluating applicability inside the conversation.

## Invocation contract

- If the first token after `/durable-workflow-runtime` is a reserved wrapper
  command, handle that command and stop. Do not call `bridge.py start`.
- If this skill is loaded for a normal workflow run, operate through the
  shipped runtime and bridge contract.
- The remaining selection is which published `workflow_id` to start, not
  whether the skill should keep governing the task.
- Keep workflow choice explicit when possible; otherwise rely on the configured
  default binding.

## Reserved wrapper commands

These tokens are wrapper commands, not `workflow_id` values:

- `setup`
  Install slash-only skills from `workflow-shortcuts/` and the
  `workflow-creator` companion into `~/.agents/skills` and `~/.claude/skills`.
  Follow `setup/SKILL.md` and run `setup/scripts/setup.py`. Do not start a
  workflow afterward unless the user separately asks to run one.

## Primary contract

If you review only one thing in this skill, review this loop:

```text
start -> yield -> host executes prompt -> Observation -> resume -> ... -> done
```

This loop is the product. Everything else in this skill exists to protect this
handoff from drifting into free-form chat behavior.

Ownership in that loop:

- `start`
  the host calls `bridge.py start`
- `yield`
  the runtime returns a `response.json` that asks the host to execute one step
- `Observation`
  the host's only valid structured reply after a yielded step
- `resume`
  the host sends that `Observation` back through `bridge.py resume`
- `done`
  the runtime, not the host, decides the workflow is terminal

Do not blur these two namespaces:

- `response.kind`
  runtime-to-host control signal: `yield | done | error`
- `Observation.status`
  host-to-runtime execution result: `succeeded | failed | blocked | partial`

They are not interchangeable. The host never emits `done`; the runtime never
emits `succeeded`.

## Default reading boundary

Read only this whitelist before `bridge.py start` succeeds:

- `workflow-binding.json`
- `scripts/bridge.py`
- `references/bridge-cli-spec.md`
- `references/host-loop.md`
- `references/observation-format.md`
- `references/index.md` only when you need the concrete skill-root layout
- `references/workflow-selection-spec.md` only when choosing a published
  `workflow_id`

Do not read anything under `workflow-runtime/workflows/` before start for
normal execution, including workflow-specific `references/flowchart.md`,
`contract.py`, `policy.py`, `state.py`, `verifiers.py`,
`graphbuilder_runtime.py`, or workflow prompt assets. Those are allowed only
when the task is explicitly about authoring or debugging workflow internals.

Treat verifier logic and workflow business references as runtime-owned
implementation detail by default. The host agent normally does not need them to
execute or resume a workflow correctly.

## Keep the layers separate

- `runtime`: owns state, pause/resume, branch selection, and terminal states
- `workflow`: owns internal step contracts, prompts, policy, and verifier logic
- `skill wrapper`: only routes into the skill-local bridge/runtime
- `host agent`: only executes the current prompt and returns an observation

If these blur together, the host agent will start improvising branch decisions
and step semantics in chat, which defeats the whole point of the runtime.

## First moves

1. If the invocation is `/durable-workflow-runtime setup` or
   `durable-workflow-runtime:setup`, follow `setup/SKILL.md`, run
   `setup/scripts/setup.py`, report the link result, and stop.
2. Treat any other skill invocation as the decision to use the bundled
   runtime.
3. Check whether this skill bundle already has `scripts/bridge.py`,
   `workflow-binding.json`, and the wrapper entry. If you need the concrete
   install path for the current environment, read `references/index.md`
   instead of assuming a Codex-specific directory layout.
4. Read `references/index.md`, then start with interface-level spokes only.
5. If the bridge or bundled runtime does not exist yet, say so explicitly and
   switch to design or implementation guidance instead of pretending the loop
   can already run.
6. If the caller needs to choose a workflow, use the published wrapper catalog
   in `workflow-binding.json` and read
   `references/workflow-selection-spec.md` for the exact selection contract.
7. For normal execution, use the inlined `start/resume` loop below. The
   reference docs are for examples and edge cases, not for the core path.

## Core execution loop

This is the minimum contract the host agent should follow without leaving this
file.

From onesmash/slm-as-harness, MIT.

More from onesmash/slm-as-harness