Topic: Appendix A. How the Textbook Relates to Spec Kit and Kiro
Difficulty level: Medium
Estimated study time: 3-4 hours of active study + 2 hours of practice
Prerequisites: Basic understanding of SDD (Specification-Driven Development)
Familiarity with Markdown formatting
Experience working with at least one AI assistant for programming
Understanding of basic project management concepts (roadmaps, requirements, planning)
Learning objectives: Map the seven textbook artifacts with corresponding elements in Spec Kit and Kiro using a correspondence table
Justify the choice of format (textbook/Spec Kit/Kiro) for a specific project based on criteria from the appendix
Migrate a process from one system to another while preserving the meaning of artifacts, not just their names
Formulate explicit validation facts in validation.md for a hypothetical project
Identify the shortcomings of the simplified textbook format and propose additional conventions for a large team
Overview: This appendix of the SDD textbook reveals the relationship between the author's specification format (files mission.md, tech-stack.md, roadmap.md, requirements.md, plan.md, validation.md, QWEN.md) and two industrial systems: Spec Kit and Kiro. The key thesis is that the format should not become dogma; what matters is preserving intent, plan, verification, and decisions in reviewable artifacts. The textbook is intentionally simplified for learning and direct work with Qwen Code, while Spec Kit and Kiro offer richer infrastructure for teams, templates, and integrations. Studying this appendix will enable the reader to move freely between systems, adapt processes to team needs, and make informed decisions about tooling choices.
Key concepts: Author's sdd dialect for qwen code: Seven Markdown files forming a complete specification cycle: from mission to validation. The format is designed for direct reading by an AI agent without special CLI utilities. Each file is responsible for a separate aspect of thinking: why the project exists, what constraints, in what order to build, what exactly to build, how to decompose implementation, what facts permit merging, and how the agent should behave.
Validation.md as a separate thinking stage: The main architectural difference of the textbook from alternatives. Instead of distributing verification criteria across tasks, checklists, or plan analysis — an explicit file with facts that determine whether a branch can be merged. This creates a separate layer of quality thinking, visible before implementation begins.
Spec kit: A specification system with commands like /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.analyze. Provides ready-made templates, extensions, presets, and repeatable workflows. Oriented toward teams with multiple projects requiring a unified standard.
Kiro: A platform with three layers: steering files (permanent rules), specs (specific features), tasks and tests (verifiable path). Tightly integrated with the IDE process, uses agent hooks and steering for agent behavior management.
Artifact correspondence table: A mapping tool between systems. Shows that mission.md = project constitution (Spec Kit) = steering files (Kiro); requirements.md = /speckit.specify + /speckit.clarify = requirements; plan.md = /speckit.plan + /speckit.tasks = design + tasks; validation.md = partially /speckit.analyze + checklists = criteria in tasks and tests.
Process migration through meaning preservation: Adaptation methodology: do not impose file names, but transfer principles — explicit constitution, clarification of ambiguities before planning, separation of architectural decisions from task lists, visible verification facts before implementation, comparison of implementation with artifacts rather than chat memory.
Three kiro layers for migration: Steering files (permanent project rules), specs (specific feature specifications), tasks and tests (verifiable path to implementation). When migrating from the textbook to Kiro, content must be distributed across these layers.
Format selection criteria: Textbook — for learning, small projects, transparency in Markdown, platform independence. Spec Kit — for established teams, ambiguity clarification, extensions, multiple projects. Kiro — for existing Kiro users, IDE integration, built-in specs and agent hooks.
Shortcomings of simplified format: In a large team, additional conventions are required: merge requests, roadmap owners, specification reviews, task templates. These topics are covered in part 16 of the textbook.
Reviewable artifacts as process core: The main meta-principle: it does not matter what files are called or what CLI is used — what matters is that intent, plan, verification, and decisions exist in artifacts that can be reviewed, versioned, and compared with implementation.
Practice exercises: Name: Exercise 1: Building a correspondence table for a hypothetical project
Problem: You are given a project: a mobile app for habit tracking. In the textbook format, files already exist: mission.md ("help users build sustainable habits through gamification"), tech-stack.md (Flutter, Firebase, Provider), roadmap.md (MVP → social features → analytics), requirements.md (list of user scenarios), plan.md (architecture + sprint tasks), validation.md (retention metrics, test coverage). Task: fill out the correspondence table indicating how each textbook file would be represented in Spec Kit (specific commands) and in Kiro (specific layers/files). For validation.md, justify why its separate existence is an architectural decision, not just convenience.
Solution: Step 1: mission.md → Spec Kit: project constitution (introduced via /speckit.init or manually in the specification header); Kiro: steering file project.md or habits-steering.md. Step 2: tech-stack.md → Spec Kit: part of constitution + plan (constraints are recorded in /speckit.clarify, technical plan in /speckit.plan); Kiro: steering file tech-steering.md + design/specs. Step 3: roadmap.md → Spec Kit: order of specifications and tasks, managed via /speckit.tasks; Kiro: list of features in specs/ with priorities. Step 4: requirements.md → Spec Kit: /speckit.specify for functional requirements, /speckit.clarify for ambiguities; Kiro: files specs/habit-tracking.md, specs/gamification.md. Step 5: plan.md → Spec Kit: /speckit.plan for architectural decisions, /speckit.tasks for decomposition; Kiro: design/architecture.md + tasks/ with separate tasks. Step 6: validation.md → Spec Kit: partially /speckit.analyze (post-implementation verification) + checklists in tasks; Kiro: acceptance criteria in each task + tests. Justification for separate validation.md: it creates a 'quality frontier' — facts that must be visible before implementation, not derived post-factum. This changes team psychology: the developer sees success criteria before writing code, which prevents 'motion for motion's sake'. In Spec Kit and Kiro, this idea is 'dissolved' into the process, requiring additional discipline. Step 7: QWEN.md → Spec Kit: agent rules in presets; Kiro: agent hooks and steering files for behavior.
Complexity: intermediate
Name: Exercise 2: Migration with meaning preservation — from textbook to Kiro
Problem: A team of 4 developers worked in the textbook format for 3 months. Accumulated: mission.md, tech-stack.md, roadmap.md with 12 items, requirements.md with 8 user stories, plan.md with architectural decision to use Clean Architecture, validation.md with 5 criteria. The team is switching to Kiro. Task: determine what content will go into steering files, specs, tasks, and tests. Special attention: validation.md contains the criterion 'API response time < 200 ms for 95th percentile' — where will it end up in Kiro and how to ensure its visibility BEFORE implementation, as the separate file did?
Solution: Step 1: Steering files (permanent rules): mission.md → project-steering.md; tech-stack.md → tech-steering.md; principles from QWEN.md → agent-steering.md. Step 2: Specs (specific features): each roadmap.md item + related requirements → separate file in specs/: auth-spec.md, habit-creation-spec.md, gamification-spec.md, etc. requirements.md is broken down and embedded into corresponding specs. Step 3: Architecture from plan.md → design/clean-architecture.md (separate system-level spec). Step 4: Tasks and tests: decomposition of plan.md → tasks/ with linkage to specs. Step 5: Performance criterion from validation.md: in Kiro it goes into acceptance criteria of tasks related to API. Problem: it gets 'dissolved' into tasks. To preserve visibility BEFORE implementation: create performance-steering.md in steering files with global SLA; add performance-spec.md as a system spec; include the criterion in Definition of Done for all API tasks; create a separate task 'Set up load testing' in the first sprint. Thus, the meaning of 'explicit verification facts before implementation' is preserved through multi-level duplication and system specifications, although the form has changed.
Complexity: intermediate
Name: Exercise 3: Justifying format choice for a specific context
Problem: Three scenarios: (A) Solo developer learning SDD, creating a pet project on weekends. (B) Product team of 15 people, 3 React projects, needs a unified specification standard for handoff between designers, analysts, and developers. (C) Team of 8 people already working in VS Code with Kiro for a year, satisfied with IDE integration, but feel that specifications get 'blurred' across tasks and chats. For each scenario: choose a format, justify with 3 criteria from the appendix, indicate risk and mitigation.
Solution: Scenario A: Textbook format. Criteria: (1) learning SDD — direct match; (2) project is small — does not require infrastructure; (3) needs platform independence — pet project not tied to corporate licenses. Risk: structure will be lost if scaling up. Mitigation: agree on conventions from part 16 in advance if the project grows. Scenario B: Spec Kit. Criteria: (1) established teams and templates — need unified standard for 15 people; (2) separate ambiguity clarification step — critical for handoff between roles; (3) multiple projects — requires unified standard. Risk: excessive formalization will slow down startup projects. Mitigation: create a 'light' Spec Kit preset for the MVP phase. Scenario C: Kiro with enhancements. Criteria: (1) already working in Kiro — migration costs are minimal; (2) needs IDE integration — preserved; (3) problem of 'blurring' specs — solved by introducing explicit steering files and separate spec files analogous to validation.md. Risk: team perceives enhancements as 'more bureaucracy'. Mitigation: run a workshop showing how explicit specs save time on clarifications in chat.
Complexity: intermediate
Name: Exercise 4: Creating validation.md for an existing Spec Kit project
Problem: Given a Spec Kit project: e-commerce platform. The team uses /speckit.specify for requirements, /speckit.plan for architecture, /speckit.tasks for decomposition, /speckit.analyze for post-implementation verification. Problem: acceptance criteria are 'smeared' across tasks in Jira, there is no single place for pre-merge verification. Task: create validation.md in the spirit of the textbook, extracting and consolidating criteria. Content must include: (1) functional criteria for cart; (2) non-functional (performance, security); (3) 'validation review' process before merge.
Solution: Structure of validation.md: Section 1: Context — 'This file contains facts that must be confirmed before merging into main. No branch is merged without checking against this list.' Section 2: Functional criteria (cart): [F1] Adding item updates counter in < 100 ms without reload; [F2] Changing quantity recalculates cost on client with server validation; [F3] Cart persistence between sessions for authenticated users; [F4] Cart cleared after successful order placement with confirmation. Section 3: Non-functional criteria: [N1] Cart API response time < 200 ms (p95) under 1000 RPS load; [N2] All modification operations require valid JWT; [N3] SQL injections impossible per automated scan results; [N4] Logs contain no PII (regex check in CI). Section 4: Validation review process: Step 1 — branch author fills validation-checklist.md in PR; Step 2 — CI runs automated checks N1-N4; Step 3 — reviewer verifies F1-F4 manually on staging; Step 4 — if non-compliant, merge is blocked with indication of unmet item; Step 5 — after merge, /speckit.analyze to identify hidden risks. Integration with Spec Kit: validation.md does not replace /speckit.analyze, but precedes it, creating a 'gate' before merge. The team keeps familiar commands, but adds an explicit quality artifact.
Complexity: advanced
Case studies: Name: Case: Startup migration from textbook format to Spec Kit as team grew from 2 to 12 people
Scenario: EdTech startup 'LinguaFlow' began with two founders using the textbook format to develop a language learning platform. Over 8 months the project grew: a separate designer, analyst, 6 developers, 2 QA appeared. Files mission.md, roadmap.md, etc. were stored in a shared repository, but the process got 'blurred': developers interpreted requirements.md differently, QA didn't know which criteria to check features against, the analyst made changes to roadmap.md without notifying the team.
Challenge: Three specific problems: (1) requirements.md turned into a 'wall of text' at 400 lines that nobody updated; (2) validation.md existed, but developers merged branches 'remembering' criteria without checking the file; (3) when onboarding new developers, the textbook format required personal explanation from founders — knowledge scaling didn't work. The team considered Kiro (one developer used it in personal projects), but founders feared losing 'simplicity' and 'control'.
Solution: Transition to Spec Kit with meaning preservation: (1) mission.md and tech-stack.md were consolidated into a project constitution, accessible via /speckit.init; (2) requirements.md was split into 8 separate specifications (/speckit.specify), each with an analyst owner; (3) mandatory /speckit.clarify was introduced before planning — designer and analyst must resolve all 'TBD' in requirements; (4) plan.md was transformed into /speckit.plan + /speckit.tasks with explicit separation of architecture and tasks; (5) criteria from validation.md were embedded into task checklists and /speckit.analyze was added as post-implementation verification; (6) a preset 'LinguaFlow-Standard' was created with agent rules inheriting QWEN.md. Key decision: preserve the idea of 'explicit verification facts' through mandatory checklist in /speckit.tasks, rather than a separate file.
Result: After 3 months: onboarding time reduced from 2 weeks to 3 days (new developer runs /speckit.init and gets full context); feature 'returns' from QA to development decreased by 60% (thanks to /speckit.clarify); analyst and designer became specification owners, developers became task owners; founders retained control through constitution review and /speckit.analyze. Unexpected effect: the 'LinguaFlow-Standard' preset turned out so successful that the team began selling Spec Kit implementation consulting to other EdTech companies.
Lessons learned: Simplicity of the textbook format becomes a trap as the team grows — scaling requires institutionalization of processes
The idea of 'explicit verification facts' is transferable between systems, but form must adapt to team culture
Migration resistance is often not about technical risks, but about founders' loss of 'control' — this is solved through their role in constitution and /speckit.analyze
Successful migration requires a 'mediator' who understands both systems — in this case, a developer with Kiro experience who translated principles into Spec Kit language
Related concepts: Artifact correspondence table
Process migration through meaning preservation
Shortcomings of simplified format
Format selection criteria
Name: Case: Integrating validation.md into an existing Kiro project at a corporate bank
Scenario: Digital bank 'FinSecure' team (20 developers, 5 product teams) used Kiro for 2 years. Structure: steering files for compliance requirements, specs for each feature, tasks in Jira with acceptance criteria. Regulatory pressure intensified: required to prove that every feature was checked against 47 control points before reaching production. Existing criteria in tasks turned out fragmented, audit could not reconstruct the full picture.
Challenge: Kiro did not provide a 'single source of truth' for validation facts — they were distributed across tasks, tests, checklists in Confluence. During audit the team spent 3-5 days gathering evidence for one feature. Risk: inability to pass regulatory audit, fines, license restrictions. Migration to another system was excluded due to deep Kiro integration with the bank's IDE and security policies.
Solution: Adapting the validation.md idea within Kiro: (1) a separate 'validation specs' layer was created — files like specs/validation/feature-X-validation.md, mandatory for all features involving money or customer data; (2) validation spec contains 47 control points, grouped by risks, with explicit 'confirming artifact' fields (link to test, log, review); (3) a 'validation gate' step was added to CI — build is blocked if validation spec is not reviewed by security officer; (4) steering file validation-steering.md defines which features require validation spec; (5) an agent hook in Kiro automatically suggests validation spec template when creating specs for critical features. Thus, the meaning of 'separate quality thinking stage' was integrated into Kiro without disrupting existing infrastructure.
Result: Audit preparation time reduced from 3-5 days to 2 hours (all validation specs in one directory with clear structure). First regulatory audit passed without remarks on validation process. Unexpected effect: developers started thinking about compliance earlier — validation spec was created at design stage, not in a rush before release. The team formalized the pattern as 'Kiro Validation Extension' and contributed it to the open-source community.
Lessons learned: An idea from a 'simple' textbook can solve 'enterprise' problems with proper adaptation
Distributed quality criteria create 'hidden debt' — a single source of truth is necessary for regulatory and audit requirements
Integrating a new artifact into an existing system requires automation (CI gate, agent hooks) — otherwise discipline will not hold
Steering files in Kiro are ideally suited for defining policies, while specs are for specific checks: this matches Kiro's original architecture
Related concepts: validation.md as a separate thinking stage
Three Kiro layers for migration
Reviewable artifacts as process core
Process migration through meaning preservation
Study tips: Create a physical or digital 'correspondence map': print the table from the appendix and supplement it with your own examples from your projects — motor memory and visualization enhance retention
Practice 'reverse translation': take a specification in Spec Kit format (/speckit.specify) or Kiro (spec file) and rewrite it in textbook format — this develops deep understanding of structure, not just superficial name recognition
Conduct an 'audit of your project': which artifacts from the correspondence table exist explicitly for you, which are 'dissolved' in chats, memory, tasks? This exercise reveals 'hidden debt' of specifications
Study through comparing three columns: for each artifact ask — 'What is added?', 'What is lost?', 'What changes the thinking order?' — this prevents mechanistic transfer of names without transferring meaning
Use the 'scenario method': invent a specific team (size, experience, existing tools) and justify format choice — better 3 deep scenarios than 10 superficial ones
Focus on validation.md: this is the main architectural difference. Try explaining to a colleague why a 'separate file' changes development psychology — if the explanation is convincing, you understood the essence
Read textbook part 16 in parallel: shortcomings of the simplified format are covered there, and understanding format boundaries is critical for conscious choice
Practice 'translation' at the process level, not just artifacts: how does the /speckit.clarify step in Spec Kit relate to 'ambiguity clarification before planning' in the textbook? This requires understanding workflow, not just file structure
Additional resources: Original sdd textbook for qwen code: Full course text, including part 16 on scaling processes in large teams
Spec kit documentation: Official guides for /speckit.* commands, presets, extensions, and integrations
Kiro documentation: Guides for steering files, specs, agent hooks, and IDE integration
Comparative analysis of sdd tools: Review articles on Spec Kit, Kiro, as well as lesser-known systems (e.g., Aider, Claude Code projects)
Specification patterns in regulated industries: Cases from fintech, healthtech, aerospace on how 'explicit verification facts' solve compliance challenges
Course source materials (knowledge base): Full context on which this guide was generated — for in-depth study of connections between sections
Summary: Appendix A demonstrates that the specification format is a tool, not a dogma. The author's textbook dialect (seven Markdown files from mission.md to validation.md) is intentionally simplified for learning and direct work with Qwen Code, while Spec Kit and Kiro offer industrial infrastructure for teams, templates, and integrations. The main architectural difference of the textbook is validation.md as a separate thinking stage about quality, creating a 'frontier' of verification facts before implementation. The correspondence table enables moving between systems while preserving artifact meaning. Format choice depends on context: textbook for learning and small projects, Spec Kit for teams with established processes and multiple projects, Kiro for deep IDE integration and agent hooks. Successful adaptation requires understanding not only 'what' to transfer, but 'why' — intent, plan, verification, and decisions must live in reviewable artifacts regardless of the chosen platform.