Skip to main content

​
Playbooks and flows

Playbooks and Flows add a coordination view on top of existing Kheish primitives. They do not introduce a second runtime. Use this model when you want a durable, reviewable procedure that starts normal session runs and then tracks the daemon evidence those runs produce.

​
Model

A Playbook is an immutable, digest-covered manifest version. It describes:
  • the objective
  • expected inputs
  • preconditions
  • roles
  • phases
  • acceptance criteria
  • evidence expectations
  • tool policy hints
  • provider and model defaults
  • capability and credential scope guidance
Tool policy, runtime defaults, and scope fields are declarative governance hints in the manifest. The daemon stores and digests them, but the actual tool surface, route, permissions, capability scope, and credential scope still come from the normal session/run/runtime configuration. Playbook version content is immutable. Its mutable release state lives separately and can be draft, verified, canary, active, or revoked. A Flow is one durable projection of a started Playbook version. It stores correlation data and references to Kheish primitives such as:
  • session_id
  • the root run_id
  • root and sidechain agent ids linked to the root run
  • runs in sidechain sessions spawned from the root run
  • session task ids created by scoped runs or legacy scoped agents
  • pending and historical approval/question ids visible through run state and run events
  • output and debug evidence reachable through the normal run APIs
The Flow status is derived on read from the scoped primitives. It is not persisted on the Flow record. A historical root run can remain interrupted for audit while the Flow projection still reaches a useful terminal state from scoped child work. A failed scoped run or task makes the Flow fail closed instead of reporting success from a root answer alone.

​
Why this is not a workflow engine

Kheish still executes work through sessions and runs. A Flow start wraps a normal SubmitInputRequest, attaches daemon-owned kheish_flow metadata, and schedules the underlying session run through the existing run path. This avoids duplicating:
  • run scheduling
  • approvals and questions
  • background task tracking
  • sidechain agents and mailboxes
  • MCP and tool exposure
  • connector and output routing
  • debug artifacts
  • restart recovery
Flow projections do not retry shell commands, resume processes, schedule child work by themselves, or create a second approval system. They only correlate and summarize daemon primitives that already exist.

​
Release safety

Only startable Playbook versions can start Flows. Startable states are:
  • verified
  • canary
  • active
Publishing into one of those states requires evidence references. Structural validation alone does not make a Playbook verified.

​
Correlation metadata

Flow start reserves the metadata key kheish_flow. Callers cannot provide that key themselves on normal run input. The daemon writes it when starting a Flow so run views and debug evidence can be correlated back to:
  • flow_id
  • playbook_id
  • version
  • digest
  • a daemon-generated correlation nonce
The metadata is for daemon correlation. It is not a prompt feature and should not be used by Playbook authors as user-facing content.

​
Evidence Used

​
Evidence Note

  • Code verified: crates/kheish-daemon/src/playbooks.rs, crates/kheish-daemon/src/state/playbook_workflow.rs, crates/kheish-daemon/src/control_tools/helpers.rs, crates/kheish-daemon/src/control_tools/tasks.rs, crates/kheish-daemon/src/control_tools/bash.rs.
  • CLI/API verified: playbooks ..., flows ..., agents list, runs events, tasks list/output surfaces checked against command and handler code.
  • Daemon live tested for this note: no; deterministic Flow projection tests cover root, sidechain, approvals, and tasks.
  • Provider-specific tested for this note: no; Flow projection is provider-neutral.