Specs in the Terminal

Lesson 4 · Kiro CLI v3 for v2 users. Time: 10 minutes. Tangible win: generate and review a real spec, then run one task.

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.

Primary source Specs — kiro.dev. Spec types, the three files, parallel task waves. About 6 minutes. The CLI flow itself is described in the V3 announcement.

What a spec produces

FileHolds
requirements.md (or bugfix.md)User stories and acceptance criteria, or bug analysis (current, expected, unchanged behavior)
design.mdArchitecture, sequence diagrams, error handling, test strategy
tasks.mdDiscrete, 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.

TypeUse when
Feature, requirements-firstYou know the behavior; design follows
Feature, design-firstYou know the architecture; requirements follow
BugfixRoot cause and regression risk matter
Quick SpecWell-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.

Plan agent

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

  1. In a scratch git repo, start kiro-cli and run /spec new rate-limit.
  2. Pick Feature, describe a small change, and read the generated requirements.md. Leave one inline comment and send it back.
  3. Approve design, then look at tasks.md. Which tasks would form wave 1?
  4. Run a single task only, and check the diff with git diff.
  5. Not sure what a prompt means? Ask Kiro: "use introspect to explain /spec".
Ask me to compare Requirements-First and Design-First for a project you actually have in mind. Anything unclear? Ask.