Section 5 · Kiro workflow
steering.md · requirements.md · design.md · tasks.md
Persistent steering memory plus the execution spine — what each file needs, must include, and when it is ready.
steering.md is persistent project memory (stack, coding standards). requirements.md is the “what” for a single feature on the execution spine; design.md and tasks.md follow after the Clarification Gate.
Execution spine — steering vs requirements
| File | Purpose | Scope |
|---|---|---|
| steering.md | Persistent project memory (e.g. tech stack, coding standards) | Whole repo, every session |
| requirements.md | The “what” for a single feature (from the execution spine) | One feature or change set |
steering.mdSteeringAudience: Human + AILong-lived context agents reload every session — so they stop guessing stack, style, and project rules.
Persistent project memory: tech stack, coding standards, folder conventions, and pointers to mission/roadmap — not feature-specific acceptance criteria.
Must include
- Tech stack — frameworks, versions, package manager, deploy target
- Coding standards — naming, patterns, lint/format commands
- Project structure — where specs, app code, and docs live
- Links to constitution.md, tech-stack.md, or AGENTS.md where applicable
- Exact commands agents should run (build, test, lint)
Must not
- Replace requirements.md for a single feature’s acceptance criteria
- Drift from what the repo actually uses — update when stack or standards change
- Secrets or credentials — steer behavior, not store keys
Ready when
- ✓A new agent session can orient without re-pasting stack context in chat
- ✓Aligns with tech-stack.md and team constitution
When to update
When stack, standards, or repo layout change — steering.md is living memory, like code.
Workflow order
Load steering first, then shape this feature’s requirements. Do not skip to tasks or code while the Clarification Gate is open.
- 0
steering.mdLoad persistent memory — stack, standards, commands
- 1
requirements.mdshape-spec → clarify → gate (this feature’s what)
- 2
design.mdArchitect how — after gate
- 3
tasks.md/create-tasks → dependency-ordered checklist
- 4
Code + verify/implement one task at a time; MCP for evidence
requirements.mdWhatAudience: Human + AIThe “what” for one feature on the execution spine — intent for this change, not the whole product forever.
Per-feature living spec: user outcomes, measurable acceptance criteria, resolved ambiguity. Read steering.md first for context; requirements.md defines this feature’s contract.
Must include
- Vision or problem statement — who hurts and why
- User stories with testable acceptance criteria (EARS patterns)
- Explicit out-of-scope and DO NOT constraints
- Clarification Gate — open items tracked until resolved
- Roles, data lifecycle, and error behavior where the feature touches them
Must not
- Implementation details (frameworks, file names, class diagrams) — those belong in design.md
- Vague completion language (“make it work”, “looks good”)
- Unresolved [OPEN] items while claiming ready to build
Ready when
- ✓Clarification Gate passes — zero unresolved open items
- ✓Success criteria are observable and measurable
- ✓Ready for Plan Checklist green (Section 4)
When to update
Whenever scope, success criteria, or constraints change — update before or with code in the same PR.
design.mdHowAudience: Human + AIArchitecture and approach agreed after requirements are clear — so agents implement one coherent system, not improvised structure.
Technical plan: components, data flow, and decisions — aligned with tech-stack.md and constitution tiers.
Must include
- Overview of the technical approach for this feature
- Main components/modules and how data flows between them
- Key design decisions with brief rationale
- References to requirements (which REQ IDs this design satisfies)
- Call out Tier Two changes (schema, dependencies, public API) for human approval
Must not
- Re-copy entire requirements.md — link and trace instead
- Contradict tech-stack.md or constitution.md without an explicit change request
- Skip design and jump straight to large code changes
Ready when
- ✓requirements.md gate has passed
- ✓Design is reviewable — another engineer could implement from it
- ✓No major open architectural questions left in requirements
When to update
When architecture, modules, or integration points change — keep design.md matching what you actually built.
tasks.mdStepsAudience: Human + AIAn ordered, executable checklist — smallest verifiable units — so AI and humans implement and review one step at a time.
Output of /create-tasks: atomic tasks with dependencies, requirement links, and verification steps (exact commands).
Must include
- Tasks broken into atomic, independently verifiable units
- Dependency order — what blocks what
- Link each task to requirement IDs or user stories
- Verification checklist per task — exact commands (e.g. npm run build, npm run lint)
- Checkboxes updated as work completes
Must not
- Created before the Clarification Gate passes
- Monolithic tasks (“build the whole feature”) without verification
- Stale checkboxes — done in code but unchecked in tasks.md
Ready when
- ✓Generated from clarified requirements.md (and informed by design.md)
- ✓Every task has a verification path
- ✓Dependencies form a clear execution order
When to update
After each task completes and at feature sign-off — match tasks.md to reality (Minimal Living Docs Checklist, Section 4).
Practice
Check your understanding
A few minutes of recall now saves rereading later.
1.Which file holds persistent standards shared across every feature?
2.When is design.md written?
3.How should tasks be implemented?
Order the spec files as an agent should load and produce them. Use the arrows to move a step, then check your order.
- 1requirements.md
- 2Code + verify
- 3tasks.md
- 4design.md
- 5steering.md