Defining Your First Feature

Specs are written in Markdown. They describe what a feature does and why, without implementation details.

1. Create a PRD

Create a prd.md file in your repository root:

# My Project

## Feature: User Authentication

Users need to log in securely.

### Scenario: Successful login
- Given a user has valid credentials
- When the user submits the login form
- Then the user is authenticated and redirected

### Scenario: Invalid credentials
- Given a user has invalid credentials
- When the user submits the login form
- Then an error message is displayed

Including metadata

You can add YAML frontmatter metadata to features, stories, and scenarios for organization and tracking. See the Spec Syntax (.md) guide for details.

2. Generate feature specs

Preview what SpecLeft would create:

specleft plan --dry-run

When it looks right, run it for real:

specleft plan

SpecLeft creates one file per feature under .specleft/specs/:

This is also called a “feature unit”

.specleft/specs/
├── feature-user-authentication.md

3. Inspect a feature unit

Open .specleft/specs/feature-user-authentication.md:

# Feature: User Authentication

## Scenarios

### Scenario: Successful login
- Given a user has valid credentials
- When the user submits the login form
- Then the user is authenticated and redirected

### Scenario: Invalid credentials
- Given a user has invalid credentials
- When the user submits the login form
- Then an error message is displayed

4. Generate skeleton tests

Preview generation without writing files:

specleft test skeleton --dry-run

Generate the tests:

specleft test skeleton

Example skeleton output:

from specleft import specleft

@specleft(
    feature_id="feature-user-authentication",
    scenario_id="successful-login",
    skip=True,
)
def test_successful_login():
    with specleft.step("Given a user has valid credentials"):
        pass # TODO: implement test step

    with specleft.step("When the user submits the login form"):
        pass # TODO: implement test step

    with specleft.step("Then the user is authenticated and redirected"):
        pass # TODO: implement test step

5. Run tests safely

Skeleton tests are skipped until you implement them:

pytest

SKIPPED: Scenario 'successful-login' not yet implemented

6. Track progress

Check what is implemented vs. skipped:

specleft status

Find the next scenario to implement:

specleft next