Workflows

A workflow is a plan for a team of agents: which agents do the work, in what order, with which loops and reviews, run by Kiro in the background while you keep talking in the main chat. Workflows arrived on September 30, 2026 in the IDE (1.2), CLI V3 (2.26.0), and Kiro Web, as an opt-in feature.

Two other things in Kiro share the name and are not this. The built-in workflow choices the IDE shows when you start a session are a different feature, and Kiro Crew has its own Python-script Workflows. This page covers declarative agent orchestration in the shared Kiro runtime.

What is a workflow?

A workflow is a graph of nodes. Kiro’s docs boil it down to five ideas:

• Step. One agent runs in its own session with its own context. A step cannot read another step’s session. Whatever it needs from earlier work arrives through an explicit handoff.
• Handoff. Either the captured output (the step’s final message) or a declared artifact (a file the step wrote) is passed to a later step through a template variable in its prompt.
• Branch and join. Independent agents look at the same work in parallel, and a join policy decides how their results combine.
• Loop. A group of steps repeats until a stop condition matches or a safety cap is reached.
• Wait. The run watches a pull request, or anything a script of yours can check, without spending model turns while nothing changes.

The run is written down as a recipe, a JSON or YAML tree with a name, optional inputs, and a steps array. The node types are step, sequence, repeat, parallel, and watch. Values flow between steps as templates such as {{task}} for a launch input, {{previous.output}} for the last sibling’s output, and {{artifacts.report}} for a file a prior step registered.

You rarely start by writing one. Describe the outcome in the parent chat, say how much structure and review you want, and Kiro proposes a workflow, names its steps and agents, and launches it. Save the definition under .kiro/workflows/ once it is worth repeating. Kiro generates recipes in JSON; YAML works too.

Why it exists

Some work is too big for one session: requirements, design, implementation, independent review, validation. Doing it all in one conversation means you supervise every stage, and the context fills with reasoning and tool output from stages that are already finished.

Workflows fix three things at once. The runtime runs each step in turn, so you are not the one reminding the agent what comes next. Each step starts with fresh context, so a reviewer judges the work without inheriting the coder’s reasoning, which is what makes the review independent. And the run happens in the background, so even a small investigation keeps its noise out of the main chat while you keep working.

How it works

Turning it on. Workflows are opt-in in every client, and the switch is per client:

Client	Where	Setting
IDE	Agent Focus → Workspace Configuration → Workflows → enable, then start a new chat session	kiroAgent.workflows.enabled
CLI V3	/settings → Features → Workflows, then exit and restart Kiro CLI	chat.enableWorkflows
Web	Settings → Workflows → Enable workflows	(toggle)

If the Workflows option is not there, the feature has not reached your account yet. The CLI needs the restart because workflow commands are decided when the process starts.

Starting a run. In the IDE and in Web you ask Kiro in the chat. In the CLI you can also launch a saved recipe directly with /workflow run; if you leave out a declared input, Kiro opens a form to collect it. A recipe is the same file in all three clients.

Following a run. The parent chat and every step stay connected both ways. A step reports outward by calling send_message: severity success completes the step, warning pauses the step and the run until you answer, error fails it, and info is a progress note. You can message a step directly or tell the main agent what the step should do and it delivers the guidance.

Client	Inspect	Controls
IDE	Workflows area above the parent chat; select a step to open its Workflow step tab	Pause, Resume, Stop
CLI	/workflow history, a full-screen monitor, /workflow status <id>	Pause, Resume, Stop, Retry failed or aborted work
Web	Workflows, Summary, Files, and Artifacts beside the chat	Pause, Resume, Stop; Retry when a finished run has retryable failed nodes

A run reports one of five statuses: running, paused, completed, failed, or aborted. Pause is cooperative: it takes effect at the next node boundary, so check that the status actually reads paused before assuming the agent has stopped. Kiro checkpoints the run at node boundaries, so a reconnect does not replay finished work, and completed steps stay intact even when the agents revise the rest of the plan.

Recipes, and where they come from. Project recipes live in .kiro/workflows/ as *.workflow.json, *.workflow.yaml, or *.workflow.yml. Personal recipes go in ~/.kiro/workflows/. Recipes also arrive synchronized for your account, and a set is bundled with Kiro. When names collide, the order is project, then user, then synchronized, then bundled, and an invalid higher recipe does not hide a valid lower one. Web accepts one upload at a time under Settings → Workflows, or a whole .kiro/workflows/ folder through Configuration Sync.

The bundled recipes. Kiro ships three its own team uses. investigate is one read-only step that writes a cited report. feature-pipeline moves through requirements, a design and review loop, a plan, an implement and review loop (two reviewers on different models, merged by an aggregator), and a final validation against the requirements. publish-pr opens a pull request, waits on it without spending model turns, and responds to feedback until the PR is merged or closed. Name one and hand it the inputs. The docs are clear that bundled recipes are executable examples, not required method, and that the set can vary by client version.

The bundled agents. Steps name an agent, and it has to be workflow-capable: either a custom agent from .kiro/agents/ or one of the agents Kiro ships for workflows, such as wf-planner (read-only investigation and planning), wf-coder (implements, tests, commits), wf-design, wf-design-reviewer, wf-review-aggregator, wf-pr-submitter, wf-pr-responder, and semantic_reviewer (behavioral code review). These show up only while workflows are enabled and do not appear in the /agent picker. A built-in sub-agent is not a valid step agent. A step’s tools and permissions come from its agent definition, which is the lever for keeping unattended steps narrow.

Models and effort per step. A step resolves its model and reasoning effort as step override, then workflow default, then the parent session’s setting when the run was created, then the agent’s default. The bundled feature-pipeline spends extra effort on design and review and deliberately puts its two code reviewers on different models so their findings are independent. An unknown model id passes validation with a warning and then fails the run at the step’s first model call, so validate every modelId before launch. See Choosing a Model for what is available.

Background delegation and sub-agents. With workflows enabled, the main agent gets a run_workflow tool. It runs recipes, and run_workflow(agent://<name>) runs a single custom agent as a one-step background workflow: the parent chat stays free, the run is inspectable, and progress can come back while it works. In CLI V3, the Workflows: sub-agent tool setting (2.27.0, on by default) keeps direct invoke_sub_agent delegation available alongside run_workflow; turn it off under /settings → Features to route all main-chat delegation through workflows. The IDE and Web route main-session delegation through workflows whenever workflows are enabled. An agent running inside a step can still use its own sub-agents if its configuration allows, but they are not nodes in the run and cannot signal, pause, or revise the step on its behalf.

What it costs. A workflow coordinates several agents and repeats reviews, so it spends more tokens than a single session doing the same task, under the same credit model as other agent work. That is the trade: pay for structure and independent judgment where the work benefits from it, and keep small tasks in the chat. A one-step investigate run is cheap; a three-iteration review loop with two reviewers is not.

Common mistakes

Reaching for a workflow when a chat would do. Renaming a function does not need requirements, two reviewers, and a validation step, and the credits add up. The fix: use a workflow when the work has stages that benefit from fresh context and independent review, or when you want it out of the way in the background.

Launching with an undeclared input. A bare {{task}} that is not declared in inputs and supplied at launch stays as literal text in the prompt; it produces a validation warning, not an error. The fix: declare every input and supply every value. If a step’s prompt visibly contains braces, this is why.

Treating the iteration cap as success. A repeat stops at maxIterations whether or not the work is done, and Resume on a capped loop does not add iterations; it pauses again straight away. The fix: give loops a machine-readable stop condition, such as a fileCheck on a JSON verdict, and choose onMaxIterations deliberately: pause for a human decision, abort to fail loudly, continue only when moving on is safe.

Expecting parallel to be faster. The docs are blunt: parallel gives branches separate context and a join policy; it does not promise a shorter wall clock. The fix: use it for independent judgment, like two reviewers who must not see each other’s notes, and measure any time saved rather than assuming it.

Trusting a recipe to be read-only. A workflow does not make an agent read-only. Side effects come from the selected agent’s tools and permissions and from the prompt. The fix: review the agents a recipe names before you run it, and use a narrowly scoped agent such as the read-only reviewer for unattended steps.

Running two runs on one checkout. Recipes do not isolate branches, worktrees, or output paths, so two runs can edit the same files or overwrite the same artifact. The fix: give concurrent runs distinct output directories, and separate worktrees when they can touch the same files.

Permissions and safety

Everything a step does passes through its agent’s tool list and the usual permission layer, where deny beats ask beats allow. Stopping a run interrupts work without undoing it: files already changed stay changed, so inspect the workspace and use version control before relaunching.

Since IDE 1.2, Kiro asks before the agent changes recipes under .kiro/workflows/, just as it does for agent, hook, and power files, even when broader file permissions would allow the write. In an untrusted workspace the IDE does not load workflow recipes at all until you trust the workspace. That closes the obvious hole where a cloned repository ships a recipe that tells the agent to rewrite its own rules.

Captured output is also protected on the way between steps: when it is interpolated into a prompt, Kiro wraps it in tamper-resistant delimiters an earlier step cannot forge, so a confused or compromised step cannot inject text that a later agent mistakes for its instructions.

Where it fits

Workflows are the “in what order, by whom” layer on top of Kiro’s other building blocks. Custom agents are what the steps run as. A steering file, like your prompt, can shape how Kiro divides the work when it proposes a workflow. Specs describe one feature in detail; feature-pipeline walks the same requirements, design, implementation stages with an agent and a reviewer at each. Hooks fire on events; workflows run a plan. The three bundled recipes end where Kiro’s part ends: a cited report, a validated branch, or a green pull request. Merging stays with you.

By surface, the IDE, CLI, and Web share one runtime and one recipe format; what differs is how you enable the feature, where recipes come from, and which controls you get. Mobile is not covered by the docs.

Learn more

• Write your first workflow recipe builds an implement, review, and loop recipe and runs it in the IDE and CLI.
• Create a custom agent makes an agent a step can name.
• Build a read-only reviewer agent is the kind of narrow agent review steps should use.
• Set the reasoning effort explains the effort levels a step can override.
• Credits and Pricing covers what a multi-agent run costs.