Run and manage workflows

Workflow runs preserve progress, so you can leave and return without replaying completed work. Across IDE, CLI, and Web, the run remains connected to its parent conversation while Kiro checkpoints node status, outputs, artifacts, repeat progress, watch cursors, and step sessions at durable boundaries.

A background workflow does not block the main conversation. Kiro can acknowledge the launch, return progress while steps run, inspect the completed run and its artifacts, and synthesize the outcome in the parent chat. The Workflows overview traces one such run end to end.

In Kiro Web, the parent session and run details remain visible together:

• Workflows shows runs, nested nodes, status, elapsed time, agent, model, effort, and step activity.
• Summary shows the synthesized session outcome.
• Files lets you inspect workspace files produced or changed during the run.
• Artifacts shows outputs explicitly exposed by the workflow.

A progress update in the parent chat and a direct message to a selected step serve different purposes. Ask the main agent to interpret progress, resolve a broader issue, or decide what should happen next. Message the step when the guidance applies specifically to that agent's current task.

The channel between the parent chat and a step runs both ways, at any point in the run. A step reports outward through its send_message signals. Guidance reaches the step by either route: message the selected step directly in your client, or tell the main agent in the parent chat what the step should do and it delivers that guidance into the step's session. A running step picks the guidance up on its next turn; a paused step treats it as the reply it was waiting for.

A run reports one of five statuses, and paused covers three different situations that call for different responses. The controls a client offers differ by surface; the statuses, and what moves a run between them, are the same everywhere.

Nodes can also be pending or skipped. Each repeat iteration creates a fresh set of state entries for its body, so the same static node ID can appear once per iteration. Which of these controls each client exposes is listed under Choose the right run control.

A step can ask for information and pause without losing its session context. The step agent signals this by calling send_message with severity warning; Kiro parks the step and run until you reply.

Your reply has to reach the paused step's session. The direct route is to open that step in your client and answer there; the tabs below show where. You can also answer through the parent chat by asking the main agent to pass your answer to the paused step, and it delivers the reply into the step's session for you. A plain message typed into the parent chat without that instruction is a conversation with the main agent, not a reply to the step.

Whichever route you take, the reply lands in the paused step's own session; the parent chat is at most the place you typed it. Three things decide what happens next, and the figure below follows one reply through all of them: the step continues with its history intact; its next send_message signal picks the branch; and only success moves the run on to the next node in a new session. A warning pauses the same session again, and an error ends the run.

The flow above is Kiro's built-in pause when a step asks for input. A recipe author can also make a step explicitly interactive with completion, which keeps the step open after each reply until a condition is met:

{
  "type": "step",
  "id": "triage",
  "agent": "wf-planner",
  "prompt": "Investigate the flaky test and refine a fix plan with the user.",
  "completion": {
    "completionSignal": "success"
  }
}

After each turn, Kiro evaluates completion. If it remains false, the step waits for another message in its session.

Interactive steps cannot run inside parallel, because Kiro cannot park one branch for input while its siblings continue.

Pause is cooperative. Acceptance of a pause request does not mean execution has already stopped. The active agent turn can continue until Kiro reaches the next node boundary. Inspect the run until its status becomes paused before assuming no more agent work is occurring.

A repeat paused by onMaxIterations: "pause" has exhausted its fixed budget. Resume does not add iterations; the repeat reaches the same cap and pauses again. Revise the remaining plan, or stop the run and launch a corrected recipe as a new run.

Use Stop, /workflow cancel, or Ctrl+X only when work must stop immediately. Cancellation can interrupt a step between file operations. Files already changed remain changed. Inspect the workspace and use version control to discard unwanted partial edits before starting again.

CLI can retry all unsuccessful work or a selected failed/aborted node:

/workflow retry <workflowId>
/workflow retry <workflowId> <nodeId>

Kiro resets each retry target to pending and clears its step session, timestamps, captured output, node artifacts, failure metadata, completion metadata, interactive state, and watch state. It reopens terminal ancestors so execution can reach the target while preserving completed sibling work.

Retry does not undo workspace files. Inspect partial edits before retrying. A completed run is not retryable in the current CLI UI; launch the recipe again to create a new run.

Each run has its own workflow ID and state tree. Recipe files do not isolate output paths, Git branches, or worktrees, so two runs can still edit the same checkout or overwrite the same artifact.

• In IDE, use the run list under Workflows in the parent session details.
• In CLI, use /workflow history or /workflow list, then select or pass the workflow ID.
• In Web, open Workflows beside the parent conversation and select a run from the run list.
• Give concurrent runs distinct run_dir and artifact paths.
• Use separate worktrees or workspaces when runs can edit the same files.

Completion is a handoff, not just a status change. The main agent can inspect the run, read its declared artifacts and relevant files, verify the requested evidence, and summarize the result in the parent conversation.

A useful completion summary names:

• the outcome and workflow ID;
• steps completed and any loops or reviews performed;
• files created or changed;
• artifacts and machine-readable verdicts;
• validation performed and anything left unverified.

In Kiro Web, use Summary, Files, and Artifacts to inspect that evidence directly. A recipe or step agent must produce and expose an artifact; not every file created during a run becomes a declared artifact automatically.

A running or paused workflow can replace its remaining top-level plan while preserving nodes that already ran.

• Completed and currently executing work remains immutable.
• If a step is active, Kiro queues the replacement until the next step boundary.
• If no step is active, including while the run is paused, Kiro can apply the replacement immediately.
• The complete revised tree must still pass schema, ID, nesting, step-count, template, agent, and watch validation.
• If a queued replacement fails validation, Kiro rejects it and continues with the original plan.

Who may revise a plan is fixed by the run structure:

Agents use update_workflow for both actions. For ordinary outcomes, a step should still signal through send_message; update_status is for deliberate overrides. Plan revision is an agent/runtime capability and does not imply that every client exposes a manual revision control.

A watch node polls an external resource without spending model turns while the resource is idle. Its handler returns one of three outcomes:

Kiro persists the watch cursor and terminal state with the run, so novelty tracking survives a restart. Across an interruption and recovery, delivery is at least once, so a responder must tolerate a repeated item. If idleTimeoutSec is set, an idle watch ends with a terminal outcome after that duration; without it, the watch can wait indefinitely.

Two handlers are built in. github-pr tracks what it has already reported itself. command runs a program you write once per poll and stores whatever cursor the program returns, so your program decides what counts as new; see Watch anything else with command.

The publish-pr pattern pairs a github-pr watch with a responder inside a repeat; see Publish and respond.

Kiro persists full workflow state after node transitions. Completed steps, recorded terminal outcomes, paused-for-input state, captured outputs, artifacts, and watch cursors survive at their last durable boundary. An interrupted step without a final signal continues in its existing step session instead of replaying its initial prompt as a new step.

A run that still reports running does not accept Resume. Reopen its parent session or monitor and inspect its active step. If it remains running without new output, record the workflow ID and collect client diagnostics before starting a duplicate run; the client has no separate manual "reclaim" control.

Kiro limits repeated failed continuation attempts and fails the step rather than retrying forever. The exact storage layout and process-ownership records are implementation details, not recipe API.

• Recipes support at most 8 levels of nesting and 50 static step nodes.
• Every repeat has a positive maxIterations.
• Repeat conditions run after an iteration, so every repeat executes at least once.
• parallel gives each branch its own context and a join policy (all, allSettled, or any). Kiro starts the branches concurrently; use it for isolation and join semantics rather than assuming a shorter wall-clock time.
• Workflows do not isolate Git branches or create worktrees.
• Client closure and cross-client attachment behavior are not part of the recipe contract documented here.

• Return to Author workflows for the full recipe schema, node types, and template variables.
• Adapt a starting-point graph from Workflow examples.
• Revisit the Workflows overview for how a run relates to the parent chat.