The Proposal

Before any code gets written, you need to describe what you're building. Not to the AI — to yourself. The proposal is that description made permanent.

Note: Before writing a proposal, you could run /opsx:explore to think through the idea first. Exploration is where you ask questions, visualize tradeoffs, and crystallize what you're actually trying to build. Then when you're ready, the proposal captures what emerged. It's optional — some people go straight to proposal. Either way works.

Run this in your project directory:

you: /opsx:propose "a toast notification system — success, error, warning, and info variants, auto-dismiss after 3 seconds, click to close, stacks when multiple appear"

OpenSpec reads your config.yaml, reads what you typed, and generates a proposal.md inside a new change folder:

openspec/
└── changes/
    └── toast-notifications/
        ├── .openspec.yaml
        └── proposal.md

Open proposal.md and read through it. You'll see four sections:

Why — one paragraph on why this change exists. Grounds everything that follows.

What Changes — a bulleted list of the concrete outputs: what files get created, what behaviors get added. No implementation detail yet — just scope.

Capabilities — the named behaviors this change introduces. Yours will have two: toast-appearance (what toasts look like) and toast-lifecycle (how they show, dismiss, and stack). These names matter — in lesson 04 each capability becomes its own spec file.

Impact — what this change touches. In this case: one output file, no dependencies, no existing code affected.

This is the first place the a-ha happens.

You typed one sentence. The tool produced a scoped, structured description of the work. More importantly — it made decisions you didn't consciously make. Single HTML file. No dependencies. No build step. You implied that, but you didn't write it down. Now it's written down, and the AI will read this file before it writes a line.

If anything is wrong, edit it now. The spec comes next.