Workflow examples

The examples on this page are starting points. A bundled recipe demonstrates one useful shape, and the set of bundled recipes can vary across client versions. Change the steps, agents, models, effort, limits, handoffs, and completion evidence to fit your work.

Use this when you need a self-contained answer without source changes. Start from the parent conversation:

The recipe is intentionally small:

brief → investigate · wf-planner → report artifact → main-agent summary

A minimal reusable recipe:

name: investigate-question
inputs:
  brief: prompt
  report_path: file
steps:
  - type: step
    id: investigate
    agent: wf-planner
    artifacts:
      report: "{{report_path}}"
    prompt: >
      READ-ONLY investigation; do not edit code or commit.
      Investigate {{brief}} and write findings to {{report_path}}.
      Lead with the answer, cite files and symbols, list risks and recommendations,
      then call send_message with severity success and the key finding.

A single step keeps the run cheap and auditable. Declaring report makes its path available to later steps as {{artifacts.report}} if this grows into a larger workflow.

Failure guardrail: use a path inside the run workspace and make the read-only constraint explicit. A workflow does not make an agent read-only by itself; the selected agent tools and permissions still govern side effects.

Use this when requirements, design, implementation planning, coding, independent review, and final validation should be explicit stages rather than one long conversation. This is the shape of most feature work:

1. Requirements. One agent turns the task into testable outcomes, in its own session, so the constraints exist as a file before anyone designs against them.
2. Design, reviewed. A designer drafts and an independent reviewer judges, in a loop that ends on approval or a fixed cap. The reviewer never sees the designer's reasoning, only the design.
3. Plan. A planner turns the approved design into an ordered implementation plan.
4. Execute, reviewed. A coder implements the plan; two reviewers on two different models review the result in parallel; an aggregator merges their findings into one verdict. Loop until approved.
5. Validate. A final step checks the finished work against the original requirements, not against the plan.

The figure reproduces the bundled feature-pipeline topology: its named agents, the two reviewers with their model overrides, code-aggregate, and validate as a plain top-level step. The skeleton that follows is an adaptation of it that adds explicit worktree isolation and a machine-readable validation gate; use it as a starting point for your repository's policy, not as the recipe itself.

- type: step
  id: setup
  agent: wf‑coder

The bundled example launches from Opus 5 at High effort, then overrides where it pays: the design and review agents run at Extra high effort, the two code reviewers deliberately use different models (claude-fable-5 and gpt-5.6-sol) so their findings are independent in more than name, and the one-line setup step runs at Low. The remaining steps inherit the launch model and effort.

• design-loop: at most three design/review attempts; stop only when design-review.json says APPROVED; abort if unmet.
• code-loop: at most three implementation/review attempts; run both reviews in parallel, aggregate them into code-review.json, and stop only when its verdict is APPROVED; abort if unmet.
• validate: one final pass against the original requirements.

Here is an adaptable skeleton. It keeps the same stages and adds two things the bundled recipe leaves to you: an isolated worktree per run, and a validate-gate repeat that turns the final check into a machine-readable PASS or abort.

name: deliver-feature
inputs:
  task: prompt
  worktree_path: string
  run_id: string
steps:
  - type: step
    id: setup
    agent: wf-coder
    prompt: >
      Verify that {{worktree_path}} is an absolute path to an isolated worktree.
      Create {{worktree_path}}/.kiro/workflow-runs/{{run_id}} for this run.
      Do not change the primary checkout. Report the selected path.

  - type: step
    id: requirements
    agent: wf-design
    artifacts:
      requirements: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/requirements.md"
    prompt: >
      In {{worktree_path}}, write testable requirements for {{task}} to
      {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/requirements.md.

  - type: repeat
    id: design-loop
    maxIterations: 3
    onMaxIterations: abort
    stopCondition:
      fileCheck:
        path: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/design-review.json"
        jsonPath: verdict
        value: APPROVED
    steps:
      - type: step
        id: design-draft
        agent: wf-design
        artifacts:
          design: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/design.md"
        prompt: >
          In {{worktree_path}}, read {{artifacts.requirements}}.
          Draft or revise the design and write it to {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/design.md.
      - type: step
        id: design-review
        agent: wf-design-reviewer
        artifacts:
          design_review: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/design-review.json"
        prompt: >
          In {{worktree_path}}, review {{artifacts.design}} against
          {{artifacts.requirements}}. Write {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/design-review.json
          with verdict APPROVED or REVISE and the findings.

  - type: step
    id: plan
    agent: wf-planner
    artifacts:
      plan: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/plan.md"
    prompt: >
      In {{worktree_path}}, write an ordered implementation and validation plan
      from {{artifacts.requirements}} and {{artifacts.design}} to
      {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/plan.md.

  - type: repeat
    id: code-loop
    maxIterations: 3
    onMaxIterations: abort
    stopCondition:
      fileCheck:
        path: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/code-review.json"
        jsonPath: verdict
        value: APPROVED
    steps:
      - type: step
        id: implement
        agent: wf-coder
        artifacts:
          code_summary: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/code-summary.md"
        prompt: >
          Implement {{artifacts.plan}} in {{worktree_path}} and run relevant checks.
          Write {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/code-summary.md with changed files, tests run,
          command output, and remaining risks.
      - type: parallel
        id: code-reviews
        joinPolicy: all
        branches:
          - type: step
            id: review-a
            agent: semantic_reviewer
            artifacts:
              review_a: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/review-a.md"
            prompt: >
              Independently review the implementation in {{worktree_path}} using
              {{artifacts.code_summary}}. Write findings to {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/review-a.md.
              Do not read other reviews.
          - type: step
            id: review-b
            agent: semantic_reviewer
            artifacts:
              review_b: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/review-b.md"
            prompt: >
              Independently review the implementation in {{worktree_path}} using
              {{artifacts.code_summary}}. Write findings to {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/review-b.md.
              Do not read other reviews.
      - type: step
        id: code-aggregate
        agent: wf-review-aggregator
        artifacts:
          code_review: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/code-review.json"
        prompt: >
          In {{worktree_path}}, read {{artifacts.review_a}} and
          {{artifacts.review_b}}. Write {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/code-review.json with
          verdict APPROVED or REVISE, deduplicated findings, and corroborated
          issues ranked first.

  - type: repeat
    id: validate-gate
    maxIterations: 1
    onMaxIterations: abort
    stopCondition:
      fileCheck:
        path: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/validation.json"
        jsonPath: verdict
        value: PASS
    steps:
      - type: step
        id: validate
        agent: wf-coder
        artifacts:
          validation_report: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/validation.md"
          validation: "{{worktree_path}}/.kiro/workflow-runs/{{run_id}}/validation.json"
        prompt: >
          In {{worktree_path}}, validate the implementation against
          {{artifacts.requirements}} and {{artifacts.code_summary}}.
          Run the required checks. Write {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/validation.md and
          {{worktree_path}}/.kiro/workflow-runs/{{run_id}}/validation.json with verdict PASS or FAIL and the evidence.
          Do not fix code in this step; report honestly.

Worktree selection and run setup are explicit, not automatic workflow behavior. Keep worktree_path inside an allowed workspace root: open or launch from the isolated worktree itself, or create the worktree inside the current workspace. Every artifact and fileCheck path in this recipe lives under worktree_path, and a fileCheck path outside every allowed workspace root fails its node. Give concurrent runs different run_id values so their artifacts and gates never collide. The example validates the change but does not bypass repository controls. To land it, hand the validated branch to Publish and respond for review, then merge through your normal repository process once the pull request is green and approved.

Failure guardrail: iteration caps limit time and usage; they do not prove quality. This example aborts when either review approval or the final validation verdict remains unmet rather than silently advancing.

Use this for failures that can be reproduced and checked mechanically: a broken build, failing test, deployment validation, or performance regression.

Each iteration reproduces the failure, diagnoses one cause, applies the smallest change, and reruns the same check; the loop exits only when result.json records the verdict, and the cap pauses the run instead of declaring success. The skeleton keeps those moves in a single step; split them into separate steps when each needs its own agent or its own evidence file.

name: troubleshoot-until-verified
inputs:
  issue: prompt
  result_path: file
steps:
  - type: repeat
    id: fix-loop
    maxIterations: 10
    onMaxIterations: pause
    stopCondition:
      fileCheck:
        path: "{{result_path}}"
        jsonPath: verified
        value: true
    steps:
      - type: step
        id: diagnose-and-fix
        agent: wf-coder
        prompt: >
          Reproduce {{issue}}. Inspect the latest result at {{result_path}} if it exists.
          Test one hypothesis, apply the smallest justified change, rerun the reproduction,
          and write JSON with verified, evidence, and remaining_risk fields.

Each iteration re-derives truth from the repository and the same check. fileCheck gives the runtime an enforceable stopping condition; a success claim in prose alone does not end the loop.

Failure guardrail: onMaxIterations: pause surfaces a decision instead of spending indefinitely or reporting false success.

Use this after a branch is ready for review. A watch waits without model turns, a focused responder addresses new activity, and the repeat exits when the pull request reaches a terminal state, which happens when you or your repository process merge or close it. The workflow's deliverable is a green, approved pull request; the merge is yours.

The figure below draws the loop as a loop. The particle rests while the watch is parked, goes once round through respond when activity arrives, and leaves by the exit only once you have merged or closed the pull request.

name: publish-and-respond
inputs:
  branch: string
  run_dir: string
steps:
  - type: step
    id: submit
    agent: wf-pr-submitter
    prompt: >
      Publish {{branch}} as a pull request, or reuse its open PR.
      Write its URL and metadata to {{run_dir}}/pr.json.
  - type: repeat
    id: pr-loop
    maxIterations: 200
    onMaxIterations: pause
    stopWhen: wait.terminal
    steps:
      - type: watch
        id: wait
        handler: github-pr
        config:
          prRef: "{{run_dir}}/pr.json"
      - type: step
        id: respond
        agent: wf-pr-responder
        prompt: >
          Respond to the new PR activity in {{wait.output}}.
          Address feedback that is safe and in scope. Ask before changing the design,
          expanding scope, or altering the user experience.

The responder runs after both ordinary and terminal watch activity, so it can perform final wrap-up once the pull request has been merged or closed. The workflow does not override credentials, branch protection, required checks, or approval policy, and it does not merge: it hands you a green, approved pull request, and you or your repository process perform the merge.

Failure guardrail: give concurrent runs separate run_dir values so they do not share pr.json, and use least-privilege GitHub credentials.

The same wait-and-respond loop works for anything a script can check. Swap the github-pr watch for a command watch that runs your own program, and the loop waits on a ticket, a deployment, or a build in another system; see Watch anything else with command.

Workflow shape can change output quality as much as the selected model, and the best shape depends on the model. A model that plans well may need fewer review loops; a fast, cheaper model may need a stronger reviewer and a lower cap; a model that reasons deeply on a single pass may be wasted on a tight repeat. Treat model, provider, effort, decomposition, critique, and verification as experiment inputs rather than assuming one configuration is best, and expect to iterate.

The bundled feature-pipeline recipe is one worked answer: it spends effort where judgment matters (design and review at Extra high) and buys independence by putting its two code reviewers on different models. Change the model, and the right place to spend effort moves with it.

A useful experiment:

1. Declares one task set and one evaluation rubric.
2. Runs the same small workflow under several available configurations, using per-step modelId and effortLevel overrides.
3. Keeps each lane isolated so one output does not bias another.
4. Records quality, elapsed time, and estimated usage as artifacts.
5. Uses a declared evaluator to compare results.
6. Revises the workflow or configuration and repeats when the evidence justifies it.

Provider and model availability depends on the account and client. Validate every modelId before launch. Kiro does not select providers automatically, fall back between them, or guarantee a performance ordering; your rubric decides.

Use parallel when several independent judgments should converge into one result. Give each branch a different available configuration when diversity is useful, then make an aggregate step deduplicate findings and rank corroborated issues. Parallel currently provides context isolation and join semantics; do not assume it shortens wall-clock time.

For open-ended optimization, run one measured experiment per iteration. Commit an improvement and revert a regression. When no natural correctness condition exists, use maxIterations as the explicit cost ceiling and pause for a human decision at the cap.

The examples above are pieces. Real work chains them, and you rarely start by writing a recipe: you describe the outcome in the parent chat and Kiro proposes the workflow, or you name a bundled recipe and hand it the inputs. Three typical chains, each ending where Kiro's part ends: a green, approved pull request for feature delivery, a validated branch for a local fix, or a cited report for read-only work. Any merge is yours or your repository's.

Ship a feature from a ticket. Ask Kiro to deliver the change in a fresh worktree. It sets up the worktree, writes requirements, loops design and review, plans, loops implementation and two-model review, validates against the requirements, then publishes a pull request and parks a watch on it. While it runs you keep working in the parent chat; when a reviewer comments, the responder wakes, addresses what is safe, and asks you before changing scope. You merge when you are satisfied.

Fix a failing build. Ask Kiro to make the build green without changing behavior. It reproduces the failure, then loops diagnose, smallest change, rerun until the same check passes, with a cap that pauses for you instead of thrashing. If the cause turns out to be a design question, the step pauses and asks; you answer in that step's session or through the main agent, and the loop continues with its history intact. It ends with the fix on a branch and the evidence file that proves the check passed.

Understand before you change. Ask Kiro to investigate an unfamiliar area and report risks before any code moves. One read-only step produces a cited report; the main agent summarizes it in your chat, and that is where this run ends: a report you can act on, with no branch and no pull request, because nothing was changed. If the report warrants a change, say so, and Kiro proposes the feature chain above with the report as its first input, so the requirements step starts from evidence rather than from your memory of the codebase.

Keep each boundary explicit when you chain:

• Pass durable files as artifacts and short conclusions as captured output.
• Give loops a machine-readable stopping condition when one exists.
• Treat iteration caps as safety limits, not proof of success.
• Keep workspace and worktree paths explicit.
• Review agent tools, credentials, and side effects before launch.

• Author workflows covers the complete recipe schema, node types, templates, stop conditions, agents, models, and validation.
• Run and manage workflows explains monitoring, steering, controls, and recovery across clients.