Early thoughts on Kiro, Amazon’s new agentic IDE/VSCode fork

TLDR: Starting with generating spec docs upfront feels right, and matches how I work with other AI codegen tools. Kiro does a good job of this.

TLDR 2: Great logo.

Amazon just released Kiro, a competitor to Cursor, VSCode, Windsurf, Zed, Claude Code, Gemini CLI, OpenAI Codex, Jules, …

This might be a crowded playground.

To compete with existing agentic code assistants/IDEs/CLIs, Kiro is going all in on two built-in concepts:

• Spec mode enables you to do some planning upfront and will produce requirements, design, and task docs before writing any code for a task.

• Hooks enable the agent to perform tasks autonomously when triggered, like keeping docs in sync or checking for code smells on file save.

You can also connect your MCP servers to Kiro and add agent steering rules which help to guide agent behaviour and responses.

I was intrigued. Doing spec work upfront can be a good way to work with LLM codegen, and Kiro includes it in the box.

I spent some time working with Kiro yesterday and wanted to share my early feedback.

The task: add light mode to a static site

I’ve been testing code agents against my personal Astro + Tailwind site, a relatively tiny repo with only a couple of components, two routes, content links, and some global styling. Each agentic editor is asked to complete the same tasks: add light mode support and clean up styles in the process. I used Claude Sonnet 4.0 while testing Kiro.

If you aren’t familiar with Tailwind, there is a built-in dark variant that can be used. Because the site is already dark by default, the existing themes need to be ported over to use the dark variant, and then light colors need to be added. Plus, add a toggle somewhere and track the state. LLMs seem to struggle with some of the updates that came Tailwind v4, which is part of the reason I use this as a test. (Claude 4’s training cutoff is March 2025, so it should be aware of these updates).

Spec-tacular start

I used Kiro’s spec mode to generate some spec files before the agent starts to make changes to my codebase. requirements.md, then design.md, and finally tasks.md are generated before Kiro starts writing code.

My initial prompt was extremely simple: “I want to add a light mode theme to my app. I also want to clean up style definitions, especially colors, so they are all declared in one place”. I didn’t provide much context upfront, but I wanted to see what kind of docs spec mode spits out.

I ran through this task twice, once before generating agent steering rules and once after (because I didn’t discover the Kiro tab until after I generated specs the first time).

The generated requirements.md contains a list of user stores and WHEN-THEN-SHALL acceptance criteria: 

1### Requirement 1
2
3**User Story:** As a visitor to the portfolio site, I want to toggle between light and dark themes, so that I can view the content in my preferred visual mode.
4
5#### Acceptance Criteria
6
71. WHEN a user visits the site THEN the system SHALL display a theme toggle control that is easily accessible
82. WHEN a user clicks the theme toggle THEN the system SHALL switch between light and dark modes instantly
93. WHEN a user switches themes THEN the system SHALL persist their preference across browser sessions
104. WHEN a user returns to the site THEN the system SHALL remember and apply their previously selected theme
115. IF no theme preference is stored THEN the system SHALL respect the user's system preference (prefers-color-scheme)

(A fun note about the generated acceptance criteria: both times I generated requirements.md, each requirement had the same number of acceptance criteria. The first time, there were always four criteria. The second time, pictured above, there were five.)

The generated requirements and acceptance criteria seemed pretty reasonable. And, because it's just markdown, you can edit it before moving on to the next step. Once you are happy with the stories and criteria, you can move on to the next step: a design spec.

Design time

Next, the next step in spec mode’s process is design.md. This file contained:

• Proposed architectural changes, like how colors are stored.

• Updates to components and interfaces, including TypeScript snippets for component props and proposed state management changes.

• Data model changes, which included how the color theme was changing in my case.

• Notes on error handling and implementation considerations, including callouts for accessibility-related considerations.

This is the step in the spec process that I found to be the most important! The doc gets into some technical details and is a good place to question things and iterate on what the agent will actually do. In my case, rolling a custom color theme when I want to continue to use Tailwind’s default colors.

1## Components and Interfaces
2
3### ThemeToggle Component
4**Location**: `src/components/ThemeToggle.astro`
5
6**Features**:
7- Toggle button with sun/moon icons
8- Smooth transition animations
9- Accessible keyboard navigation
10- Visual feedback for current state
11
12**Interface**:
13```typescript
14interface ThemeToggleProps {
15 position?: 'fixed' | 'relative';
16 className?: string;
17}
18```

This is the point at which steering rules became useful. 

Steering rules are markdown files that give additional context about your project to the agent, similar to setting rules in Cursor or adding a CLAUDE.md file when building with Claude Code. If you don’t already have markdown rules you want to copy over, Kiro can generate them for you. (There appears to be a small bug where I had to exit and re-open my editor for the generated steering docs to appear in the list in the IDE.)

These steering rules are fed in as context for every agentic action, vibe code prompt, and hook that runs in Kiro.

Without steering rules, my spec’s design.md file contained many references to tailwind.config.js. Tailwind v4 ditches this configuration file in favour of a CSS-centric approach, so my project does not have a config file to edit. When I generated a design.md with steering rules, there was no hint of that config file. Take what you will from this sample size of two. (tailwind.config.js did make an appearance later in the process.)

(Almost) Time to do the work

Once the design doc is finalized, Kiro generates tasks.md containing an implementation plan. Similar to breaking down a story into smaller tickets, work is broken down into smaller tasks:

1- [ ] 3. Implement ThemeToggle component with accessibility features
2 - Create Astro component with toggle button and sun/moon icons
3 - Add proper ARIA labels and keyboard navigation support
4 - Implement smooth transition animations that respect prefers-reduced-motion
5 - Wire up click handlers to update theme state and localStorage
6 - _Requirements: 1.1, 1.2, 1.3_

Kiro did a totally reasonable job at breaking down the big spec job into smaller tasks, and each task references sections in the requirements doc.

All of these docs can also be regenerated at any point in the process. Say you have updated requirements or design specifications. You can edit a spec file (once again, manually or using the agent) and then use the updated spec file context to refresh downstream files.

As a test case, I made edits to design.md, then updating tasks.md. Unfortunately, after this process, tailwind.config.js had slipped into the tasks.md file, even when I had steering rules referencing Tailwind v4.

The year is 2094. LLMs are still generating tailwind.config.js files.

Do the tasks

Once you are happy with tasks.md, you can click through tasks one at a time, or yolo it and let the agent run through all tasks.

I tried both. If you’re here for the vibes, running through everything at once might be how you want to work. I like to build things that work, so going through each task individually made it easier for me to digest and test updates, and provided reasonable places for me to make edits and commit the changes.

Kiro also makes changes and runs tests as it edits your code. In my case, the pnpm build or pnpm dev scripts were run to make sure the build was not broken. You manually permit Kiro to run these scripts (good!).

As you go through tasks, you can also refine them manually and retry tasks, just in case something goes awry while the agent is working. After work is complete, you can see the diff and execution.

If Kiro was going down a path I didn’t like, such as adding a bunch of global styles that were unnecessary, small tasks allow me to manually intervene without digging through massive changesets. 

I did get a surprise on my second stab at adding light mode. Kiro thought I already had a theme toggle component, even though it was not part of my current branch. It appears to have been cached from my previous run and branch. Keep in mind, this was a fresh spec run on a new branch. This could be an issue if I were working on a large project with a ton of branches.

It actually works!

After working through the list of tasks, Kiro was able to successfully add a light theme and use Tailwind’s dark variant for the previous defaults.

Some manual intervention was required to change some unfortunate color choices and wonky styles. At this point, it’s like vibe coding using any other AI codegen assistant. Results are about as good as your inputs and prompts. I won't get too much into code quality here, but it seemed to match what I would get using Cursor, VSCode + Copilot, or Zed with Claude Sonnet 4. (LLMs love to generate a ton of code to handle theme switching. I've found it takes some prompting and massaging to get a simpler implementation suitable for my site.)

Oh no, the hook made my app ugly

With the successful theming of my app, I decided to try using Kiro’s hooks to find code smells.

Hooks are automated processes triggered by actions like creating, deleting, or saving a file. A prompt is sent to Kiro in the background, and the job is then enqueued to complete the task.

Once a hook is created, you get a useful interface to configure it, including the instructions, the trigger event, and file paths to watch:

I tried Kiro’s default “Optimize my code” hook and then updated some styles across a couple of different files, including components and my global.css file. 

My initial hook execution left my app in an unhappy state. Colors I had just added with the spec work were removed, some of the custom styling was botched, and my already ugly app (I am not a designer) was bordering on fugly. Thankfully, Kiro has big Revert buttons everywhere, so I was able to roll back the hook's changes.

I’m not going to lie, I had trouble following the hook execution. It opens a new tab in the agent panel and just starts editing files. I think this could be useful for keeping documentation or tests up to date as you make changes to a code file, but looking for code smells felt invasive. I don’t want the hook to do a small theme update and then change all my frontend components to match that update (that I didn’t want in the first place).

I want this particular hook to feel closer to spec mode. An approval system that previews what the hook is about to do, allowing me to accept or reject the plan, would be massively helpful.

Adding “Generate a plan of the work being done, present it to me, and ask me for approval before performing any edits.” to the hook instructions was all that was required. Instead of just going to town on my repo, the agent came up with a plan and made no changes before I approved.

I could see approvals like this causing workflow issues with hooks. Because they are kicked off automatically, I would need to remember to approve work. A solvable problem, but it requires a strategy for managing the agent and hooks.

Overall, spec mode seems like a win

I liked the step-by-step approach of Kiro’s spec mode. It closely matches how I work with other AI codegen tools, but is more “in your face” about the process. It forces you to provide better context to the agent and offers reasonable places to manually intervene, review code, and commit changes. It also creates a documentation trail for you to follow for each feature you build. In theory, you should also be able to use a hook to keep those docs up to date.

I think I like the idea behind hooks, and I see the potential. But my first impression was not amazing.

Overall, I enjoyed using Kiro. Spec mode is nice, but could (and maybe should) be a process followed for any AI codegen tool. Hooks have real promise. More time and experimentation are required for me to develop a workflow for managing the agent and these automated hook workflows.

Sidenote: great logo, great choice of color.