spec-generator

Where it fits

• Feature pipeline, step 2, Phase 1. Writes requirements.md. Runs next: Phase 2.
• Feature pipeline, step 3, Phase 2. Writes design.md. Runs next: sdd:spec-design-review.
• Feature pipeline, step 5, Phase 3. Writes tasks.md. Runs next: sdd:spec-task-review.
• Bugfix pipeline, step 1, bugfix. Writes bugfix.md, design.md, tasks.md. Runs next: subagent-driven-development.

Steps and outputs come from sdd:spec-workflow.

Overview

Generate or update structured specifications under project/work-items/ following the Kiro spec workflow. This skill supports:

1. New Specs: Creating Feature or Bugfix specs from scratch.
2. Existing Specs: Reviewing and updating existing specs to reflect new requirements or discovered changes.

Each spec produces or maintains three documents through an interactive three-phase process with user review gates between phases.

Discovery Handoff (Feature Specs Only)

sdd:spec-discovery creates project/work-items/{NN}-{name}/, writes discovery.md there and passes the directory path when it invokes this skill.

1. Take the work-item path from the handoff.
2. When invoked directly for a feature, find the work item whose discovery.md matches the topic and has status Approved. Do not copy anything: the file stays in the work item.
3. Read discovery.md as context for generating requirements.md.

discovery.md is reference material: it captures agreed direction and constraints but is not a formal spec document. It will be deleted after sdd:spec-task-review passes.

For bugfix specs, skip this section entirely, as there is no discovery output.

Updating Existing Specs

When the user asks to “update” or “review” an existing spec:

1. Identify the Spec: Ask for the spec number or directory name.
2. Verify State: Read the existing requirements.md (or bugfix.md), design.md, and tasks.md.
3. Identify Changes: Ask the user what needs to be changed or updated.
4. Interactive Update: Follow the same three-phase workflow (Requirements/Bugfix -> Design -> Tasks), but instead of creating new files, update the existing ones while maintaining the project’s formatting and tracing standards.
5. Task Management: If updating tasks.md, ensure any completed tasks remain marked as completed ([x]) unless the change requires re-implementing them. Add new tasks following the Task Sequencing Rules.

Spec Types

Type	Workflow	Documents
Feature (Requirements-First)	Requirements -> Design -> Tasks	requirements.md, design.md, tasks.md
Feature (Design-First)	Design -> Requirements -> Tasks	design.md, requirements.md, tasks.md
Bugfix	Bug Analysis -> Design -> Tasks	bugfix.md, design.md, tasks.md

Reference Materials

Before generating any spec, read these for format and process guidance:

• Templates: project/work-items/templates/ – structural templates for each document, held under feature/, bugfix/ and gates/
• Spec Documentation: project/work-items/spec-documentation/ – detailed process documentation
• Existing Specs: completed work items under project/work-items/[0-9]*/ (those containing implementation-audit.md) – real examples of completed specs for content quality reference

A repository adopting the pipeline for the first time has none of these. When a reference location is missing, say so once in your reply and carry on: the document structures in this skill and in references/ are the templates. Do not stop to ask for the missing reference directories and do not create them. The work item directory under project/work-items/ is different: Step 1 creates it unless sdd:spec-discovery already did, even when it is the first one in the repository.

Step 1: Gather Input & Determine Spec Type

When a discovery.md header supplies the description, spec type and workflow, take them from there and ask only what it lacks. Otherwise ask the user:

1. Description: What feature or bug are you speccing?
2. Spec type: Feature or Bug?
3. Workflow (features only): Requirements-First or Design-First?

Then, unless the work-item directory already exists, determine the next available sequential number:

# Scan existing directories in project/work-items/ for numbered prefixes
ls -d project/work-items/[0-9]*/ 2>/dev/null | sort -t/ -k3 -V | tail -1

Without a shell, glob project/work-items/[0-9]*/ instead. No match means this is work item 01; that includes a repository with no project/work-items/ tree at all.

When the directory exists, skip numbering and use it. Otherwise create the directory under project/work-items/ with the next sequential number, creating project/work-items/ itself if it does not exist yet. Spec documents never go in the repository root, even when the repository has no project/ tree:

• Features: {NN}-{kebab-case-name}/ (e.g., 01-user-authentication/)
• Bugs: {NN}-{kebab-case-name}/ (e.g., 02-null-pointer-on-login/)

Step 2: Gather Existing Context

Before generating any document, read relevant project documentation to ensure accuracy and consistency with the existing codebase.

Required Context Gathering

1. OpenAPI Specification: Read the project’s API spec to understand existing endpoints, schemas, and patterns:

   # Find the OpenAPI spec
   Glob pattern: **/openapi.yaml
   Glob pattern: docs/apis/**/*.yaml

2. Architecture Documentation: Understand the current system architecture:

   Glob pattern: **/ARCHITECTURE.md
   Glob pattern: project/architecture/**
   Glob pattern: docs/architecture/**

3. Domain Terminology: Use correct domain language throughout specs:

   Glob pattern: **/UBIQUITOUS_LANGUAGE.md

4. Existing Specs: Review completed specs for content quality and style reference:

   Glob pattern: project/work-items/[0-9]*/*.md

5. Existing Tests: Understand current test patterns and coverage:

   Glob pattern: **/*Test*.kt
   Glob pattern: **/*.test.ts
   Glob pattern: **/*.spec.ts

   and any other test-file pattern the project uses (see AGENTS.md).

6. Knowledge Base: Check for relevant domain knowledge:

   Glob pattern: knowledge-base/**/*.md

When Context Is Missing

A glob that matches nothing is information, not a blocker. Record in the document’s Introduction which sources were unavailable (for example, no openapi.yaml yet, so API consistency could not be checked against an existing contract) and generate from what the user supplied. Only stop to ask when the description itself is too thin to write requirements from.

Why This Matters

• Prevents designing APIs that conflict with existing endpoints
• Ensures data models align with existing schemas
• Maintains consistent naming conventions across the codebase
• Avoids duplicating or contradicting existing architecture decisions
• Identifies reusable components and patterns

Step 3: Phase 1 – First Document

Generate the first document based on spec type. Present to user for review. Iterate until approved.

The user review stop applies to every spec type. A bugfix spec skips the review skills, not the user reviews: it stops after bugfix.md and again after design.md.

Requirements-First Feature -> requirements.md

Follow the template at project/work-items/templates/feature/requirements.md.

Structure:

# Requirements Document

## Introduction

[Brief description of the feature, its purpose, and context within the project.]

## Glossary

- **Term_Name**: Definition used throughout this document

## Requirements

### Requirement 1: [Requirement Title]

**User Story:** As a [role], I want [capability], so that [benefit].

#### Acceptance Criteria

1. THE [Glossary_Term] SHALL [behavior]
2. WHEN [condition], THE [Glossary_Term] SHALL [behavior]
3. IF [condition], THEN THE [Glossary_Term] SHALL [behavior]

Key conventions:

• Use EARS notation (Easy Approach to Requirements Syntax): WHEN, THE [Glossary_Term] SHALL, IF...THEN
• The subject of every acceptance criterion is a glossary term (THE Notification_Service SHALL), never the system, so that requirements, design components and tests name the same thing
• Every requirement has a User Story with acceptance criteria
• Acceptance criteria are numbered within each requirement (1.1, 1.2, … 2.1, 2.2, …)
• Define a Glossary of domain terms used as subjects in EARS statements
• Include edge cases and error handling requirements

Design-First Feature -> design.md

Follow the template at project/work-items/templates/feature/design.md.

Read the Approach, Constraints and Decisions sections of discovery.md as input to design.md.

See Design Document Sections below for the full structure and required sections.

Bugfix -> bugfix.md

Follow the template at project/work-items/templates/bugfix/bugfix.md.

Structure:

# Bugfix Requirements Document

## Introduction

[Brief description of the bug, where it occurs, and its impact.]

## Bug Analysis

### Current Behavior (Defect)

1.1 WHEN [condition] THEN the system [incorrect behavior]
1.2 WHEN [condition] THEN the system [incorrect behavior]

### Expected Behavior (Correct)

2.1 WHEN [condition] THEN the system SHALL [correct behavior]
2.2 WHEN [condition] THEN the system SHALL [correct behavior]

### Unchanged Behavior (Regression Prevention)

3.1 WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]
3.2 WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]

Key conventions:

• Current Behavior describes what’s broken (the defect)
• Expected Behavior describes the correct behavior using SHALL
• Unchanged Behavior documents what must NOT change using SHALL CONTINUE TO
• Enumerate every existing neighboring behavior the fix could plausibly disturb, drawing from the issue report, affected service, and architecture notes, not only behaviors the reporter explicitly named.
• Number items with section prefix (1.1, 1.2, 2.1, 2.2, 3.1, 3.2)

Step 4: Phase 2 – Second Document

Generate the second document derived from the approved first document. Present to user for review. Iterate until approved.

Requirements-First Feature -> design.md

Derive the technical design from the approved requirements:

• Architecture that satisfies all requirements
• Components mapped to requirement areas
• Correctness Properties that validate requirements (with **Validates: Requirements N.N** tracing)
• Testing strategy including property-based tests

Design-First Feature -> requirements.md

Derive feasible requirements from the approved design:

• Requirements that are achievable given the architecture
• EARS notation requirements traced to design components
• User stories that match the system’s capabilities

Bugfix -> design.md

Follow the template at project/work-items/templates/bugfix/design.md.

Derive the fix design from the approved bug analysis:

• Glossary with Bug_Condition, Property, and Preservation terms
• Bug Details with fault condition and formal specification
• Hypothesized Root Cause with code-level analysis
• Correctness Properties:
  • Property 1: Fault Condition – bug condition inputs produce expected behavior
  • Property 2: Preservation – non-bug inputs produce same behavior as before
• Fix Implementation with specific file/function/line changes
• Testing Strategy with exploration, fix checking, and preservation checking

Design Document Sections

See references/design-document-sections.md for the full list of required and optional sections, and design quality standards.

Step 5: Design Review Gate (Feature Specs Only)

After the user approves design.md AND both requirements.md and design.md exist, invoke the sdd:spec-design-review skill as a quality gate before generating tasks.

Timing by workflow type:

• Requirements-First: After Phase 2 (design.md) is approved
• Design-First: After Phase 2 (requirements.md) is approved (both documents now exist)
• Bugfix: Skip this gate. Present design.md to the user for review and, once approved, proceed to tasks.md

Process:

1. Invoke the sdd:spec-design-review skill
2. The skill validates alignment between requirements.md and design.md
3. It also checks architecture consistency with the existing codebase
4. A design-review-summary.md is generated in the spec directory

Based on review outcome:

• APPROVED: Proceed to tasks.md generation

• APPROVED WITH ISSUES: Inform the user of issues found. Recommend addressing major issues but allow proceeding to tasks.md if the user chooses

• BLOCKED: Do NOT proceed to tasks.md. Then, in this order:

  1. Present every critical finding.
  2. Sort the findings into those that need a decision only the user can make and those that do not.
  3. For each finding that needs no such decision, draft the concrete revision to the affected document in this same turn: the exact API parameter, validation rule, error code or component change. Do not defer a revision because a different finding is still open.
  4. Put only the findings that need a decision to the user, each with its options.
  5. State that sdd:spec-design-review is re-run after the revisions and before tasks.md generation continues; iterate until the review passes.

Both documents approved -> sdd:spec-design-review -> [APPROVED] -> tasks.md
                                                   -> [BLOCKED]  -> Fix documents -> Re-review

Step 6: Phase 3 – Tasks

Generate tasks.md derived from both approved documents. Present to user for review.

Follow the template at project/work-items/templates/feature/tasks.md, or project/work-items/templates/bugfix/tasks.md for a bugfix spec.

Task Sequencing Rules

1. API-First: If the spec involves changes to existing APIs or new endpoints, the first task MUST be updating the OpenAPI spec file (openapi.yaml) and running the project’s type-generation script (if API types are generated from openapi.yaml). Implementation tasks MUST follow this and build against the updated spec.

2. Build-and-Test After Each Task: Every implementation task MUST include a sub-task to build the project and run relevant tests. This catches regressions early and ensures incremental correctness.

3. Test Coverage Tasks: Include explicit tasks for adding or updating tests at each layer:

   • Unit tests: For new/modified services, handlers, components
   • Integration tests: For cross-component interactions (e.g., Lambda handler -> service -> repository)
   • E2E tests: For user-facing flows (in the e2e/ directory)

4. Mandatory Ending Tasks: Every tasks.md MUST conclude with the following tasks in order:

   • Update OpenAPI spec (if API changes were made but the spec wasn’t updated as the first task)
   • Add or update E2E tests in the e2e/ directory (if applicable)
   • Update documentation and knowledge base: Update relevant docs (architecture, README, knowledge-base/README.md), add/update auto-memory if patterns changed
   • Final validation: Run the full build and ALL tests (backend, frontend and E2E, each if the project has one) to ensure the system compiles and there are no failures

Checkpoint Tasks

Insert checkpoint tasks every 3-5 implementation tasks (project default; adjust in the template if your project sets a different bar). Checkpoints MUST:

• Run the project’s full build (backend and frontend, each if the project has one), as documented in AGENTS.md or the README
• Run all tests (unit, integration)
• Verify no regressions in existing functionality
• Pause for user review if questions arise

Structure

# Implementation Plan

## Overview

[Brief description of the implementation approach.]

## Tasks

- [ ] 1. Update OpenAPI spec and regenerate types
  - Update `openapi.yaml` with new/modified endpoints and schemas
  - Run the project's type-generation script to regenerate API types
  - Verify generated types compile
  - _Requirements: N.N, N.N_

- [ ] 2. [Backend implementation task]
  - [Sub-task description]
  - Write unit tests for new/modified code
  - Run the project's backend build and test command, as documented in `AGENTS.md` or the README
  - _Requirements: N.N_

- [ ] 3. [Frontend implementation task]
  - [Sub-task description]
  - Write unit tests for new/modified components
  - Run the project's frontend build and test command, as documented in `AGENTS.md` or the README
  - _Requirements: N.N_

- [ ] 4. Checkpoint - [Milestone description]
  - Run full backend build and tests
  - Run full frontend build and tests
  - Verify no regressions

... [Remaining tasks] ...

- [ ] N-3. Add/update integration tests
  - [Test scenarios covering cross-component interactions]
  - _Requirements: N.N_

- [ ] N-2. Add/update E2E tests
  - Add/update tests in `e2e/` directory
  - Run E2E tests against mock server
  - _Requirements: N.N_

- [ ] N-1. Update documentation and knowledge base
  - Update architecture docs if system design changed
  - Update `knowledge-base/README.md` with new patterns or decisions
  - Update auto-memory if project conventions changed
  - _Requirements: N.N_

- [ ] N. Final validation
  - Run the project's full backend build and test command (if the project has one)
  - Run the project's full frontend build and test command (if the project has one)
  - Run the project's E2E test command (if the project has one)
  - Verify the OpenAPI spec is up to date: the type-generation script produces no diff
  - Confirm all tests pass with zero failures

Key conventions:

• Numbered tasks with checkbox format: - [ ] N. [Task title]
• Sub-tasks as indented bullet points under each task
• Requirement tracing: _Requirements: N.N, N.N_ on each task
• Build/test sub-tasks: Every implementation task includes a build+test step
• Optional tasks marked with * prefix on the task number: - [ ] *N. [Task title]
• Checkpoint milestones every 3-5 tasks: - [ ] N. Checkpoint - [description]
• Property-based test tasks (optional, marked with *): write PBT tests for correctness properties
• Notes section with implementation guidelines
• Status Summary table tracking overall progress

Step 6b: Task Review Gate (Feature Specs Only)

After the user approves tasks.md for a feature spec, invoke the sdd:spec-task-review skill as a quality gate before implementation.

For bugfix specs: Skip this gate entirely. Proceed directly from tasks.md to execution.

Process:

1. Invoke the sdd:spec-task-review skill
2. The skill validates requirements coverage, design coverage, sequencing, implementability, and completeness
3. A task-review-summary.md is generated in the spec directory

Based on review outcome:

• APPROVED: discovery.md is deleted. Proceed to sdd:spec-qa-review plan mode.
• APPROVED WITH ISSUES: Inform user. Recommend fixes but allow proceeding; discovery.md is deleted when proceeding.
• BLOCKED: Fix tasks.md issues, re-run review.

Step 7: Quality Checklist

Before finalizing each document, verify against the checklists in references/quality-checklist.md covering requirements, design, and tasks documents.

Step 8: Execution Support

When the user asks to implement tasks:

1. Tasks can be executed one at a time or all at once (only incomplete required tasks).
2. Post-Task Validation & Commit: After completing every top-level task (e.g., Task 1, Task 2):
   • Run the project build and all relevant tests.
   • If the build and tests pass, commit the changes using the project’s commit conventions (see AGENTS.md).
   • If the build or tests fail, fix the issue before proceeding to the next task.
3. Update task checkboxes as work progresses: - [ ] -> - [x]
4. Update the Status Summary section to reflect current progress.
5. At Checkpoint tasks, run full builds and tests and verify before proceeding.
6. Never skip test or build steps – these are not optional, they catch regressions early.

Build & Test Commands Reference

Each project defines its own commands: read AGENTS.md or the README and keep those handy during execution. Each row applies only if the project has that layer.

What	Where to find it
Backend build + tests	The project’s backend build and test command
Frontend build + tests	The project’s frontend build and test command
E2E tests (mock)	The project’s E2E test command
E2E tests (production)	The project’s E2E smoke command against the production base URL
Regenerate API types	The project’s type-generation script (if API types are generated from openapi.yaml)
Check OpenAPI spec freshness	Run the type-generation script and verify no git diff

Workflow Summary

User describes feature/bug
        |
        v
  Determine spec type
  & create directory
        |
        v
  Discovery handoff           <-- Read discovery.md in work item
  (Feature specs only)
        |
        v
  Gather existing context
        |
        v
+-- Feature (Req-First) --> requirements.md --> design.md --> sdd:spec-design-review --> tasks.md --> sdd:spec-task-review
|
+-- Feature (Design-First) -> design.md --> requirements.md --> sdd:spec-design-review --> tasks.md --> sdd:spec-task-review
|
+-- Bugfix -----------------> bugfix.md --> design.md --> tasks.md (no review-skill gates)
                                |              |              |
                                v              v              v
                           User Review    User Review    User Review
                           & Iterate      & Iterate      & Iterate

---

The story behind this skill

Read the post on Substack, published 7 September 2026. The post describes the skill as it was then, and this page shows it as it is now.

See it in the worked example

• requirements.md
• design.md
• tasks.md

The worked example walks through every artefact.

Source

View SKILL.md on GitHub