Specification Structure

Directory layout

project/
├── openspec/
│   ├── project.md              # Project context
│   ├── AGENTS.md               # Instructions for AI agents
│   ├── specs/                  # Current truth (IS)
│   │   ├── warehouse/
│   │   │   └── spec.md
│   │   ├── invoicing/
│   │   │   └── spec.md
│   │   └── crm/
│   │       └── spec.md
│   └── changes/                # Change proposals (SHOULD BE)
│       ├── add-barcode-scan/
│       │   ├── proposal.md
│       │   ├── tasks.md
│       │   ├── design.md
│       │   └── specs/
│       │       └── warehouse/
│       │           └── spec.md  # Delta spec
│       └── archive/            # Archived changes
│           └── 2025-01-15-add-mobile-app/

---

Two specification types

1. Specs (Current truth)

The openspec/specs/ folder contains the current state of the system. What is written here = what is implemented.

# openspec/specs/warehouse/spec.md

# Warehouse Specification

## Purpose
Manage stock, receipts and issues, inventories.

## Requirements

### Requirement: Automatic numbering of receipts
The system MUST automatically generate a unique receipt number.

#### Scenario: Create a new receipt
- **WHEN** the user creates a new receipt
- **THEN** the system generates a number in the format PR-YYYY-NNNN
- **AND** the number is read-only

### Requirement: Track stock cards
The system MUST allow tracking stock cards with movement history.

#### Scenario: View card history
- **GIVEN** a stock card exists for product "ABC-001"
- **WHEN** the user opens the card detail
- **THEN** they see all movements (receipt, issue, inventory)
- **AND** movements are sorted from newest

---

2. Changes (Delta specifications)

The openspec/changes/ folder contains proposed changes in delta form:

# openspec/changes/add-barcode-scan/specs/warehouse/spec.md

## ADDED Requirements

### Requirement: Barcode scanning during receipt
The system MUST allow barcode scanning for quick product identification during receiving.

#### Scenario: Successful EAN scan
- **WHEN** the user scans barcode "8590000001234"
- **THEN** the system automatically fills the product by EAN
- **AND** fills the product on the receipt line
- **AND** moves the cursor to the quantity field

#### Scenario: Unknown barcode
- **WHEN** the user scans a barcode that is not in the system
- **THEN** the system shows "Product not found"
- **AND** offers "Create new product"
- **AND** pre-fills the EAN code for the new product

#### Scenario: Offline scanning
- **GIVEN** the device is offline
- **WHEN** the user scans a barcode
- **THEN** the system saves the scan to a local queue
- **AND** shows the indicator "Waiting for sync"
- **WHEN** the device reconnects
- **THEN** the system automatically syncs the queue

### Requirement: Scan audit log
The system MUST log all scans for audit purposes.

#### Scenario: Log successful scan
- **WHEN** the user successfully scans a product
- **THEN** the system records: timestamp, userId, ean, productId, receiptId

## MODIFIED Requirements

### Requirement: Create receipt item
The system MUST allow adding a receipt item **manually or via scanning**.

#### Scenario: Manual item addition
- **WHEN** the user clicks "Add item"
- **THEN** a form opens for product selection
- **AND** the user can search by name or code

#### Scenario: Add item by scanning
- **WHEN** the user clicks "Scan"
- **THEN** the camera opens
- **AND** after scanning the item is added automatically

## REMOVED Requirements

(No requirements are removed in this change)

## RENAMED Requirements

(No requirements are renamed in this change)

---

Delta operations

Operation	Description	Content
ADDED	New requirements	Full text with scenarios
MODIFIED	Changed requirements	Full new text
REMOVED	Removed requirements	Name only
RENAMED	Renamed requirements	FROM and TO

---

➡️ Continue to spec.yaml format.