Specs in the Terminal
Specs are the IDE's structured workflow, now in the terminal. Instead of "build X", you agree on what (requirements), how (design) and steps (tasks) as files, then run the tasks.
What a spec produces
| File | Holds |
|---|---|
requirements.md (or bugfix.md) | User stories and acceptance criteria, or bug analysis (current, expected, unchanged behavior) |
design.md | Architecture, sequence diagrams, error handling, test strategy |
tasks.md | Discrete, trackable implementation tasks |
The CLI flow
Start with /spec new <name>. Per the V3 announcement you can then review requirements and design, leave inline comments on the document, and choose which tasks to run, all from the terminal. A community write-up of an earlier build also reports a description step after the name, then a choice of Feature, Bug or Quick Spec. Treat that detail as version-dependent and check it in your own session.
| Type | Use when |
|---|---|
| Feature, requirements-first | You know the behavior; design follows |
| Feature, design-first | You know the architecture; requirements follow |
| Bugfix | Root cause and regression risk matter |
| Quick Spec | Well-understood work; all three files generated without approval gates |
Running tasks
"Run all tasks" builds a dependency graph from tasks.md and runs independent tasks concurrently in waves: wave 1 has no dependencies, wave 2 depends only on wave 1, and so on. Waves run in order; tasks inside a wave run together. Hook into this with PreTaskExec and PostTaskExec from lesson 2, for example to run tests after each task.
V3 also has a read-only Plan agent. A community write-up reports that approving its plan hands off to the default agent and starts implementing without a manual mode switch. Verify in your build before relying on it.
Retrieval check
Which file should hold acceptance criteria for a new feature spec?
Right. Requirements capture stories and acceptance criteria; design and tasks come after.
Acceptance criteria are the what, so they sit in requirements.md.
Task B depends on task A. Tasks C and D depend on nothing. How do they run?
Right. Wave 1 is every task with no dependencies (A, C, D); B waits for wave 2.
Wave 1 contains all tasks with no dependencies: A, C and D. B follows once A is done.
A one-line, well-understood change needs a spec trail. Which type fits?
Right. Quick Spec skips the approval gates for well-understood work.
Quick Spec is built for work you already understand: it generates all three artifacts in one pass.
Practice
- In a scratch git repo, start
kiro-cliand run/spec new rate-limit. - Pick Feature, describe a small change, and read the generated
requirements.md. Leave one inline comment and send it back. - Approve design, then look at
tasks.md. Which tasks would form wave 1? - Run a single task only, and check the diff with
git diff. - Not sure what a prompt means? Ask Kiro: "use introspect to explain
/spec".