Workflow nodes

A workflow is a list of nodes connected by dependsOn. Add one only when the work needs hand-offs, checks, approvals, deployment or resuming from a failed step.

Node shape

{
  "key": "implement",
  "type": "ai",
  "name": "Implement and self-test",
  "dependsOn": ["understand"],
  "inputs": [],
  "outputs": [],
  "capabilities": {},
  "config": { "prompt": "…", "timeoutSeconds": 3600 },
  "retry": { "maxAttempts": 2 }
}

Field	Notes
key	Starts with a letter; letters, digits, _ and -; up to 64 characters; unique in the workflow
type	One of the node types
name	Display name
dependsOn	Keys of the nodes that must finish first
inputs, outputs	Declared hand-offs. See Hand-offs and routing
capabilities	What this node may use; a subset of the plugin's. See Capabilities
config	Type-specific settings
retry.maxAttempts	1 to 5

Rules

• The graph is built from dependsOn only and must have no cycles. Use retries and failure policy for rework, not back edges.
• A workflow has 1 to 100 nodes. The client's plugin editor handles up to 30.
• ai and ai_review nodes need config.prompt. config.timeoutSeconds is 60 to 86,400 (default 3,600). When time runs out, the run stops, saves the timeout, and follows the node's retry policy.
• Nodes must not name a specific machine (runnerId, hostId, clientId, machineId, endpoint). Use runner tags in the binding.
• A personal workflow needs at least one ai or ai_review node and a publish node.

Node types

Personal and organization workflows

type	Runs on	Use it for
ai	A harness (runtime) on a runner	Analysis, writing, coding, using Skills and MCP
ai_review	A separate harness route	An independent AI review. A node can't approve its own work
human_review	A person	Business review or acceptance. config.action defaults to uat; config.summary tells the reviewer what to check
publish	Hub	Closes the run and records the delivery receipt. In local debugging it only marks the run finished

Organization workflows only

Use these only for organization engineering or deployment processes. They need organization review and a project binding.

type	Runs on	Use it for
spec	A person	Confirm the requirement baseline
approval	A person	Authorize a high-risk step
quality	A clean runner workspace	Build, test and quality gates. See Command nodes
script	A clean runner workspace	A controlled command with recorded evidence
tool	Hub's trusted tool registry	Built-in tools such as http_check and notify
merge	Hub or runner	Merge after the policy is met
deploy	Runner	Deploy to the environment set in the binding
deploy_chain	Hub	Deploy through an environment chain with checks, acceptance and rollback
validate	Hub	Check artifacts against declared rules
condition	Hub	Branch on run inputs

Command nodes

quality and script share one shape. Each command is an argv array, run directly without a shell.

{
  "key": "build",
  "type": "quality",
  "name": "Build and test",
  "dependsOn": ["implement"],
  "config": {
    "commands": [
      { "name": "Install", "argv": ["js:install"], "timeoutSeconds": 600 },
      { "name": "Build",   "argv": ["js:build"],   "timeoutSeconds": 600 },
      { "name": "Test",    "argv": ["js:test"],    "timeoutSeconds": 900 }
    ]
  },
  "retry": { "maxAttempts": 2 }
}

• js:install, js:ci, js:build, js:test and js:type-check pick the real command from the repository's package manager or lockfile.
• The working directory must be a relative path inside the repository.
• Quality nodes also check change hygiene by default: lockfiles from another package manager, build output and unusually large files.

In chat vs. as a task

Using a workflow plugin with / in a normal chat applies its method and AI node instructions to that chat. It does not run scripts, approvals, merges or deployment. To run the real nodes, approvals and recovery, create a task and choose the workflow.

In a task, each AI node's instructions, tool calls and output stream into the same conversation. Human confirmations happen in the chat; without an approval, later nodes don't run. The workflow's node routes choose the agent, so users don't pick one agent for every node.

harness harnesses runtime runtimes 底座