Use Kiro with YYLO

If you build with Kiro, you already work the way the field is converging on: you describe a feature, Kiro turns it into requirements, a design, and a task list, and then the agent executes that plan against your repository. The loop is genuinely good at the middle of the problem — turning intent into an implementation plan and working through it. What it leaves open is everything *around* the loop: who owns the task after the session closes, which work may start before other work finishes, and what evidence a finished change must carry before it enters shared history. This guide adds exactly that layer. Kiro keeps spec-driven execution; YYLO contributes the Git-native task truth, the dependency graph between units of work, and the admission gate that turns finished work into landed history.

The whole combination is one mapping, not one merge: what Kiro generates during one pass becomes records YYLO owns between passes. Kiro's documentation defines specs as "structured artifacts that formalize the development process for features and bug fixes in your application" (what are specs?) — planning artifacts that live in your repository and steer an implementation pass. YYLO's task ledger is the durable counterpart: the place decisions survive after the editor tab closes, with status, recorded responses, and commit references that outlast any session. The rest of this guide is the field-by-field mapping, plus the honest state of the dispatch seam between the two products.

What Kiro already owns

Verified against Kiro's published documentation on 2026-08-27, and all of it stays Kiro's when YYLO enters the picture:

• Spec-driven development. "Every spec generates three key files that form the foundation of your specification" — requirements.md (or bugfix.md), design.md, and tasks.md, where the task file "Provides a detailed implementation plan with discrete, trackable tasks". The workflow is three-phase — requirements, design, tasks — and for well-understood features Quick Spec can "auto-generate all three artifacts without approval gates" (specs).
• Steering. "Steering gives Kiro persistent knowledge about your project through markdown files" — workspace files under .kiro/steering/, global files under ~/.kiro/steering/, and three foundation documents (product.md, tech.md, structure.md) that anchor every interaction (steering).
• AGENTS.md. "Kiro supports providing steering directives via the AGENTS.md standard"; unlike steering files, AGENTS.md files have no inclusion modes and "are always included", and Kiro discovers them in subdirectories so instructions can sit next to the code they describe (steering).
• Hooks. "Hooks run shell commands or agent prompts automatically when specific events happen in your session" — JSON files in .kiro/hooks/ wired to triggers like PostFileSave and PreToolUse, where blocking triggers can veto a tool call mid-run (hooks).
• The terminal agent. The Kiro CLI is "an AI coding agent that lives in your terminal", installed with curl -fsSL https://cli.kiro.dev/install | bash and launched as kiro-cli (CLI setup, CLI overview).
• Cloud execution. "A cloud session runs the Kiro agent harness in a managed cloud sandbox instead of on your machine" — autonomous mode included, up to ten concurrent sessions, and results that come "back through your source provider (typically as a pull request)" (cloud sessions).

None of that changes under YYLO. The decision you are making is not *whether Kiro plans well* but *where the plan's consequences live* — the seam the harness boundary guide draws in full for any agent product.

Where spec-driven work ends and task truth begins

Scale is where spec-only workflows leak. Kiro's tasks.md tracks task state *during* an implementation pass, but the checklist lives inside the spec, its checkmarks are session-scoped, and when three specs from three contributors finish in the same afternoon, the ordering and the landing discipline live nowhere Kiro manages. That is the gap the mapping closes, field by field:

• One spec becomes one YYLO task. The spec's intent — what and why — becomes the task body: an approved unit of work with an id, a status lifecycle, a recorded response, and a commit reference. Kiro's requirements.md and design.md stay the planning truth; the YYLO task is the execution truth. Two artifacts, two owners, no duplicated state.
• Steering shapes the agent; the task defines the work. Your steering files and always-included AGENTS.md keep telling Kiro how to behave in this repository — style, conventions, review expectations. What the YYLO task carries is this unit of work: the description, the response contract, the commit expectation. They compose because they enter at different layers — one as standing context, one as the work order.
• Checkmarks are progress; the ledger is history. tasks.md status answers "how far along is this pass?" The YYLO task's response-and-commit record answers "what happened, who did it, and where is the proof?" — the durability the task-truth guide teaches as its core subject.
• Hooks act inside the session; admission acts on history. A PreToolUse hook can block one destructive tool call mid-run. YYLO's gate is one level up: it decides whether the *finished* change enters shared history at all.

Notice what the mapping does not do: it does not move your spec files, rename Kiro's artifacts, or duplicate the plan into a second checklist. The spec stays the spec. The task is born when the work is admitted as a unit, and it carries the consequences from there.

Dependencies: waves inside a spec, a graph across tasks

Kiro already solves dependency scheduling *inside* one spec: "Kiro builds a dependency graph of the tasks in your tasks.md and groups independent tasks into waves", and "Waves execute sequentially; tasks within a wave execute concurrently" (specs). That is in-spec scheduling, computed fresh for one implementation pass.

YYLO owns the cross-task version, declared as data instead of computed per run. The task schema carries a blocked_by[] field, and the ledger exposes it directly:

# Declare what must be done first
yy ledger create "Deploy API" --blocked-by A1b2C3,X4y5Z6
yy ledger deps T1                      # Show blockers & dependents
yy ledger ready                        # Tasks with no unmet blockers
yy ledger order --scores               # Topological execution order

The README's summary is "Declare what must be done first. The kanban system builds a dependency graph so agents work in the right order" (YYLO documentation). The division of labor that falls out is clean: let Kiro's waves schedule the tasks *within* one spec, and declare blocked_by edges *between* specs and features, so every surface reading the ledger — IDE, terminal, automation — sees the same readiness answer instead of a per-session guess. When you fan out past a couple of independent tasks, the quota, readiness, and isolation habits in safe parallel Kanban execution apply unchanged; nothing in that guide is Kiro-specific.

From finished work to landed history

The cloud-session quote above is worth pausing on: results come "back through your source provider (typically as a pull request)". A pull request is a delivery mechanism, not an admission gate. By itself it does not prove that the producing agent worked from a recorded base, that its tip is clean and committed, or that two agents finishing simultaneously integrate one at a time instead of racing the target branch.

YYLO's admission flow provides those proofs, and it is the last third of the mapping — spec-work *admitted* into shared history:

• A worktree per task. yy task start TASK_ID returns a dedicated worktree for the change; the README calls the worktree "the safety boundary". Open that worktree in Kiro's IDE or point a kiro-cli session at it, and the agent's blast radius is the worktree, not the shared checkout. A cloud session takes its isolation with it instead: Kiro clones the repository into an isolated sandbox where "your local working copy is never uploaded", so the blast radius there is the sandbox, not any checkout you own.
• A committed tip, not a dirty tree. Work lands inside the worktree with focused checks on the touched surface, then a clean commit. That tip — not "the agent said it finished" — is what moves forward.
• A guarded finish. Read-only yy task preflight TASK_ID reports closure defects before anything expensive runs; yy task finish TASK_ID queues the clean committed tip for admission.
• Serialized integration. Feature worktrees implement concurrently from recorded exact bases, and one fenced arbiter owns target mutation, so when several tasks finish together, integration is still one at a time with conflicts preserved for resolution rather than overwritten.

However many Kiro sessions contributed, admission is one queue with one record of what landed — the property the multi-agent workflow guide generalizes across harnesses, and the artifacts behind it are mapped in auditable agent workflows.

Connect Kiro's headless CLI to YYLO's dispatch surface

Now the seam itself, stated with its verified answer and dated. YYLO's documented dispatch surface lists the services claude, codex, gemini, pi, and cursor — that is the -s/--subagent table in the README and its "Switch between Claude, Codex, Gemini, Pi, or Cursor with one flag" sentence (YYLO documentation). A first-party kiro service does not exist in released product truth — the closure gate (checklist item SEO-091) verified that absence on 2026-08-29 by pulling both published tarballs — @yylo/cli 0.2.0 from npm latest, and the 0.2.1-rc.1 build from next — and sweeping them end to end: kiro never appears as a word in any file, source maps included; the dispatcher's validated service list holds five names in both builds, kiro not among them; and no kiro.py ships in the service templates. Nothing is pending here anymore: there is no first-party Kiro dispatch to wait for, and the documented route runs through the extension point below — permanently, until a future release ships the service and a new verification act re-checks the artifacts.

What you can do today is use the documented extension point, because YYLO treats a service as a contract rather than a closed list: "Service scripts live in ~/.yylo/services/. Each is a Python script that accepts standard args (-p/--prompt, -m/--model, -v/--verbose) and outputs JSON events to stdout" (YYLO documentation). Kiro's headless mode supplies the other half — the docs describe running prompts non-interactively with "no interactive terminal required", authenticated by a KIRO_API_KEY environment variable (headless mode). Install the CLI and write the wrapper:

curl -fsSL https://cli.kiro.dev/install | bash

Then drop a minimal wrapper at ~/.yylo/services/kiro.py. This illustrative starting point forwards only flags documented on the headless page, and it follows that page's own advice to "Use --trust-tools with specific categories instead of --trust-all-tools to follow the principle of least privilege":

#!/usr/bin/env python3
"""Minimal YYLO service wrapper around the Kiro CLI in headless mode."""
import argparse
import json
import subprocess
import sys

parser = argparse.ArgumentParser(description="Kiro agent service for YYLO")
parser.add_argument("-p", "--prompt", required=True)
parser.add_argument("-m", "--model", default="")
parser.add_argument("-v", "--verbose", action="store_true")
args = parser.parse_args()

# Only headless-documented flags are forwarded. Model selection — including
# Kiro's Auto routing — is configured inside Kiro, so -m is accepted for the
# service contract but deliberately not passed to kiro-cli.
command = [
    "kiro-cli", "chat", "--no-interactive",
    "--trust-tools=read,grep,write", args.prompt,
]

result = subprocess.run(command, capture_output=True, text=True)
if args.verbose:
    print(json.dumps({"event": "command", "argv": command}), flush=True)
print(json.dumps({"event": "result", "output": result.stdout.strip()}), flush=True)
sys.exit(result.returncode)

With your wrapper installed, dispatch resolves it by name, bounding each run and recording its evidence like any other service:

yy start -b shell -s kiro -i 1 -v

Two notes keep this honest. First, this wrapper is yours, in the directory YYLO reserves for user services — with first-party dispatch verified gone, the extension mechanism is the supported design, not a workaround, and yylo services status shows what YYLO sees. Second, the wrapper captures final output only; Kiro's headless mode also offers a JSON-lines output format for richer event streams, and adapting the wrapper to emit per-step events is user territory. Should a future release ever ship a first-party kiro service, this section collapses to one flag — but only after a new gate act verifies the released artifacts, never on this page's word.

Steering, hooks, and what the task carries

Kiro gives you more instruction surfaces than most agents, so the standing-versus-episodic split deserves its own statement. Steering files (with always, fileMatch, and manual inclusion modes), always-included AGENTS.md files, hooks, and per-purpose custom agents — "a way to customize Kiro behavior by defining specific configurations for different use cases" (custom agents) — are all *standing* configuration: they shape how the agent behaves whenever it works. The YYLO task is *episodic* truth: what this unit of work is, what it produced, and where it landed. Standing config belongs in Kiro's files; episodic truth belongs in the ledger; and neither should be asked to do the other's job.

The one caution is the seam itself. Hooks execute shell commands automatically, prompts can carry substitution commands, and a control plane that dispatches prompts into that environment multiplies the surface. Before wiring anything irreversible into either side, read prompt and shell-context safety; its boundaries apply unchanged when the agent is Kiro. And if your reason for combining the products is really the fear of being stuck with one harness, that fear has its own treatment — the portability audit, plus a switching procedure that costs one flag (harness switching); the same logic that makes switching cheap is what makes combining safe, since neither product holds the other's records hostage. The Cursor sibling guide covers the IDE-agent-plus-control-plane pattern for Cursor specifically.

Start one bounded task today

The cheapest way to prove the mapping is one small spec with nothing riding on it. Install YYLO, admit the spec's outcome as one task, and let Kiro work the plan inside the boundary:

npm install -g @yylo/cli
yylo init --task "Describe one verifiable outcome from one spec" --subagent claude
yy task start TASK_ID
# open the returned worktree in Kiro (IDE, kiro-cli, or an attached cloud session)
# implement with focused checks, commit, then:
yy task preflight TASK_ID
yy task finish TASK_ID

The first dispatch above uses a documented service today; dispatching to a Kiro service through the wrapper from the previous section goes through the extension point — first-party Kiro dispatch is gone from released truth, so the wrapper is the path, not a stopgap. Keep first iterations inside the bounds the bounded-loop guide teaches — one verifiable outcome, focused checks on the touched surface — and the combination settles into its steady state: Kiro planning and writing inside the task, YYLO owning what the task *is*, what it depends on, and whether it landed. Kiro's published behavior was verified against kiro.dev and docs.kiro.dev on 2026-08-27; YYLO's dispatch, ledger, and admission claims against the committed README and source, after re-checking the dispatch surface against the released artifacts on 2026-08-29. Both products move — re-verify before relying on either after they change, and treat the dispatch seam as the extension path until a new gate act says otherwise.