Agent Skills › spinabot/brigade › taskflow

taskflow

GitHub

TaskFlow用于跨多个分离任务执行持久化工作流，保持单一所有者上下文。适用于多步后台任务、等待外部依赖及需状态持久化的场景。管理流程身份、子任务链接、版本冲突安全及生命周期状态，不包含业务逻辑。

skills/taskflow/SKILL.md spinabot/brigade

触发场景

需要跨多个步骤或长时间运行的后台任务任务需要等待子代理或外部系统响应需要在重启后恢复工作或保持状态持久化

安装

npx skills add spinabot/brigade --skill taskflow -g -y

更多选项

不安装直接使用

npx skills use spinabot/brigade@taskflow

指定 Agent (Claude Code)

npx skills add spinabot/brigade --skill taskflow -a claude-code -g -y

安装 repo 全部 skill

npx skills add spinabot/brigade --all -g -y

预览 repo 内 skill

npx skills add spinabot/brigade --list

SKILL.md

Frontmatter

{
    "name": "taskflow",
    "metadata": {
        "brigade": {
            "emoji": "🪝"
        }
    },
    "description": "Use when work should span one or more detached tasks but still behave like one job with a single owner context. TaskFlow is the durable flow substrate under authoring layers like Lobster, ACPX, plugins, or plain code. Keep conditional logic in the caller; use TaskFlow for flow identity, child-task linkage, waiting state, revision-checked mutations, and user-facing emergence."
}

TaskFlow

Use TaskFlow when a job needs to outlive one prompt or one detached run, but you still want one owner session, one return context, and one place to inspect or resume the work.

When to use it

Multi-step background work with one owner
Work that waits on detached ACP or subagent tasks
Jobs that may need to emit one clear update back to the owner
Jobs that need small persisted state between steps
Plugin or tool work that must survive restarts and revision conflicts cleanly

What TaskFlow owns

flow identity
owner session and requester origin
currentStep, stateJson, and waitJson
linked child tasks and their parent flow id
finish, fail, cancel, waiting, and blocked state
revision tracking for conflict-safe mutations

It does not own branching or business logic. Put that in Lobster, acpx, or the calling code.

Current runtime shape

Canonical plugin/runtime entrypoint:

api.runtime.tasks.flow
api.runtime.taskFlow still exists as an alias, but api.runtime.tasks.flow is the canonical shape

Binding:

api.runtime.tasks.flow.fromToolContext(ctx) when you already have trusted tool context with sessionKey
api.runtime.tasks.flow.bindSession({ sessionKey, requesterOrigin }) when your binding layer already resolved the session and delivery context

Managed-flow lifecycle:

createManaged(...)
runTask(...)
setWaiting(...) when waiting on a person or an external system
resume(...) when work can continue
finish(...) or fail(...)
requestCancel(...) or cancel(...) when the whole job should stop

Design constraints

Use managed TaskFlows when your code owns the orchestration.
One-task mirrored flows are created by core runtime for detached ACP/subagent work; this skill is mainly about managed flows.
Treat stateJson as the persisted state bag. There is no separate setFlowOutput or appendFlowOutput API.
Every mutating method after creation is revision-checked. Carry forward the latest flow.revision after each successful mutation.
runTask(...) links the child task to the flow. Use it instead of manually creating detached tasks when you want parent orchestration.

Example shape

const taskFlow = api.runtime.tasks.flow.fromToolContext(ctx);

const created = taskFlow.createManaged({
  controllerId: "my-plugin/inbox-triage",
  goal: "triage inbox",
  currentStep: "classify",
  stateJson: {
    businessThreads: [],
    personalItems: [],
    eodSummary: [],
  },
});

const classify = taskFlow.runTask({
  flowId: created.flowId,
  runtime: "acp",
  childSessionKey: "agent:main:subagent:classifier",
  runId: "inbox-classify-1",
  task: "Classify inbox messages",
  status: "running",
  startedAt: Date.now(),
  lastEventAt: Date.now(),
});

if (!classify.created) {
  throw new Error(classify.reason);
}

const waiting = taskFlow.setWaiting({
  flowId: created.flowId,
  expectedRevision: created.revision,
  currentStep: "await_business_reply",
  stateJson: {
    businessThreads: ["slack:thread-1"],
    personalItems: [],
    eodSummary: [],
  },
  waitJson: {
    kind: "reply",
    channel: "slack",
    threadKey: "slack:thread-1",
  },
});

if (!waiting.applied) {
  throw new Error(waiting.code);
}

const resumed = taskFlow.resume({
  flowId: waiting.flow.flowId,
  expectedRevision: waiting.flow.revision,
  status: "running",
  currentStep: "finalize",
  stateJson: waiting.flow.stateJson,
});

if (!resumed.applied) {
  throw new Error(resumed.code);
}

taskFlow.finish({
  flowId: resumed.flow.flowId,
  expectedRevision: resumed.flow.revision,
  stateJson: resumed.flow.stateJson,
});

Keep conditionals above the runtime

Use the flow runtime for state and task linkage. Keep decisions in the authoring layer:

business → post to Slack and wait
personal → notify the owner now
later → append to an end-of-day summary bucket

Operational pattern

Store only the minimum state needed to resume.
Put human-readable wait reasons in blockedSummary or structured wait metadata in waitJson.
Use getTaskSummary(flowId) when the orchestrator needs a compact health view of child work.
Use requestCancel(...) when a caller wants the flow to stop scheduling immediately.
Use cancel(...) when you also want active linked child tasks cancelled.