Workflows: Background Agent Teams

Lesson 5 · Kiro CLI v3 for v2 users. Time: 12 minutes. Tangible win: run the bundled investigate workflow and author a two-step recipe.

Sub-agents (v2) run inside your session. A workflow runs a graph of agent steps in the background, each in its own fresh session, while your main chat stays free. A reviewer step does not inherit the coder's reasoning, which is the real point.

Primary source Workflows — kiro.dev. Concepts, surfaces, safety. About 12 minutes; then Author workflows for recipes.

Turn it on

Workflows are opt-in. Set chat.enableWorkflows and restart the CLI:

kiro-cli settings chat.enableWorkflows true

Then ask in plain language ("Investigate how auth works here, in the background, and give me a cited summary") or run /workflow run. In V3 you approve the proposed plan before any step runs. Nothing starts on its own unless you ask.

Five ideas

IdeaMeaning
StepOne agent, own session. Cannot read other steps' sessions
HandoffOutput or a declared artifact passes to a later step
Branch and joinIndependent agents judge the same work; a policy combines results
LoopRepeat until evidence matches or a cap is reached
WaitWatch an external system without spending model turns

Kiro ships three recipes: investigate (read-only), feature-pipeline and publish-pr. Recipe precedence: project .kiro/workflows/, then ~/.kiro/workflows/, then synced, then bundled.

A minimum recipe

{
  "name": "plan-and-implement",
  "description": "Plan a change, then implement it",
  "inputs": { "task": "prompt" },
  "steps": [
    { "type": "step", "id": "plan", "agent": "wf-planner",
      "prompt": "Create an implementation plan for: {{task}}. Do not edit files." },
    { "type": "step", "id": "implement", "agent": "wf-coder",
      "prompt": "Implement this plan, then run tests:\n\n{{previous.output}}" }
  ]
}

Save as .kiro/workflows/plan-and-implement.workflow.json, ask Kiro to run validate_workflow on it, then /workflow run plan-and-implement --task "...".

Safety and cost

Every step goes through the same permission checks as any session, and the launching session's rules apply too, so an agent's own allow never grants more than you do. This is the lesson 1 sub-agent rule again. Workflows use more tokens than one session; keep small tasks in chat. Set a finite maxIterations on every repeat.

Retrieval check

Why does each workflow step run in its own fresh session?

Right. Fresh context gives independent judgment; steps pass only explicit handoffs.

Steps cannot read each other's sessions. Isolation lets a reviewer evaluate work without inheriting the coder's reasoning.

A step agent has an allow rule for git push, but your session does not. What happens?

Right. An agent's own allow never grants more than the launching session allows.

The launching session's policy still applies, and the most restrictive rule wins, so the agent rule grants nothing extra.

In the recipe above, how does implement receive the plan?

Right. The final message of the previous step is passed via a template.

Steps cannot read each other's sessions; handoffs travel through templates such as {{previous.output}}.

Practice

  1. Run the setting command above, restart kiro-cli, and open a scratch repo.
  2. Ask: "Use the investigate workflow to explain how this repo is built. Do not modify anything." Review the plan before approving.
  3. While it runs, keep chatting in the main thread. Open the monitor and select a step (Ctrl+G is the sub-agent monitor shortcut; check /workflow for yours).
  4. Save the recipe above, validate it, and run it on a tiny task.
Ask me to design a recipe for a job you really do, such as plan, implement, then two independent reviewers. Anything unclear? Ask.