Spec format

Kiro-style artifacts per feature: brief → requirements → gap → HLD → LLD → tasks → implement → validate, tracked by spec.json.

Directory structure

.specdrive/
├── config.yaml
├── steering/                 # source of truth for YOUR repo
│   ├── product.md
│   ├── tech.md
│   ├── structure.md          # real package paths — edit me
│   ├── coding-style.md
│   └── verticals/            # optional domain notes
└── specs/
    ├── features/YYYY-MM-DD[-TICKET]-<slug>/
    │   ├── spec.json         # phase, approvals, ready_for_implementation
    │   ├── brief.md
    │   ├── requirements.md
    │   ├── gap-analysis.md
    │   ├── design-hld.md
    │   ├── design-lld.md
    │   ├── decisions.md      # optional ADRs
    │   ├── tasks.md          # checkbox tasks [ ] / [x]
    │   └── impl-validation.md
    ├── bugs/…
    └── tech-debt/…

Gate order (YOUR JOURNEY)

1 brief → approve → 2 requirements → approve → 3 gap_analysis → approve → 4 design_hld → approve → 5 design_lld → approve → 6 tasks → approve (last human gate) → 7 implement (Design2Code optional on UI+Figma) → 8 validate

Tracked in spec.json: each gate has generated + approved. Implement unlocks only when ready_for_implementation: true (after tasks approved).

requirements.md

Phase 1 — WHAT. User stories with EARS acceptance criteria.

  • Overview and user value
  • User stories (REQ-001, REQ-002, …)
  • EARS patterns: Ubiquitous, Event-driven, State-driven, Unwanted event
  • Non-functional requirements (a11y, performance)
  • Out of scope

brief.md

Kickoff. Problem, goals, scope in/out, approach, open questions. Human-approved first.

gap-analysis.md

Codebase gaps. Compare requirements to what already exists — cite real file paths from the scan + steering. No invented modules.

  • Existing code inventory
  • Requirements coverage matrix
  • Gaps / files to create or modify
  • Recommended implementation order

design-hld.md + design-lld.md

HOW — split like Kiro.

  • HLD: architecture overview, flows, screen/module map
  • LLD: concrete classes/files, interfaces, state machines, a11y/semantics
  • Both must follow steering/structure.md package paths

tasks.md

Implementation plan. Small, file-scoped checkbox tasks.

  • Waves of tasks (TASK-001, …)
  • Markdown checkboxes - [ ] / - [x]
  • Real file paths from LLD / gap analysis
  • Status, requirements refs, dependencies

spec.json example

{
  "specdriveVersion": "1.0",
  "id": "SPEC-001",
  "slug": "product-review",
  "folderName": "2026-07-20-product-review",
  "title": "Product Review Screen",
  "type": "feature",
  "stack": "flutter",
  "phase": "design_hld",
  "ready_for_implementation": false,
  "gates": {
    "brief": { "status": "approved", "generated": true, "approved": true },
    "requirements": { "status": "approved", "generated": true, "approved": true },
    "gap_analysis": { "status": "approved", "generated": true, "approved": true },
    "design_hld": { "status": "pending", "generated": true, "approved": false },
    "design_lld": { "status": "pending", "generated": false, "approved": false },
    "tasks": { "status": "pending", "generated": false, "approved": false }
  }
}

Full specification

See the complete format document on GitHub: SPEC-FORMAT.md