TL;DR: OpenSpec takes everything you already know about a feature, the requirements, the designs, the tickets, the system it’s going into, and turns it into one plain English document that everyone can review before a line of code is written.

What OpenSpec is

At its core, OpenSpec is a tool that produces a spec both humans and AI agents can read. Not a design document, not a ticket, and not a prompt. A single set of human readable files that live in the repository next to the code, and answer the questions that are key to success:

  • Why are we doing this?
  • What is in and out of scope?
  • What parts of the system will change?
  • What decisions are still open?
  • What does done look like?

The useful part is the order of events. We write the spec, talk about it, and change it while changing our minds is cheap. Then an engineer or an agent builds from the version we agreed. That sounds obvious, but it is surprisingly easy to skip when somebody can produce a convincing looking pull request in ten minutes.

What it isn’t

It is not a way to get AI to write code nobody needs to review. It is closer to the opposite: a way to move the important review earlier, to a document everyone can read.

Product requirements can still live where product requirements live. Designs can still be in Figma. Jira can still track ownership and status. I would not copy all of that into OpenSpec. The spec should explain the change and record the decisions; the other tools should keep doing the jobs they are good at.

What it actually produces

Let’s say we are adding plan selection to a signup flow. The change might look like this:

openspec/
  changes/
    add-plan-selection/
      proposal.md      what and why, and what it touches
      design.md        decisions, trade-offs, and open questions
      tasks.md         the work, in order
      specs/
        plan-selection-flow/spec.md
        plan-pricing/spec.md
  archive/             shipped changes, kept

You might have expected a lot more, but actually, OpenSpec generates a minimal set of files, most of which you can read through easily. There will be technical details in there, but the high level overview is there and understandable.

proposal.md starts with the reason for the work:

Why

Today the signup flow can only sell a single plan. Anything else is sold manually through a form, which creates hand cranked work for the onboarding team and blocks the relaunch. We want customers to choose a plan at the start of signup, and for that choice to carry through so billing and provisioning happen automatically.

The files under specs/ contain the requirements and the scenarios that demonstrate them:

### Requirement: Plan selection is the first step of signup

The signup flow SHALL begin with an explicit plan selection step
showing the plans the customer is eligible for.

#### Scenario: Selection is mandatory

- **WHEN** a customer tries to advance without choosing a plan
- **THEN** the flow SHALL NOT advance
- **AND** the customer SHALL be prompted to choose

#### Scenario: Only one plan available

- **WHEN** a customer is eligible for exactly one plan
- **THEN** that plan SHALL still be presented for explicit selection

That is not particularly technical. A product manager can read it and ask whether someone with one eligible plan should need to click at all. That is a real product decision, and it is much better to have it there than discover it halfway through a pull request.

tasks.md breaks down the implementation, but it can also call out the things we still do not know:

## Phase 0 - Unblock (no code merges until complete)

- [ ] 0.1 **GAP** Agree the setup fee amount per market. That one
      must exist is settled, contract generation fails without it.
      Only the amount is open.
- [ ] 0.2 **GAP** Confirm launch markets. Tickets say "each active
      market" without defining the set.

Once the agent is running and writing the code, it will track its work by ticking off each of the tasks in each phase as it completes them.

Making a spec

An engineer sets OpenSpec up once in the repository. After that, the inputs are the things we already have: a requirements document, designs, tickets, and the codebase where the work will land.

There are two useful starting points:

/opsx:explore    still working out the problem
/opsx:propose    ready for a first draft

explore is useful when the answer is not clear yet. It can read the code and help weigh options without writing a change. propose produces the first set of files.

The commands are not the important bit. The input is. “Add plan selection” will get you a generic document. Giving it the requirements, designs, relevant tickets, and a little context about the system gets you something worth reviewing.

Then read it together. A process my team has done, once the spec has been generated is reading through every line, discussing and making updates. In some cases, the spec will have open ended questions, or make assumptions that need to be validated.

The difficult part is not writing code any more

In March 2025, YC’s Jared Friedman said that around a quarter of startups in that batch had codebases that were about 95% AI generated.

The more interesting question is what happens after the code arrives. In Stack Overflow’s 2025 survey, 66% of respondents called out AI solutions that are “almost right, but not quite” as a frustration. 45% said debugging AI generated code takes more time. The problem is not that models cannot write code. “Almost right” is a high bar, and it is hard to spot in a large diff.

Here is how OpenSpec frames it: “Generating code is now cheap. Correctness is still expensive.”

Plan review, not just code review

AI will build the wrong thing quickly, confidently, and often in a way that looks complete. The plan is where we get to catch that before it becomes a diff somebody has to unpick.

Reading Markdown is also a much lower bar than reading a large pull request. A designer or product manager does not need to understand the data model to say that an existing customer should not see an upgrade prompt, or that an empty state is missing. They just need the document to make that assumption explicit.

”Can I do this if I’m not technical?”

I think this is slightly the wrong question.

You do not have to write the engineering detail. You do need to disagree with the document when it is wrong.

The product work is already there: why we are doing this, what changes, what does not, and what happens at the edges. The spec can draft the mapping onto services, contracts, and data. Then somebody with product context reads a sentence such as existing customers keep the old pricing and never see the upgrade prompt and says “yes” or “no, actually”.

That is the useful contribution. It does not require technical knowledge. It requires knowing the product well enough to spot an assumption that is not true.

What stays in the ticket

Jira tracks work; the spec explains it.

Keep the ticket for ownership, status, links to the epic, and whatever acceptance criteria help the team track delivery. Keep the reasoning, scope, edge cases, and expected behaviour in the spec. Linking the two is enough; copying them into each other usually makes both worse.