taskflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# TaskFlow

Manage long-running task flows across turns with three grouped tools — `taskflow_flow`, `taskflow_step` and `taskflow_inspect`:
state is persisted to SQLite and supports optimistic locking, step dispatch,
waiting, and resume. Mirrors the API surface of openclaw managedFlows
(createManaged / runTask / setWaiting / resume / finish / fail / requestCancel /
getTaskSummary).

## When to use

- A multi-step job needs its progress tracked across turns (steps, results, status).
- A step should be dispatched to a subagent session and its result written back
  into the flow state once it completes.
- Multiple writers (main session, concurrent sub-tasks) modify the same flow at
  once, requiring conflict detection instead of silent overwrite.

## Tool overview

- `taskflow_flow(action="create", flow_id, description, initial_state)`: create a flow with
  initial revision=1 and status running. Ceilings (refused as `Error:` text):
  at most 20 steps per flow (`TASKFLOW_INFRA["max_steps_per_flow"]`) and at most
  20 ACTIVE flows per session (`max_flows_per_session`; finished/cancelled flows
  release their slot) — close flows with `taskflow_flow(action="finish")` / `taskflow_flow(action="cancel")`
  before creating more.
- `taskflow_step(action="run_task", flow_id, task, label, depends_on, expected_revision,
  validation_criteria, retry_policy, response_schema, expected_params,
  input_bindings, file_deps, judge_criteria, judge_model, functional_role,
  step_model, step_timeout_seconds, priority)`:
  register a step and dispatch a detached subagent session (through the existing
  spawn entry); `child_session_key` is persisted. `validation_criteria` records
  natural-language acceptance criteria on the step (the step judge uses them at
  resume); `retry_policy` opts the step into failure-aware re-dispatch by
  `taskflow_step(action="wait_all")`. The expectation side of a step is declared here:
  `response_schema` (JSON Schema the child's structured output must satisfy — it
  is handed to the child as its output contract and validated again on resume),
  `judge_criteria` + `judge_model` (semantic acceptance criteria and an optional
  judge model), `expected_params` (structured inputs, recorded for the report),
  and `input_bindings` (e.g. `{"target_files": "step-1.structured_result.files"}`
  — upstream structured values appended to this step's task as an
  `## Input parameters` block), `file_deps` (project-relative source files
  whose changes should trigger a re-verification of this step), and execution
  metadata: `functional_role` (researcher / executor / reviewer / librarian /
  general), `step_model`, `step_timeout_seconds`, `priority`. `depends_on` is a list of
  prerequisite step ids (e.g. `["step-1"]`): while dependencies are unmet the
  step is recorded as `blocked` and is not dispatched; once every dependency is
  `done` it is dispatched immediately and recorded as `dispatched`. When the
  child session completes, its result flows back automatically through the
  existing announce/settle-wake pipeline — do not poll; once the result arrives,
  inject it with `taskflow_step(action="resume")`.
- `taskflow_step(action="dispatch", flow_id, step_ids, expected_revision)`: batch-dispatch one
  or more steps that are currently `ready` (dependencies satisfied but not yet
  dispatched). Use it to dispatch independent steps in parallel, or to dispatch
  steps unlocked by `taskflow_step(action="resume")`. If any id is unknown, is already
  `dispatched`/`done`, or still has unmet dependencies, the whole batch is
  rejected — nothing is dispatched and no state changes; if a dispatch fails
  mid-batch, the steps already dispatched successfully are persisted first and
  the failures are reported.
- `taskflow_step(action="update_steps", flow_id, steps, expected_revision)`: full-replace the
  flow's steps list (like `todowrite` for TaskFlow). Pass the COMPLETE list;
  each step is an object with `step_id`, `task`, `depends_on`, `status`
  (`ready | blocked | dispatched | done | failed | skipped | cancelled`). Use
  it to add, remove, reorder, or
  rewrite steps. New steps must be `ready`/`blocked` — dispatch still goes
  through `taskflow_step(action="dispatch")`. A `dispatched` step keeps its
  `child_session_key` and cannot be downgraded to `ready`/`blocked` (its task
  may change, but the running child keeps the old task). A `done` step cannot
  change its task/`depends_on`/status. Removing a `dispatched` step whose
  child is still running succeeds with a non-blocking `Warning:` — kill the
  child or settle it first. Terminal flows reject the call.
- `taskflow_step(action="wait_all", flow_id, timeout_seconds, poll_interval_seconds)`: bounded
  polling that waits for the child sessions of all `dispatched` steps in this
  flow to settle. It only checks child sessions dispatched by this flow and does
  not wait on unrelated sessions, so it never gets stuck behind other background
  tasks. Returns the settle status of each step and prompts you to call
  `taskflow_step(action="resume")` for each completed child session.
- `taskflow_flow(action="set_waiting", flow_id, wait_reason, expected_revision)`: set the flow
  to waiting and record the wait reason.
- `taskflow_step(action="resume", flow_id, child_session_key, result, expected_revision,
  token_usage, validation_criteria, structured_result, step_outcome, auto_dispatch)`:
  inject the child-session result into the flow state and return to running.
  Idempotent: resuming again with the same (child_session_key, result) does not
  inject a second time, and the revision does not change.

  Two-tier quality gate, both tiers opt-in per step and chained:

  * **Tier 1 — structure.** When the step declares `response_schema`, the result
    (`structured_result` when you pass it, else parsed from `result`) is
    validated against that schema. The verdict is recorded on the result entry
    (`structured_result`, `schema_validated`, and the pairing key `step_id`). A
    failure is a failure signal like any other: it re-dispatches under the
    step's `retry_policy` (`schema_error` is the retry type) and **never** spends
    a judge call; with no retry budget left the step is marked `failed`.
  * **Tier 2 — semantics.** When the step declares `judge_criteria` (or the
    legacy `validation_criteria`), an auxiliary-LLM step judge reviews the
    result — the validated `structured_result` when there is one, else the
    result text — and returns pass / retry / block: `retry` re-dispatches within
    the step's retry budget (`STEP_JUDGE["max_retries"]`, default 2) with the
    judge's guidance appended to the replacement task, and `block` (or an
    exhausted budget) marks the step `blocked`. A Tier 1 pass does **not** skip
    Tier 2: a structurally valid result can still be semantically wrong.

  `step_outcome` (`success` / `failure` / `partial` / `skipped`) lets the caller
  state how the child run ended; it outranks both tiers. `failure` marks the step
  `failed` without calling the judge, `skipped` marks it `skipped`, and
  `success` / `partial` are recorded while the gates still run. The judge is
  fail-open — when it is disabled or unavailable the step is marked `done`.
- `taskflow_flow(action="finish", flow_id, summary, expected_revision)`: mark done (terminal).
  Gated, fail-open: every step must be `done` or `blocked`, no step may be
  `blocked`, and the flow's evidence must have no failing/stale row.
- `taskflow_flow(action="fail", flow_id, reason, expected_revision)`: mark failed (terminal).
- `taskflow_flow(action="cancel", flow_id, reason, expected_revision)`: cancel the flow (terminal).
- `taskflow_inspect(action="summary", flow_id)`: read-only readback of status, revision,
  child_session_key, steps, and results; also the re-read entry point after a conflict.
- `taskflow_inspect(action="progress", flow_id)`: read-only progress report (user-facing):
  completion percentage, per-status counts, the first 3 pending steps, estimated
  remaining time based on the `dispatched_at` intervals of completed steps, plus
  the wait reason and the number of injected results. Changes no state; use
  `taskflow_inspect(action="summary")` when you need raw steps/results or the latest revision.
- `taskflow_flow(action="budget", flow_id, budget_action, token_budget, expected_revision)`:

From lasertsole/sherry_agent, MIT.

More from lasertsole/sherry_agent