# OpenSpec Specification Format

## Overview

OpenSpec uses a structured markdown format for specifications. Specs live in two places:

- **`openspec/specs/`** - Current specifications (source of truth)
- **`openspec/changes/<change-name>/specs/`** - Proposed changes (deltas)

## Spec Structure

### Source Spec with Frontmatter (openspec/specs/auth/spec.md)

```markdown
---
id: auth/authentication
relatedTasks: [bd-a1b2, bd-b2c3]
relatedRules: [security-guidelines.md, module-development.md]
status: active
---

# Auth Specification

## Purpose
Authentication and session management.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned
- AND the JWT contains user ID and role

#### Scenario: Invalid credentials
- WHEN a user submits invalid credentials
- THEN an error is returned
- AND no JWT is issued
```

### Delta Spec (openspec/changes/add-2fa/specs/auth/spec.md)

```markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required
- AND the OTP is sent to the user's registered device

#### Scenario: Valid OTP
- WHEN a user submits a valid OTP
- THEN a JWT is issued
- AND the user is logged in

## MODIFIED Requirements

### Requirement: User Authentication
The system SHALL issue a JWT on successful login after two-factor verification.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN an OTP challenge is required (CHANGED)
- AND no JWT is issued until OTP verification (ADDED)

## REMOVED Requirements

(None for this change)
```

## YAML Frontmatter (Optional)

Specs can include YAML frontmatter for coordination with Beads tasks and `.augment/` rules:

```markdown
---
id: auth/authentication
relatedTasks: [bd-a1b2, bd-b2c3]
relatedRules: [security-guidelines.md, module-development.md]
status: active
dependencies: [database/schema]
---

# Spec Content
...
```

### Frontmatter Fields

- **id** (string): Unique spec identifier (e.g., "auth/authentication", "features/2fa")
- **relatedTasks** (array): Beads task IDs implementing this spec (e.g., ["bd-a1b2"])
- **relatedRules** (array): `.augment/` rule files that apply (e.g., ["security-guidelines.md"])
- **status** (string): One of: `draft`, `active`, `archived`, `deprecated`
- **dependencies** (array): Other spec IDs this spec depends on (optional)

### Benefits

- **Automatic Traceability**: Link specs to implementing tasks
- **Context Loading**: AI agents load relevant rules automatically
- **Coordination**: Integration with coordination manifest (`.augment/coordination.json`)
- **Dependency Tracking**: Track spec dependencies

**Note**: Frontmatter is optional and backward compatible. Specs without frontmatter continue to work normally.

---

## Delta Format Rules

### Section Headers

Use these exact headers in delta specs:

- `## ADDED Requirements` - New capabilities
- `## MODIFIED Requirements` - Changed behavior
- `## REMOVED Requirements` - Deprecated features

### Requirement Format

```markdown
### Requirement: <Name>
The system SHALL/MUST/SHOULD <requirement text>.

#### Scenario: <Scenario Name>
- WHEN <condition>
- THEN <expected behavior>
- AND <additional expectation>
```

### Keywords

- **SHALL** - Mandatory requirement
- **MUST** - Mandatory requirement (stronger)
- **SHOULD** - Recommended but not mandatory
- **MAY** - Optional

### Scenario Format

Use Given-When-Then style:

- **GIVEN** - Initial context (optional)
- **WHEN** - Action or condition
- **THEN** - Expected result
- **AND** - Additional conditions/results

## Example: Complete Change

### Proposal (openspec/changes/add-2fa/proposal.md)

```markdown
# Add Two-Factor Authentication

## Motivation
Users need stronger account security. Passwords alone are insufficient.

## Changes
- Add OTP generation and verification
- Modify login flow to require 2FA
- Add user settings for 2FA enrollment

## Impact
- Breaking change: All users must enroll in 2FA
- Database migration required
- Frontend login flow changes
```

### Tasks (openspec/changes/add-2fa/tasks.md)

```markdown
## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table
- [ ] 1.3 Add migration script

## 2. Backend Implementation
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint
- [ ] 2.4 Add 2FA enrollment endpoint

## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI
- [ ] 3.3 Add 2FA settings page
```

### Spec Delta (openspec/changes/add-2fa/specs/auth/spec.md)

See example above in "Delta Spec" section.

## Archiving Process

When archiving, the delta is applied to the source spec:

1. **ADDED** sections are appended to source spec
2. **MODIFIED** sections replace existing requirements
3. **REMOVED** sections are deleted from source spec

Result: `openspec/specs/auth/spec.md` now includes 2FA requirements.

## Best Practices

1. **One Spec Per Component**: Don't mix auth and profile specs
2. **Complete Scenarios**: Every requirement needs at least one scenario
3. **Clear Language**: Use SHALL/MUST for clarity
4. **Atomic Changes**: Each delta should be independently reviewable
5. **Update Existing**: Use MODIFIED for changes, not ADDED + REMOVED

## Validation

### With CLI

```bash
openspec validate <change-name>
```

Checks:
- Required headers present
- Requirement format correct
- Scenario format valid
- No orphaned scenarios

### Without CLI

Manual checklist:
- [ ] All deltas have ADDED/MODIFIED/REMOVED sections
- [ ] Every requirement has a scenario
- [ ] Keywords (SHALL/MUST) used correctly
- [ ] Scenarios follow WHEN/THEN format

