> ## Documentation Index
> Fetch the complete documentation index at: https://kiro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Keep working with Kiro while reusable, multi-step agent plans run in the background across IDE, CLI, and Web.

Some work is too big for one agent session: a feature that needs requirements, design, implementation, independent review, and validation. Some work you would rather hand off than watch: an investigation that should finish while you keep working. A workflow gives both to a team of agents with a plan. It is for developers and team leads who want that work finished without watching every step.

The model defines which agents do the work and in what order, and the Kiro runtime executes that plan, so each step runs on time without reminders. Workflows are graphs of agent steps, sequences, loops, and parallel branches, in a format that people and agents can both read and create. Each step runs in its own session with fresh context, so a reviewer, for example, evaluates the work without inheriting the coder's reasoning.

Workflows run in the background. You keep working with Kiro in the main conversation while the delegated work progresses, and each step's session stays available to pause, resume, or steer during the run and to revisit with follow-up questions afterward. Delegating even a small investigation keeps its tool output and detailed reasoning out of the main conversation, which preserves your context for the work in front of you.

Kiro generates a workflow for the task at hand. Save one as a recipe to reuse it, or write your own.

**ℹ️ Info:** Workflows are distinct from the built-in workflow choices shown when you start an IDE session and from [KiroCrew Workflows](https://kiro.dev/docs/crew/features/workflows.md). This documentation covers declarative agent orchestration in the shared Kiro agent harness.

## Start from the agent

You do not write a recipe first. Describe the outcome in the parent chat and say how much structure or review you want. In a V3 session, Kiro shows the proposed plan for your approval before any step runs. You can review its steps and agents before starting it. In Kiro CLI 2.33.1 or later, enabling Workflows no longer starts a workflow on its own; one runs only when you explicitly ask for it.

In Kiro CLI V3, selecting a recipe from the `/workflow run` picker opens a confirmation form with a plan preview. The same approval step appears when Kiro creates a workflow from your prompt.

Three prompts that start a run:

Investigate how authentication works in this repository and report the risks before we change anything. Do it in the background and bring me a cited summary.

Deliver the rate-limiting feature in a fresh worktree: requirements, design review, plan, implementation with two independent reviewers, and a final validation against the requirements.

Make the build green without changing behavior. Reproduce the failure, fix one cause at a time, and rerun the same check. Pause and ask me after ten attempts.

You can also specify custom agents, preferred models, and thinking effort per step, or steer how Kiro divides the work through your prompt or a steering file. Kiro ships three recipes its own team uses: `investigate` for read-only investigation, `feature-pipeline` for staged feature delivery, and `publish-pr` for opening a pull request and handling review feedback. Name one and hand it the inputs. Kiro generates recipes in JSON; YAML is also supported.

In Kiro CLI 2.33 or later, when a workflow asks you to approve its plan, the approval shows a compact step tree: each step with its agent, plus model and effort where the plan sets them. Press **Tab** to move into the tree, **Enter** to show or hide a step's details, and **Tab** again to return to the choices. In Kiro CLI 2.34 or later, type suggested changes directly into the approval to revise the plan before it starts. Nothing runs until you answer. With `/tools trust-all` on, Kiro answers a workflow plan with its one-time Allow option and saves no rule. To confirm, start a workflow from the chat and wait for the approval: it lists the steps before anything runs.

In Kiro CLI 2.33 or later, a workflow still starts when your organization has turned off the Auto model, instead of failing.

A workflow coordinates several agents and repeats reviews, so it uses more tokens than a single session. That is the trade: spend more on structure and independent judgment for work that benefits from it, and keep small tasks in the chat. For how model usage counts against your plan, see [Billing](https://kiro.dev/docs/billing.md).

## Turn it on

Workflows are opt-in in every client. A recipe is the same file in Kiro IDE, Kiro CLI, and Kiro Web; how you turn workflows on, where recipes come from, and which controls you get differ by client.

    IDE
    CLI
    Web

1. Open **Workspace Configuration** for the project.
2. Choose **Workflows**.
3. Enable workflows.
4. Start a new chat session.

The backing setting is `kiroAgent.workflows.enabled`. It is the global switch: when it is off, Kiro does not start new workflows, and existing workflow runs and recipes stay available. Changes apply to new sessions. If **Workflows** is absent, it is not available for your account yet.

In Kiro IDE 1.4.26 or later, each eligible top-level chat also has a **Use workflows** control, at the bottom of **Workflows** above the parent chat, next to **Share feedback for workflows**. The global setting decides whether workflows are available at all; **Use workflows** decides how readily Kiro starts one on its own in that session. The choices:

- **Only when asked**: Handles tasks in your active session and starts a workflow only when you ask for one. This is the initial default until you choose another option in a local session; after that, new chats start with your remembered choice.
- **Only for large tasks**: Uses workflows on its own for multi-step tasks or tasks that need more context.
- **As much as possible**: Attempts to route most tasks, such as code reading, implementation, testing, and review, to workflows.

Prefer **Only when asked** when you want to decide each delegation yourself; prefer **Only for large tasks** when multi-step work should run in the background while small tasks stay in the chat; prefer **As much as possible** when you want most of a session's work to run as workflows and accept the extra token use.

The control changes how Kiro decides, not what it may do: no choice refuses a launch, and you can still manage running workflows. Your most recent choice in a local session is remembered for new chat sessions. A choice made in a cloud session applies to that session only and does not change the local default. The control appears only in a top-level chat with workflows enabled; a **Workflow step** tab does not show it, and neither does a session created before the control existed.

To confirm, start a new chat, open **Workflows** above it, and check that **Use workflows** shows **Only when asked** if you have not chosen another option, or the choice you last made in a local session.

When Kiro asks you to approve proposed workflow steps, the IDE shows them in a permission card where you can choose **Allow** or **Deny**, or send feedback. A saved permission decision can handle a later proposal without showing the card. See [Review proposed steps in Kiro IDE](https://kiro.dev/docs/workflows/manage.md#review-proposed-steps-in-kiro-ide).

1. Run `/settings`.
2. Choose **Features**.
3. Enable **Workflows**.
4. Exit and restart Kiro CLI. Workflow commands are determined when the process starts.
5. Run `/workflow run` and confirm that the recipe picker opens.

The setting is stored as `chat.enableWorkflows`.

1. Open **Settings** in Kiro Web.
2. Choose **Workflows**.
3. Turn on **Enable workflows**. Turning it off hides workflow surfaces and prevents new launches.
4. Choose **Upload workflow** to upload one recipe. To import a complete `.kiro/workflows/` folder, use [Configuration Sync](https://kiro.dev/docs/web/cloud-configuration.md).

Web accepts `.workflow.json`, `.workflow.yaml`, and `.workflow.yml` recipe files. To change an uploaded recipe, open it under **Agent Config > Workflows**, edit it, and choose **Save**. Save is available once the file parses as JSON or YAML. If a save fails, your edits stay in the editor.

## How a workflow is built

Under the hood a workflow is a graph: agent steps, sequences, loops, and parallel branches in a format both you and Kiro can read and write. You can understand most recipes through five ideas:

| Idea | Meaning |
|---|---|
| **Step** | One agent runs in its own session with focused context. A step cannot read another step's session; it receives earlier results only through explicit handoffs |
| **Handoff** | Captured output or a declared artifact passes evidence to a later step |
| **Branch and join** | Independent agents evaluate the same work, then a policy combines their outcomes |
| **Loop** | A group of steps repeats until evidence matches a condition or a safety cap is reached |
| **Wait** | The run watches an external system, a pull request or anything a script of yours can check, without spending model turns while nothing changes |

The parent chat and each step stay connected in both directions. A step reports outward with a `send_message` signal that carries progress, a question, or its outcome. You can steer a running or paused step at any time; see [Respond when a step needs input](https://kiro.dev/docs/workflows/manage.md#respond-when-a-step-needs-input).

With those five ideas in hand, the figure below traces one run from the parent chat: launch, steps in their own sessions, a review loop, artifacts returning, and the main agent synthesizing the result. Both channels stay open the whole time, so you can keep talking in the parent chat and steer a selected step while it runs.

The recipe stores this structure as a readable JSON or YAML tree. The running product shows the same structure as nested nodes, with status, iteration, agent, model, effort, and timing metadata where supported.

A workflow can revise remaining work between step boundaries as its agents discover new information. Completed work remains intact, and the active step is not rewritten underneath itself.

Kiro checkpoints the run at node boundaries. If a run pauses or the client reconnects, completed work does not need to be replayed from the beginning.

## Start from an outcome

These examples show useful shapes, not rules. Change the steps, agents, models, limits, and completion evidence to fit your work.

  <div>
    <p>Investigate and explain</p>
    <p>Research an unfamiliar repository in the background, write a cited report, and return the important risks and change points to the main chat.</p>
    <p>Evidence: report artifact + final synthesis</p>
  
  
    <p>Deliver a feature</p>
    <p>Move through requirements, design review, implementation planning, coding, independent review, and final validation.</p>
    <p>Evidence: approved design + plan + checks</p>
  
  
    <p>Troubleshoot until verified</p>
    <p>Reproduce a failure, diagnose it, apply a fix, and loop through tests until the configured check passes or the run reaches its cap.</p>
    <p>Evidence: reproducible test or machine-readable result</p>
  
  
    <p>Publish and respond</p>
    <p>Open a pull request, wait without consuming model turns, address safe feedback, and hand you a green, approved pull request to merge.</p>
    <p>Evidence: review state + checks + ready to merge</p>
  
</div>

See [Workflow examples](https://kiro.dev/docs/workflows/patterns.md) for complete, adaptable recipe skeletons.

## Background delegation and sub-agents

Workflows add `run_workflow` for reusable recipes and single-agent background delegation. To run one custom agent in the background, the main agent can launch `run_workflow(agent://<name>)`.

A single-agent workflow behaves like ordinary isolated delegation, but it is backgrounded: the parent chat stays available, the run is inspectable, and progress can return while it works. In Kiro CLI 2.34 or later, [**Workflow use**](https://kiro.dev/docs/cli/chat/settings.md#settings-features) controls when the main chat starts Workflows.

| Situation | Delegation behavior |
|---|---|
| Main session with Workflows disabled | Kiro handles work in the active session and can use direct sub-agents |
| **Only when asked** (default) | Kiro starts a Workflow only when you request one |
| **Only for large tasks** | Kiro can start a Workflow for multi-step work or work needing more context |
| **As much as possible** | Kiro tries to route most code reading, implementation, testing, and review through Workflows |
| Agent running inside a Workflow | That agent can still use [sub-agents](https://kiro.dev/docs/custom-agents/subagents.md) when its configuration permits it |
| Reusable multi-step process | The runtime owns explicit steps, handoffs, loops, waits, and recovery |

Nested sub-agents help a workflow step divide its own task. They are not nodes in the parent workflow and cannot signal, pause, complete, or revise that step on its behalf.

## Client support

Workflows are available in Kiro IDE, Kiro CLI, and Kiro Web cloud sessions. Enablement, recipe access, launch entry points, and controls differ by client.

| Surface | Start | Inspect and interact | Current controls |
|---|---|---|---|
| IDE | Ask Kiro in the parent chat, or use `/workflow-run` to pick a saved recipe and complete its inputs | **Workflows** above the parent chat; select a step to open its dedicated **Workflow step** tab | Pause, Resume, Stop |
| CLI | `/workflow run` | Workflow history and full-screen monitor | Pause, Resume, Stop, Retry failed/aborted work |
| Web | Ask Kiro in a cloud session | **Workflows**, **Summary**, **Files**, and **Artifacts**; select a step to message it | Pause, Resume, Stop; Retry when a terminal run has retryable failed nodes |

In the IDE, Kiro tells a workflow that changes repository files to use the branch checked out when the run starts. If the workflow uses a worktree, Kiro tells it to create the worktree from that branch and rebase onto the same branch at the end.

## Start with an investigation

The `investigate` example reads a project without changing source files and writes one cited report. Start from the main chat with a concrete outcome:

Use a workflow to investigate where API request timeouts are configured. Explain the precedence rules, cite the relevant files and symbols, do not modify the project, and save the report under `.kiro/reports/`.

Kiro can launch the run in the background and keep the parent conversation available. Follow the run through the client surface:

    IDE
    CLI
    Web

Open **Workflows** above the parent chat, expand the run, and select `investigate`. Kiro opens a dedicated **Workflow step** tab with the step's session, agent, model, effort, activity, and **Message this step's agent** field. Keep it beside the parent chat to follow both contexts while the run continues.

Run `/workflow run` and select `investigate`, or provide a saved recipe and its inputs directly. Open `/workflow` history if you leave the monitor.

Open **Workflows** beside the parent chat. Select the `investigate` run to inspect its nested step, model/effort metadata, activity, and elapsed time. Use the selected step's message field to steer it, then inspect the report under **Files** or **Artifacts** when it completes.

**⚠️ Warning:** Input declarations tell launch interfaces which values to collect; the values themselves reach the recipe as text. Check required inputs before launch, especially artifact and stop-condition paths.

## Find or create recipes

Recipes can come from your workspace (`.kiro/workflows/`), your user configuration, recipes synchronized for your account, or the set bundled with Kiro; a valid recipe in a higher tier wins when names collide. See [Author workflows](https://kiro.dev/docs/workflows/authoring.md) for the supported files, the precedence rules, and Web import.

Bundled recipes demonstrate useful shapes; they are executable examples, not required methodology or guaranteed inventory across every client version. Review a recipe before running it. Side effects depend on both its prompts and the tools and permissions of its selected agents.

You do not have to hand-write a recipe first. Describe the outcome and how much structure or review you need. Kiro can create a workflow for the task at hand; save a reviewed definition under `.kiro/workflows/` when it becomes worth reusing.

## Security and trust

A workflow runs agents on your behalf in background sessions that keep going while you work on something else; each step's session stays available to inspect, pause, resume, or steer. Depending on the agents a recipe names, its steps can edit files, run shell commands and tests, commit, and open or respond to a pull request, and a `command` watch runs a program you supply once per poll. The agent definition selects the tools a step can see, through its `tools` and `excludedTools` settings, so review a recipe and the agents it names before launching it; a workflow does not make an agent read-only by itself.

Tool visibility is separate from permission. Every step session goes through the same permission checks and approval prompts as any other session: the user, administration, workspace, preset, and session rules of the session that launched the run apply to each step together with the agent's own rules, and the most restrictive applicable rule wins. The agent's own `allow` rules don't grant anything the launching session doesn't allow. See [Sub-agent permissions](https://kiro.dev/docs/custom-agents/subagents.md#sub-agent-permissions). A `command` watch runs its program through the permission policy of the session that launched the run: a rule that asks sends the prompt to that session, and a denial fails the watch node. Remote actions such as pushing a branch or commenting on a pull request use your own repository credentials, and your repository's branch protection, required checks, and approval policy still govern them along with Kiro's permission prompts. The bundled publish-and-respond pattern hands you a green, approved pull request and does not merge it; see [Publish and respond](https://kiro.dev/docs/workflows/patterns.md#publish-and-respond). When a workflow asks you to approve its plan, Kiro shows the plan and nothing runs until you answer; with `/tools trust-all` on, Kiro answers with the one-time Allow option only and saves no rule. In an untrusted workspace, Kiro does not load Workflow files from the workspace's `.kiro/workflows/` directory; your home, cloud, bundled, and generated Workflows stay available. See [Workspace trust](https://kiro.dev/docs/permissions.md#workspace-trust).

To narrow a workflow, set `tools` and `excludedTools` on the custom agents its steps use, put a finite `maxIterations` on every repeat, and give watches an `idleTimeoutSec`. To stop a run, use **Stop** in your client. Removing a recipe file from `.kiro/workflows/` or `~/.kiro/workflows/` stops offering that local recipe, but a lower-precedence recipe with the same name can take its place; to stop all workflows, disable the setting described under [Turn it on](#turn-it-on). To confirm a recipe's reach before you rely on it, read the agent definitions it names and run it on a small input first.

## Next steps

- [Workflow examples](https://kiro.dev/docs/workflows/patterns.md) provides complete starting points for investigation, feature delivery, troubleshooting, and pull request delivery.
- [Author workflows](https://kiro.dev/docs/workflows/authoring.md) covers recipe files, node types, templates, stop conditions, agents, models, and validation.
- [Run and manage workflows](https://kiro.dev/docs/workflows/manage.md) explains progress, step interaction, controls, and recovery across clients.
- [Custom agents](https://kiro.dev/docs/custom-agents.md) shows how to define agents used by workflow steps.