In OpenSpec, the standard spec format is a structured Markdown document that defines exactly what a system should do through requirements and how that behavior is verified through scenarios.

1. Core Specification Structure (spec.md)

The “Source of Truth” file (located in openspec/specs/<domain>/spec.md) follows a specific hierarchy:

• Header: The capability or feature name (e.g., # Auth Specification).
• Purpose: A brief description of what this capability provides to the system.
• Requirements: Formal statements of behavior using EARS-style (Easy Approach to Requirements Syntax) phrasing.
  • Uses keywords like SHALL, MUST, or SHOULD (e.g., “The system SHALL issue a JWT token upon login”).
• Scenarios: Concrete examples of a requirement in practice, written as a behavioral flow.

2. The Scenario Format (GIVEN/WHEN/THEN)

Scenarios are the most critical part for AI assistants because they provide unambiguous “tests” for the code. They use the standard BDD (Behavior-Driven Development) structure:

• GIVEN: The initial context or state (e.g., “Given a user is on the login page”).
• WHEN: The action or event that occurs (e.g., “When they submit valid credentials”).
• THEN: The expected outcome or result (e.g., “Then they are redirected to the dashboard”).

3. Change Proposals & Delta Specs

When you start a new feature with /opsx:propose, OpenSpec creates “Delta Specs” inside the changes/ folder. These use specific headers to indicate how the main spec will be modified once the work is archived:

• ## ADDED Requirements: New features or capabilities being introduced.
• ## MODIFIED Requirements: Updates to existing system behavior.
• ## REMOVED Requirements: Features being deleted from the system. [4, 8, 9]

4. Supporting Artifacts

While spec.md defines behavior, two other files in a change proposal provide the implementation context:

• proposal.md: Explains the Why (intent), What (scope), and high-level Approach.
• design.md: Details the How—technical architecture, database schemas, and specific library choices.
• tasks.md: An atomic, numbered Checklist that the AI agent follows step-by-step during implementation.

Here is a sample spec:

# auth-login Specification

## Purpose
Allow users to authenticate using email/password or third-party OAuth providers.

## Requirements

### Requirement: Email/password login
The system SHALL allow users to log in with a registered email and password.

#### Scenario: Successful login
- **Given** a registered user with email `user@example.com`
- **When** they submit valid credentials
- **Then** the system returns an access token and refresh token
- **And** the user is redirected to their dashboard

#### Scenario: Invalid credentials
- **Given** a registered user
- **When** they submit an incorrect password
- **Then** the system returns a 401 error
- **And** displays "Invalid email or password"
- **And** does NOT reveal whether the email exists

### Requirement: OAuth login
The system SHALL support Google and GitHub OAuth login.

#### Scenario: First-time OAuth login
- **Given** a user who has never logged in before
- **When** they complete the OAuth flow with Google
- **Then** the system creates a new account linked to their Google identity
- **And** returns access and refresh tokens

### Requirement: Rate limiting
The system SHALL rate-limit login attempts to 5 per minute per IP address.