Kiro Guide: Spec-Governed Agentic Engineering

Kiro is an agentic development family from AWS. It spans a VS Code-style IDE, a terminal CLI (kiro-cli), a browser Web agent, Mobile preview, and Crew for persistent unattended agents. Those surfaces share an agent foundation, but they are not feature-identical: local custom agents and hooks, remote sandboxes, mobile delegation, and always-on Crew automation have different boundaries. What makes Kiro distinctive from "chat that writes code" is the workflow it pushes you toward: instead of prompting your way to a diff, you turn an idea into a committed, reviewable spec — requirements.md, design.md, tasks.md checked into your repo — and only then write code against it.

The 15-year-old version: normal AI chat is asking a clever helper to start typing from a one-line description. Kiro first makes the helper write the plan, the checklist, and the acceptance tests, gets you to approve them, and then builds — ticking off the checklist while you watch the diff.

The senior version: two interaction axes matter most in the IDE. The first is Vibe vs Spec — a vibe session is conversational and good for exploration and small fixes; a spec session is the structured requirements → design → tasks loop with tracked execution. The second is Autopilot vs Supervised — autopilot acts end-to-end, supervised yields after each edit for hunk-level review. The docs state that supervised mode is a code-review convenience, not a security boundary.

Reach for Kiro's spec workflow when a change has several requirements, crosses files, needs review, or has real drift risk. Stay in vibe chat — or another editor agent — when the task is tiny, exploratory, or better handled by an inline edit than by a durable artifact you then have to maintain.

How a senior reads Kiro: four control planes

For an experienced engineer the question isn't "can it write code" but "can it preserve my intent while it changes a real repo?" That reframes Kiro as four control planes you operate at once:

Intent — specs, bugfix specs, Quick Plan, requirements analysis, #spec. This is where scope, acceptance criteria, and traceability live.

Context — steering, AGENTS.md, skills, powers, open files, and retrieved docs. Drift starts here, when stale context outranks the real architecture.

Automation — hooks, CLI agents, Web autonomous mode, subagents, and the GitHub/GitLab issue→PR flow. This is what can run without you watching.

Trust — MCP provenance, sandbox policy, internet access, secrets, repo permissions, and review gates. Treat the blast radius as part of the design: write down the threat model before you grant a tool, not after.

The rest of this guide is built from that frame, with the real on-disk syntax for each plane and an interactive tool to apply it. Where Kiro's own docs only document part of a format, this guide says so rather than dressing a guess up as fact.

The spec loop, end to end

A spec session front-loads the thinking that ordinary chat hides. You supply intent and judgment; Kiro produces artifacts and runs tasks; the final check is never "it finished" — it's whether the files, tests, and diff still match the spec you approved. The loop has explicit gates, and the gates are the point.

Specs deep dive

Specs live under .kiro/specs/, one feature-named directory per spec, committed to the repo alongside the code. A feature spec holds three files; a bugfix spec swaps requirements.md for bugfix.md and keeps the other two. Spec files use no YAML front-matter — front-matter is a steering and hooks thing.

When you create a spec, Kiro asks Feature or Bug. For a feature you pick Requirements-First (requirements → design → tasks) or Design-First (design → requirements → tasks); you cannot switch later. Quick Plan produces all three in one pass with no gates.

Acceptance criteria are EARS

The reason Kiro specs work is that acceptance criteria are written so a machine can verify them. Kiro's docs document one EARS form — the event-driven form:

WHEN <trigger> THE SYSTEM SHALL <observable response>

Bugfix specs add two more: WHEN <condition> THEN the system SHALL <correct behavior> and … SHALL CONTINUE TO <existing behavior>. The wider EARS standard has more patterns — and they are worth knowing — but note clearly: the patterns below are the EARS standard, not all documented by Kiro. Kiro reliably emits the event form; you can write the others by hand.

Read the format like a senior reviewer: - [ ] / - [x] track completion, decimal numbering nests sub-tasks, - [ ]* marks an optional test task, and the trailing _Requirements: 1.2_ is your traceability matrix in plain text — every leaf task names the acceptance criterion it satisfies. If a task has no requirement reference, it is scope you never approved.

Bugfix specs force you to separate three things before touching code — the current behavior that is wrong, the expected behavior that is right, and the unchanged behavior that must not regress. The bugfix design adds a root-cause section and "properties to test for," and the tasks phase generates property-based tests that prove the bug existed, the fix works, and nothing regressed.

Two more spec tools matter. Requirements analysis runs after requirements and before design (via the chat option or the Continue dropdown) and flags logical inconsistencies, ambiguities like "large files" or "fast response times," conflicting constraints, unstated assumptions, and missing edge cases; resolving its questions updates requirements.md. And #spec pulls a whole spec into chat — #spec:password-reset implement task 2.1, or #spec:password-reset does my implementation meet the acceptance criteria for task 3?.

The expert moves the docs imply but won't do for you: keep the spec committed so the diff and intent travel together, and run a drift detector after implementation — ask Kiro to list any file or behavior that changed outside the approved spec. A beautiful spec is a liability the moment the PR diverges from it and nobody updates it.

Steering: durable project memory

Steering is markdown that Kiro keeps in mind across sessions. Workspace steering lives in .kiro/steering/ and overrides global steering in ~/.kiro/steering/. The three foundation files — product.md, tech.md, structure.md — are generated by the Generate Steering Docs button and load on every interaction. Custom files should be scoped, so they only load when relevant.

A custom file controls when it loads through front-matter at the very top of the file. There are four inclusion modes, and using the right one is how you stop always-on context from swallowing every prompt.

Note the exact keys: fileMatchPattern (not fileMatch) only applies to fileMatch mode and takes a quoted glob or an array of globs; name + description only apply to auto mode. Inside any steering file you can embed a live project file with #[[file:<path>]] — for example #[[file:api/openapi.yaml]] — so the agent reads the real contract instead of a stale paraphrase.

Kiro also reads the cross-tool AGENTS.md standard. It discovers these files throughout the workspace, so place a root file beside repository-wide policy and nested files beside the code they describe — for example, services/api/AGENTS.md and packages/ui/AGENTS.md. They load as steering context and do not use steering inclusion modes. Keep each file portable and scoped; use Kiro steering when you need fileMatch, auto, manual, or live file references. The failure mode here isn't missing context — it's conflicting context, where global steering, workspace steering, and nearby AGENTS.md files overlap. A serious team needs a steering-conflict policy: workspace beats global, the closest guidance owns its code boundary, every custom file has an owner, and stale files get deleted during architecture review.

Hooks: event-triggered automation

Hooks run an agent prompt or a shell command when something happens. IDE 1.0 and CLI 3.0 share the same standalone, versioned format: .kiro/hooks/*.json with a top-level { "version": "v1", "hooks": [...] }. Each hook uses a PascalCase trigger such as PostFileSave, an optional regex matcher, and an action whose type is command or agent.

The shared triggers cover session start, prompt submit, stop, pre/post tool use, post-file create/save/delete, and IDE pre/post spec-task execution. Kiro's older generic hook material still mentions Manual, but the dedicated current trigger reference says legacy Manual has no v1 equivalent and new Manual-trigger hooks cannot be created; use a steering slash command for manual invocation. A command receives event context as JSON on STDIN; exit 0 adds stdout to context. Any non-zero result returns stderr to the agent and blocks PreToolUse or UserPromptSubmit. An agent action injects its prompt into the conversation. Hook files are discovered when a session starts, so begin a new session after adding or changing one.

Legacy CLI 2.x migration note — do not use this shape in CLI 3.0. CLI 2.x embedded a camelCase hooks object inside an agent config. Its preToolUse command blocked only on exit code 2; other non-zero exits warned but let the tool run. Migrate these entries to standalone .kiro/hooks/*.json, map event names to PascalCase (for example, fileEdited → PostFileSave), and retest blocking because the v1 command action treats any non-zero exit as a block for PreToolUse and UserPromptSubmit. CLI 3.0 is still early access within CLI 2.19, so version-check before distributing a shared config.

MCP, skills, powers — and which one to reach for

These mechanisms solve different problems, and the classic mistake is using the most powerful one for everything. MCP connects Kiro to external tools and data. Skills package a reusable procedure as portable instructions. Powers bundle tools and guidance so they install and load together. (Steering and hooks, covered above, round out the set.)

MCP config lives in .kiro/settings/mcp.json (workspace) and ~/.kiro/settings/mcp.json (user); both merge, workspace wins. The transport is implicit — command means a local stdio server, url means a remote one. There is no type or transport key, and no top-level timeout.

MCP is the sharpest edge in the whole tool: an MCP server is third-party code that can read secrets, run commands outside the sandbox, and exfiltrate data. Kiro only expands env vars you've explicitly allowed and warns on the rest, but the governing rule is yours to enforce — apply least privilege, autoApprove only narrow, read-only, trusted tools, and chmod 600 your mcp.json so secrets don't leak. Name the mcp risk before you connect, not after.

Skills are an open-standard procedure package: .kiro/skills/<name>/SKILL.md plus optional scripts/, references/, and assets/. The SKILL.md front-matter needs name (matching the folder) and description (which decides when it activates, by progressive disclosure).

Powers now prefer the Agent Plugins 1.0 format. A Power has a required plugin.json manifest and may add skills/, mcp.json, and dev.kiro/ extensions. The manifest declares activation keywords; Kiro loads relevant tools and skills on demand. Older power-<name>/POWER.md packages remain supported as a legacy format, but do not use them as the template for new Powers. The reason Powers exist is context economy — raw MCP loads every tool definition up front, while a Power activates the integration only when its keywords match.

IDE, CLI, Web, Mobile, Crew, and subagents

Kiro's surfaces share concepts, not a guarantee of feature identity. Pick the surface by execution boundary, continuity, and review model.

Kiro CLI (kiro-cli chat) is the terminal surface: headless review, custom agents, and scriptable validation. Use --no-interactive for one-shot runs on the stable CLI 2.x engine. CLI 3.0's new TUI and shared agent harness are early access within 2.19, so check the active engine before copying a command or config.

In IDE 1.0 / CLI 3.0, custom agents can be JSON or Markdown frontmatter under .kiro/agents/ (or ~/.kiro/agents/). Tool tags such as read, write, shell, and subagent select capabilities; permissions.rules constrain what those tools may do with allow, ask, or deny. This replaces CLI 2.x toolsSettings restrictions. Run /upgrade-agent to back up a legacy profile and migrate compatible rules, then review any regex-to-glob conversion manually.

Kiro Web is a different trust boundary from the local IDE — it clones your repo into a sandbox and opens PRs. It is preview-only and limited to certain accounts and regions. It runs in two modes: collaborative (the default — it iterates with you and opens a branch/PR on request) and autonomous mode (it owns the outcome through a Clarification → Planning → Execution → Completion arc, and even picks the model). From a GitHub issue you trigger it with the kiro label or a /kiro comment; GitLab uses a personal access token and opens an MR. On the PR you steer it with /kiro all (address every comment) or /kiro fix (one thread).

Because Web executes remotely, its sandbox controls are the security surface. Internet access has three tiers — connections-only (default), a built-in allowlist of common package registries, or open internet — plus a custom domain allowlist. And secrets carry the most risk: they're exposed to the sandbox as env vars, and the docs warn plainly that "the agent may exfiltrate these secrets through code changes, logs, or external requests, so only provide secrets necessary for the task and only use the agent with repositories you trust."

CLI cloud sessions run in a managed sandbox, continue after your local terminal disconnects, and can be resumed from another machine. That is continuity, not local feature parity: review the remote environment, credentials, network, and resulting branch before treating it like a local continuation.

Mobile is a preview surface for starting, monitoring, and steering work away from the desk. Crew is the persistent automation surface: unattended agents can stay running, accept schedules, and respond to webhooks. Crew therefore needs service-style ownership, scoped credentials, observability, and a disable path; it is not merely a longer chat session.

Subagents give context isolation: each runs with its own conversation context, tools, and permissions, then returns findings to the main agent. IDE and CLI can invoke custom agents from .kiro/agents/; Web and Mobile delegate only to Kiro's built-in subagents. Independent stages can run in parallel, dependent stages form a DAG, and a reviewer can send work back through a bounded review loop with max_iterations from 1 to 10. Do not rely on the old fixed four-subagent claim. Spec state and hook triggers are isolated per subagent, so pass an explicit brief and acceptance criteria instead of assuming the parent session's orchestration state transfers. Prefer one writer unless file ownership is explicit; use parallel agents for independent work and reviewers.

How Kiro compares

There's no universal winner — pick by planning model, context model, automation, repo workflow, and how much review evidence you need. Kiro's one real differentiator is the committed three-file spec (requirements/design/tasks with EARS criteria and dependency-wave execution). Most rivals center a single rules file — CLAUDE.md, AGENTS.md, .cursor/rules, GEMINI.md — plus mode toggles, without Kiro's on-disk spec triad. Claude Code is the flexible terminal/IDE harness; Codex is strong for local/cloud continuity and PR review; Cursor is the fast editor loop; Gemini CLI is scriptable terminal work; Cline and Roo Code are approval-first BYO-model editing; GitHub Copilot's agent is GitHub-native issue→PR.

Troubleshooting

Weak requirements — tasks look polished but miss intent. Fix: rewrite acceptance criteria as observable EARS; run requirements analysis. Verify: every task maps back to a requirement.

Broad spec — it tries to redesign the repo. Fix: name non-goals and unchanged behavior. Verify: unrelated files stay untouched.

Over-generated tasks — a long list with no dependency order. Fix: ask for fewer, smaller tasks, each with one verification line and a requirement reference.

Design ignores the codebase — Fix: point Kiro at steering and existing modules; call out any deliberate deviation. Verify with a code-owner review.

Steering conflicts — Kiro follows an old rule. Fix: narrow global steering, update workspace steering, delete stale files. Verify with a "summarize this repo's conventions" prompt.

Noisy hooks — repeated generic advice. Fix: narrow the matcher and severity; if it still fires too often, disable it and move that workflow to a manually invoked steering slash command. Verify with matching and non-matching sample files.

MCP overload — Kiro considers irrelevant tools, or context fills before the first prompt. Fix: disable unused servers/tools, prefer Powers for on-demand loading. Verify the allowed-tool list.

Hook never fires — for IDE 1.0 / CLI 3.0, check that the file ends in .json, the top level is version: "v1" plus a hooks array, the trigger is PascalCase, the matcher is a regex, and the session started after the file was created. Embedded camelCase hooks belong to legacy CLI 2.x only.

Spec rot — the diff diverged and nobody updated the spec. Fix: run a drift detector and sync requirements/design/tasks to the accepted diff. Verify the spec matches shipped behavior.

Security and governance

Treat Kiro as a powerful actor with real reach. The minimum threat model for a serious workflow names: trusted vs untrusted inputs, writable paths, network egress, secrets, MCP servers, generated code, generated tests, CI, reviewers, and the rollback path. If you can't name the blast radius, don't run autonomous mode with broad repo or network access.

The concrete rules: never put secrets in steering, skills, powers, prompts, hooks, or example configs. Don't connect an MCP server just because it exists — apply least privilege and review provenance. Remember that supervised mode is a review convenience, not an isolation boundary. In IDE 1.0 / CLI 3.0, capability-based permissions parse compound shell commands and evaluate every segment separated by ;, &&, ||, or | independently; a rule that allows npm test * therefore does not silently approve npm test ; curl attacker.example. Keep match globs narrow and remember that deny overrides ask, which overrides allow across scopes. Use blocking PreToolUse hooks only for genuinely dangerous actions; exit code 2 is the legacy CLI 2.x special case, while the v1 command action blocks on any non-zero exit for PreToolUse and UserPromptSubmit. For Web and CLI cloud sessions, scope repo permissions, the sandbox, internet access, and secrets to the task, and keep a human in the loop on every PR/MR. Enterprise MCP governance exists (an org allowlist via an MCP registry) but the docs are explicit that it's client-side enforced and can be circumvented by a user with local admin — so it's a guardrail, not a wall.