Directory Structure

A standard OpenSpec project follows this layout:

openspec/
├── AGENTS.md               # Instructions for AI assistants (generated)
├── project.md              # Project-specific context (tech stack, conventions)
├── specs/                  # THE TRUTH: Current deployed capabilities
│   └── [capability]/       # E.g., user-auth, payment-processing
│       ├── spec.md         # Requirements and scenarios
│       └── design.md       # (Optional) Technical patterns
├── changes/                # PROPOSALS: Active work in progress
│   ├── [change-name]/      # E.g., add-google-login
│   │   ├── proposal.md     # Why, What, and Impact
│   │   ├── tasks.md        # Implementation checklist
│   │   ├── design.md       # (Optional) Architecture decisions
│   │   └── specs/          # Delta specs (changes to the truth)
│   │       └── [capability]/
│   │           └── spec.md # Contains ## ADDED/MODIFIED/REMOVED Requirements
│   └── archive/            # History of completed changes

specs/ vs changes/

  • specs/: Read-only reference for the AI. Describes how the system works right now. Never edit these directly during feature work.
  • changes/: The workspace. Describe how the system will work. When a change is archived, OpenSpec merges these files into specs/.