Kiro Guide: Spec-Governed Agentic Engineering

Kiro is an agentic development tool from AWS that comes in three surfaces — a VS Code-style IDE, a terminal CLI (kiro-cli), and a browser Web agent that opens pull requests. What makes it different 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: Kiro is two interaction axes layered over those three surfaces. The first axis 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 axis 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. The catch: AGENTS.md is always included and ignores inclusion modes, so keep it short and portable and keep Kiro-specific, conditionally-loaded rules in steering. The failure mode here isn't missing context — it's conflicting context, where global steering, workspace steering, and AGENTS.md give overlapping instructions. A serious team needs a steering-conflict policy: workspace beats global, 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. The trap that breaks people: Kiro has two hook systems with different schemas and different casing. IDE agent hooks are JSON files; CLI hooks are camelCase keys inside the agent config. Do not copy one into the other.

IDE hooks are created by asking Kiro in natural language or by filling in a form, and stored as .kiro/hooks/<name>.kiro.hook JSON. Triggers include file create/save/delete, prompt submit, agent stop, pre/post tool use, and pre/post spec-task execution. The action is either an agent prompt (askAgent, which consumes credits) or a shell command (which doesn't). One field note: steering refreshes live, but a new hook needs a Kiro restart to be discovered.

CLI hooks live in the agent config under hooks, keyed by camelCase events — agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop — each an array of { command, matcher? }. The matcher (preToolUse/postToolUse only) filters by tool: fs_read, fs_write, execute_bash, use_aws, or *. The blocking model is precise and worth memorizing: exit code 2 on preToolUse blocks the tool and returns stderr to the model; any other non-zero code is just a warning and the tool still runs; a stop hook can block the agent from ending by printing {"decision":"block","reason":"…"}.

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

These four 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 MCP tools with guidance and steering 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 go further: a power-<name>/ folder with POWER.md, an mcp.json, and a steering/ directory, where keywords in POWER.md drive activation. The reason Powers exist is context economy — raw MCP loads every tool definition up front (five servers can be ~100+ tool defs and tens of thousands of tokens before your first prompt), while a Power loads tools on demand.

CLI, IDE, Web, and subagents

The same spec/steering/hook/MCP model runs across all three surfaces; pick the surface by the review model you need.

Kiro CLI (kiro-cli chat) is the terminal surface: headless review, custom agents, and scriptable validation. Use --no-interactive for one-shot runs and pipe diffs straight in. Custom agents are JSON in .kiro/agents/<name>.json with keys like tools, allowedTools, toolsSettings, resources, hooks, and mcpServers — and resources is how you surface steering to a CLI agent.

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."

Subagents give you context isolation: each runs in its own context window and returns a summary, so research and review don't pollute the main thread. They run in parallel (the CLI caps at four concurrent), but note the limits — inside a subagent, specs are unavailable and hooks don't fire. The senior pattern is to fan out subagents for research and review lanes but keep a single writer for implementation unless ownership boundaries are explicit.

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 glob and severity; downgrade to manual if it fires too often. 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 — usually a casing or surface mix-up (IDE PascalCase UI labels vs CLI camelCase keys), or a new IDE hook that needs a Kiro restart to be discovered.

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, and that Kiro's "trusted commands" use simple prefix matching — they don't analyze command chains or special characters, so a trusted prefix can still hide a dangerous tail. Reserve hard hook blocking (exit code 2 on preToolUse) for genuinely dangerous actions. For Web, 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.