Inspiration
We kept running into the same friction: turning an idea into working code still means context-switching between docs, tickets, and an editor. Spec-driven development promised a fix, but existing tools treated the spec as an afterthought—a comment, not a contract. We wanted an agent that treats the specification as the source of truth, so the distance between what you mean and what ships collapses. That gap—between intent and implementation—is what inspired Kiro.
What it does
Kiro is an agentic development environment that takes a natural-language spec and drives it end-to-end toward working code. Given a feature description, it:
- Generates and refines a structured spec (requirements, design, tasks)
- Breaks the spec into an actionable task graph
- Executes tasks with an agent that reads, writes, and runs code
- Keeps the spec and implementation in sync, flagging drift
In short: from spec to ship.
How we built it
We built the agent loop around a spec as a first-class artifact. The core pipeline is:
$$ \text{Intent} \xrightarrow{\text{parse}} \text{Spec} \xrightarrow{\text{plan}} \text{Task Graph} \xrightarrow{\text{execute}} \text{Code} $$
At each step the agent can re-read the spec and reconcile output against it. The planning stage scores tasks by dependency and risk:
$$ \text{priority}(t) = \alpha \cdot \text{dep}(t) + \beta \cdot \text{risk}(t) + \gamma \cdot \text{impact}(t) $$
with $\alpha, \beta, \gamma$ tuned so that blocking, high-risk tasks surface first. We used a tool-calling architecture (file I/O, shell, test runner) with a spec-aware context manager that keeps the agent anchored to requirements rather than drifting into improvisation. The whole thing runs as a CLI plus an editor-integrated surface.
Challenges we ran into
- Spec drift. Early versions let the agent wander from the spec. We fixed this by making the spec a re-read artifact at every planning and execution boundary, and by diffing generated code against spec intent.
- Task granularity. Too coarse and the agent lost the thread; too fine and overhead exploded. We landed on a dependency-aware decomposition that adapts depth to task complexity.
- Context limits. Long specs blew the context window. We built a hierarchical summarizer that preserves requirement IDs and invariants while compressing prose.
- Verification. Knowing whether the agent succeeded was harder than making it produce code. We leaned on tests derived directly from spec acceptance criteria.
Accomplishments that we're proud of
- A working end-to-end loop: spec in, tested code out.
- Spec–code drift detection that catches divergence before merge.
- A task graph that actually prioritizes what blocks everything else.
- The tagline we landed on: "Kiro: From Spec to Ship."
What we learned
Specs are only as good as their enforceability. The moment we treated the spec as a contract the agent must satisfy—rather than a prompt it should follow—behavior stabilized dramatically. We also learned that agent reliability is mostly a context problem: keep the right invariants in view, and the model does the rest. Formally, treating the spec as an invariant set $S$ and requiring generated code $c$ to satisfy $c \models S$ reframed our whole verification approach.
What's next for Untitled
- Multi-agent collaboration on a shared spec, with conflict resolution.
- Formal verification hooks so acceptance criteria become machine-checked invariants.
- Broader surfaces: IDE plugins, CI integration, and spec-as-code in the repo.
- Learning from drift: feed reconciliation events back to improve planning.
We're calling the project Kiro, and the north star stays the same: close the gap between what you mean and what ships.
Built With
- agentic-development
- ai-agents
