The Kiro style
Three documents, with a human gate between each. The default.
- The shape
- The two kinds of spec
- Phase by phase
- Checkpoints
- What each phase is handed
- Files it produces
The shape
requirements.md -> design.md -> tasks.md -> implement
Requirements are written in conversation. Design and tasks are drafted by the engine from what came before. Implementation happens in your own chat, one task at a time, with a ticked checkbox as the definition of done.
The two kinds of spec
＋ New Spec asks which one you want:
| Phases | |
|---|---|
| Feature | requirements → design → tasks → implement |
| Bug fix | requirements → tasks → implement |
A bug fix skips design. A one-line fix does not need a design document, and a process that demands one teaches people to write a paragraph of nothing to get past the gate.
That skip is declared once, in the style’s specTypes: list — not as a
conditional inside a stage, and not as a branch inside a prompt. The
phases a spec type visits are its list.
Phase by phase
requirements
Written during the intake chat, before the pipeline really starts — so in the normal case this stage is already satisfied by the time the walk reaches it.
It exists as a stage for the case where intake did not finish. Its gate is
manual, so a spec with no requirements.md parks here and waits for a
human rather than inventing requirements from a one-line title.
design
A new session, seeded only by requirements.md.
The gate that matters for requirements lives here, on the next phase,
not on the one that wrote the file. What a human approves is
“requirements.md is good enough to build on” — and that is a judgement
you make when you are about to depend on it.
tasks
Produces tasks.md: a numbered plan (1, 1.1) carrying a dependency
graph between tasks, expressed as ordered waves. Tasks in the same
wave may run at the same time; a wave begins only once every task in
every earlier wave is finished and ticked. Two tasks share a wave only
when they touch different files.
Every task ends green. The repository builds and its tests pass at the end of each task, not just at the end of the plan. That is what decides where the boundaries go, and it is a stronger rule than “one concern per task” — an interface and its implementation, a changed signature and every caller it breaks, a behaviour and the test that proves it are each one task. Splitting any of them leaves the tree red in between, and a plan you cannot stop half-way through is a script rather than a plan.
There is no requires: key anywhere in the style file. What a stage
needs is whatever the prior stages of this spec type produced — for a
Feature that is requirements.md and design.md; for a Bug fix, which
has no design stage, just requirements.md. Writing it out by hand would
state the pipeline twice and eventually get one of the two wrong.
implement
The engine does not wait here. This is an implement stage: no
artifacts, never satisfied, terminal.
Each task launches a native Copilot chat from the panel’s implement lens.
Git is the record, and the ticked checkbox in tasks.md is the
completion signal.
No gate, either — the plan is approved by starting its first task.
Checkpoints
checkpoints: required (the default) puts checkpoint tasks into the
plan — a top-level task that runs the full test suite and confirms it
passes. Set it to optional or none in .local-workflows/config.yml.
A checkpoint verifies; it does not ask. It never waits for a human, and a passing one is not a decision point — the plan carries straight on into the tasks after it. Whoever started the plan asked for it to be carried out; stopping halfway to ask whether to continue answers a question they already answered.
A failing checkpoint is usually work rather than a wall:
| The broken test | What happens |
|---|---|
| written by this spec’s tasks, or broken by them | fixed, re-run, ticked, plan continues |
| already red before the plan started, in code this spec does not touch | reported, plan continues |
| a failure that cannot be fixed | the plan stops there, checkpoint left unticked |
Checkpoints sit after a top-level task, never after a sub-task.
What each phase is handed
Not the whole folder, and not a conversation:
intro— read first by every phase. What this process is, what the phases are, and that the document is the deliverable rather than the reply. Phase prompts can then be about doing their own job well instead of re-explaining the pipeline they sit in.grammar— the parser-critical rules, given to every phase. The implement phase ticks checkboxes, so it needs the checkbox rules as much as the phase that writes them.- house style — given only to the stage writing that document
(
format-requirements.mdtorequirements, and so on). - the documents from prior stages — as files.
Files it produces
| File | Written by |
|---|---|
requirements.md |
the intake chat |
design.md |
design |
tasks.md |
tasks |
All under .local-workflows/specs/<spec>/, all committed.
Kiro is the default, so if you have written no .local-workflows/config.yml
at all, this is the process you are running.