Spec format

Directory structure

.specdrive/
├── config.yaml
├── product.md              # Product steering
├── tech-stack.md           # Stack (flutter | nextjs | react-native)
├── structure.md            # Folder architecture
├── coding-style.md         # Conventions
└── specs/
    └── {feature-slug}/
        ├── meta.yaml       # Gates, phase, IDs
        ├── requirements.md
        ├── gap-analysis.md
        ├── design.md
        └── tasks.md

Gate order

Tracked in meta.yaml under gates: with status, timestamp, and approver.

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

gap-analysis.md

Phase 2 — codebase gaps. Compare requirements to what already exists in the repo.

• Existing code inventory (screens, routes, components)
• Requirements coverage matrix
• Gaps to bridge before implementation
• Files to create / modify
• Recommended implementation order

design.md

Phase 3 — UI/UX HOW. The primary frontend design artifact.

• User flow and screen map
• Component hierarchy and specifications
• Navigation table
• State management (BLoC, Zustand, etc.)
• Design tokens and platform behavior
• Accessibility requirements
• Requirement traceability (REQ → design elements)

tasks.md

Phase 4 — implementation plan. Sequenced frontend tasks.

• Waves of tasks (TASK-001, …)
• Status, requirements refs, design refs
• Files to touch, acceptance criteria
• Dependencies between tasks

meta.yaml example

specdriveVersion: "1.0"
id: SPEC-001
slug: product-review
title: Product Review Screen
type: feature
stack: flutter
phase: design
gates:
  requirements:
    status: approved
  gap_analysis:
    status: approved
  design:
    status: pending
  tasks:
    status: pending

Full specification

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