Spec Syntax (Markdown)

SpecLeft specs are plain Markdown with YAML frontmatter. Each file describes one feature, story, or scenario.

Directory structures

Specs can be organized in two ways:

Flat structure

.specleft/specs/
└── authentication.md
└── reset-password.md

OR

Hierarchical structure (recommended for larger projects)

.specleft/specs/
└── authentication/
    └── _feature.md
    └── login/
        └── _story.md
        └── successful-login.md
        └── failed-login.md
    └── reset-password/
        └── _story.md
        └── email-sent.md
        └── invalid-email.md

Feature Unit

A feature unit describes a single feature and its scenarios.

## Feature: Authentication

### Scenarios

#### Scenario: Valid credentials
priority: critical

- Given …
- When …
- Then …

#### Scenario: Invalid password
priority: high

- Given …
- When …
- Then …

---
confidence: low
source: prd.md
assumptions:
  - email/password login
open_questions:
  - password complexity rules?
tags:
  - auth
  - security
owner: dev-team
component: identity
---

Including optional metadata

Include YAML frontmatter metadata for organization and tracking. This enriches your specs with context and traceability. Metadata is optional.

Feature metadata file (_feature.md)

---
feature_id: authentication
component: identity
owner: auth-team
priority: high
tags: [auth, security]
---

# Feature: User Authentication

Describe the purpose and scope of the feature.

Story metadata file (_story.md)

---
story_id: login
feature_id: authentication
priority: high
tags: [auth, login]
---

# Story: User Login

Describe a specific user journey within the feature.

Scenario unit (<scenario>.md)

This scenario would get converted into a test skeleton:

---
scenario_id: successful-login
story_id: login
feature_id: authentication
priority: critical
execution_time: fast
tags: [smoke, login]
---

# Scenario: Successful login

## Steps
- **Given** a user has valid credentials
- **When** the user submits the login form
- **Then** the user is authenticated

Test data tables

Use ## Test Data to create parameterized scenarios:

## Test Data
| username | password | expected |
|----------|----------|----------|
| alice    | secret   | success  |
| bob      | wrong    | error    |

## Steps
- **Given** a user with username `{username}` and password `{password}`
- **When** they attempt to log in
- **Then** the result is `{expected}`

Valid values

• Step keywords (optional): Given, When, Then, And, But
• Priority: critical, high, medium, low
• Execution time: fast, medium, slow

ID rules

Feature, story, and scenario IDs must be unique and match ^[a-z0-9-]+$.