Chapter 07 | The Worldview of OpenSpec

Chapter 7: The OpenSpec Worldview

Learning Objectives

Understand why OpenSpec is not a "regular documentation system" — but rather a version control system for specifications.

Three Directories = Three Identities

flowchart TB
    subgraph Now["Current State"]
        Specs["specs/
What the system currently promises
(Single Source of Truth)"]
    end

    subgraph WIP["In Progress"]
        Changes["changes/active/
Changes under review/implementation
(delta format)"]
    end

    subgraph Past["History"]
        Archive["changes/archive/
Completed changes
(Full snapshot)"]
    end

    Changes -->|/opsx:archive| Archive
    Archive -.->|delta merge| Specs

    style Now fill:#c8e6c9
    style WIP fill:#fff9c4
    style Past fill:#e1bee7

Git Analogy (Quickest Way to Understand)

→ specs are "code", changes are "PRs", and archive is "git log".

A Complete Lifecycle

sequenceDiagram
    participant U as User
    participant E as opsx:explore
    participant P as opsx:propose
    participant Files as File System
    participant A as opsx:apply
    participant Ar as opsx:archive

    U->>E: "I want to add OAuth"
    E->>U: Clarify issues, discuss thoroughly
    U->>P: Confirmed, make this change
    P->>Files: changes/add-oauth/{proposal,design,specs,tasks}
    U->>A: Implement according to tasks.md
    A->>Files: src/ + tasks.md checked off
    U->>Ar: Done
    Ar->>Files: Move change to archive/
    Ar->>Files: Merge delta into specs/auth.md

Why This Design Prevents "Requirement Drift"

Problems with Conventional Approaches:

You write PRDs in Notion today       ── 6 months later, no one remembers how many times it was changed
Tickets in Jira                     ── 2 years later, Jira expires, all links are broken
Code commits in Git                 ── Know "what was changed", but not "why"

→ Three systems drift, tear apart, and don't align

OpenSpec ties these together:

changes/archive/2026-04-add-oauth/
├── proposal.md      ← Replaces Notion PRD
├── design.md        ← Replaces design documents
├── tasks.md         ← Replaces Jira ticket list
└── specs/auth.md    ← Which specs were changed this time

With Git commit associations, code can also be traced back from the change. One folder = one complete "why + how + what was changed".

Delta is Key

changes/<name>/specs/auth.md is not the full spec, it's a change. Example:

## Chapter 7: ADDED Requirements

### Requirement: User Supports OAuth Login
The system SHALL support Google / GitHub OAuth flows.

#### Scenario: Google Authorization Success
- WHEN the user clicks "Sign in with Google" on the login page
- THEN redirect to the Google OAuth page, and return to /callback after authorization

When archiving, OpenSpec merges this section into specs/auth.md — the latter being the complete spec.

Chapter Summary in One Sentence

specs are the "system's current image", archive is the "event stream", and changes are "the event stream entry currently being edited".

→ This is exactly like a database schema migration system. The difference is: migrations manage data, OpenSpec manages requirements.

What You Can Do Now

• Explain the roles of specs/, changes/, and archive/
• Explain OpenSpec to colleagues using the Git analogy
• Understand why deltas are stored separately instead of writing the full spec

In the next chapter, we'll get hands-on — exploring our first idea using explore mode.