One Sentence to a Working App: What Kiro's Spec Mode Actually Does When You Give It Almost Nothing
How I built an OpenAPI request playground for the Kiro birthday challenge — starting from a single sentence, with a hard deadline and a few honest failures along the way.
The constraint
For Day 4 of the Kiro birthday challenge, the rules were deliberately restrictive: start with exactly one sentence. No planning docs, no architecture diagrams, no multi-paragraph prompt disguised as a sentence. Feed it to Kiro's Spec mode, let Kiro generate the full requirements, design, and task list, and build the app by following that spec. The first commit in the repo has to be the unmodified Kiro-generated spec.
I had about two and a half hours before the submission window closed.
My sentence:
Build a web app where you paste an OpenAPI spec URL and it generates a live, testable request playground for every endpoint in that API.
I picked this idea because it's a tool I would actually use — a lightweight Postman-style playground that works off nothing but a spec URL — and because parsing unstructured input into structured, usable output is the kind of problem I've been working on all year with agentic RAG systems. This felt like a fair test of whether spec-driven development holds up under time pressure.
What Kiro generated from one sentence
Spec mode works in stages. Kiro asked whether this was a feature or a bugfix, offered a choice of starting points, and then generated three documents under
.kiro/specs/openapi-playground/:requirements.md — acceptance criteria in EARS format. This is where the first real surprise came. From one sentence, Kiro derived requirements I had not thought to write down:
- Handle CORS failures with a clear user-facing message (a browser-only app firing requests at arbitrary APIs will hit this constantly)
- Validate the spec and detect missing or unsupported OpenAPI version fields
- Resolve
$refschema references, including detecting circular references
Every one of these ended up mattering. The version-field validation caught a real failure during my demo prep — more on that below.
design.md — component architecture (spec loader, endpoint explorer, request builder, response viewer) plus algorithmic pseudocode with preconditions and postconditions for spec parsing and schema resolution. This document ended up over a thousand lines.
tasks.md — an ordered implementation checklist derived from the design.
Where it went wrong (and how I recovered)
Two honest failure notes, because a writeup that pretends everything worked first try isn't useful to anyone.
Mistake one: I started in the wrong mode. My first run was in Kiro's default vibe/autopilot mode. It happily started building the app — components, configs, the works — but there was no
.kiro folder, because no spec was being generated. For this challenge that would have been a disqualified submission. I only caught it because I ran ls -la and noticed the spec folder didn't exist. If you're doing spec-driven work in Kiro, start a Spec session explicitly. The mode you're in matters.Mistake two: the design doc fought the tool. Kiro's design-first workflow wanted to produce a very detailed design.md, and the document was large enough that file writes repeatedly hit output truncation limits. I watched it retry in smaller and smaller chunks for close to seven minutes before the run got cancelled, burning credits the whole time. The fix was simple: I restarted the spec session and appended a length constraint to my sentence — asking Kiro to start with requirements first and keep each document concise. The content was still entirely Kiro-generated; I just stopped it from writing documents too large to physically complete. Requirements came out clean in under four minutes on the retry, and the earlier design.md turned out to have survived intact, so Kiro picked it up and carried on.
Lesson: spec quality and spec size are different things. Constraining length doesn't weaken the spec — it makes the workflow reliable.
The build
With all three spec files committed first (unmodified, as the rules require), implementation was the fast part. The stack the design called for was straightforward: React 18 + Vite + TypeScript, fully client-side, no backend. Swagger-parser and js-yaml for spec handling.
The core flow:
- Paste an OpenAPI/Swagger spec URL (JSON or YAML)
- The app fetches and validates the spec, resolving schema references
- Every endpoint renders in a sidebar, grouped by tag, with colour-coded method badges
- Clicking an endpoint generates a request form from the parameter schemas — path params, query params, request body pre-filled from schema examples
- Send Request fires a real fetch to the API's server URL and displays status, headers, and pretty-printed JSON
Following tasks.md as a literal checklist did something I didn't expect: it kept a time-boxed build from wandering. Every time I was tempted to polish something, the next unchecked task pulled me back. For a two-hour build that discipline was worth more than the design doc itself.
Testing it for real
I verified end-to-end against the Swagger Petstore spec (
https://petstore3.swagger.io/api/v3/openapi.json): 19 endpoints parsed and grouped in seconds, forms generated correctly for path, query, and body parameters, and live requests returning real responses — GET /store/inventory with zero params, GET /pet/findByStatus returning a full array of pets.Then I tried to show off. I loaded a second spec — Open-Meteo's weather API, in YAML — planning to close the demo video by fetching live weather for Madurai. The app rejected it: "Unsupported or missing OpenAPI/Swagger version field."
With minutes left on the clock, I didn't debug it. But here's the thing — that error message existed because Kiro's generated requirements demanded spec validation with clear failure messages. The app failed loudly and legibly instead of crashing or hanging. A requirement I would never have written myself, derived from one sentence, is what made the failure a graceful one. That's the strongest argument for spec-first development I've personally run into.
What I'd tell you if you're trying spec mode
- Start the Spec session explicitly. Autopilot builds; it doesn't spec. Check for the
.kirofolder early. - Constrain document length in your prompt. Large generated design docs can fight output limits. Concise specs generate reliably and are easier to follow anyway.
- Treat tasks.md as a contract. The checklist discipline is the real productivity gain, especially under a deadline.
- The generated requirements are the hidden value. Edge cases you'd discover in production — CORS, malformed input, version mismatches — show up as acceptance criteria before you've written any code. Fewer rewrites, not slower starts.
Spec-driven development didn't feel like ceremony here. It felt like borrowing a more careful version of myself for the planning phase, then executing at full speed.
The repo, with the unmodified Kiro-generated spec as the first commit, is on my GitHub. Happy to answer questions about the workflow in the comments.
Built for Day 4 of the Kiro birthday challenge. #BuildWithKiro #TeamKiro
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article