Design discovery, specified.

A lightweight, open-source workflow for design and product teams. Every feature moves through six short docs in your repo, passes a human decision gate, and ends as a spec that developers and coding agents can build from.

$ npx github:eranlipi/discovery-to-spec init

Try it in your browser View on GitHub

MIT licensed. Zero dependencies. No telemetry.

brief.md001-checkout

## Problem

About 40% of mobile users who reach checkout don’t complete it.

A problem, not a solution

## Desired outcome

More completed mobile orders, fewer payment tickets.

Something you can observe

## Appetite

Three weeks of a small team.

A decision, not an estimate

## No-gos

We don’t switch payment providers.

Clear limits

01Installation

$npm i -D github:eranlipi/discovery-to-spec

$npx d2s init

$npx github:eranlipi/discovery-to-spec init

$node path/to/discovery-to-spec/bin/d2s.js init

Requires Node.js 18 or later, for whoever runs the tool. Add --lang he for Hebrew templates.

02Workflow

/d2s-frameframe the problem: who it hurts, the outcome you want, the appetite and the no-gos
/d2s-researchturn interviews, tickets and data into insights with evidence
/d2s-optionslay out 2 to 4 genuinely different directions, each linked to Figma
/d2s-decidechoose one and record why. Only people approve: product, design and engineering, each by name.
/d2s-specevery screen, state and edge case, with acceptance criteria you can test
/d2s-handoffone generated doc for development. Rejected directions stay out.

Slash commands for Claude Code and Cursor. The same flow runs from the terminal with d2s new, d2s next and d2s status.

03Try it in your browser

This is the real d2s, running inside this page on a sample project. Designers fill in forms and press Next stage; developers drive the same files from a terminal. Nothing is installed and nothing leaves your browser.

This is the file in the repo. The form reads it and writes it back.

Every field is a ## heading in the template, and its guidance note is the helper text. Use example text fills empty fields with a sample. In a real project, your team writes them and real people approve.

Try

Files

—edits save in this tab

~/your-project

fill and approve are sandbox shortcuts that write example text. Try approve TBD to watch the gate refuse it. In a real project, your team writes the docs and real people approve.

04Six docs, one gate

Stage	Document	What it holds	Led by
1. Frame	`brief.md`	The problem, who it matters to, the desired outcome, appetite and no-gos	Product
2. Research	`insights.md`	Insights with evidence and a confidence level	Design and product
3. Options	`options.md`	2 to 4 directions with Figma links, pros and cons	Design
4. Decide	`decision.md`	The chosen direction, what was rejected and why, who approved	Product, design and engineering
5. Spec	`spec.md`	Screens, states, edge cases, acceptance criteria, accessibility	Design
6. Handoff	`handoff.md` `summary.md`	Generated: for development, the chosen direction, its Figma links and the criteria; for design and product, the whole exploration on one page	Engineering, design and product

Passing the gate adds a row to design/decisions.md, so nobody re-argues a decision six months later. If your repo uses OpenSpec, the handoff also drafts an OpenSpec change proposal.

05Compatibility

Figma
GitHub
Claude Code
Cursor
Codex
GitHub Copilot
OpenSpec

Claude Code and Cursor get a command per stage. Codex, Copilot and other agents read the shared rules from AGENTS.md. When the Figma MCP server is connected, agents read the linked frames.

06Easy to say yes to

MIT, no paid tier

Free to use, change and ship, for teams of any size.

Zero dependencies

About 1,200 lines of plain Node.js. Your security team can read all of it.

No telemetry

It reads and writes Markdown files in your repository. The only network call is an opt-in CI check that asks GitHub who approved.

No new licenses

Works with the GitHub and Figma you already have. AI agents are optional.

07Questions

Do designers need a terminal?

No. Try the Designer view above: every stage is a form with a Next stage button, and it writes the same Markdown files the CLI does. Today designers and product managers can also edit the files on github.com, or write in Figma or a doc and have someone paste it in. A Figma plugin is planned.

Does it replace OpenSpec?

No, it comes before it. OpenSpec starts once you know the change you want. discovery-to-spec helps you get there, and drafts an OpenSpec proposal when you do.

Do we need a paid Figma plan?

No. Figma links are plain links in the docs. Agents can read the frames through the Figma MCP server if you use it, but nothing depends on it.

Can an AI agent approve a decision?

No. The skills tell agents never to fill in who approved, and the gate wants one line per person with a name, role and date. It rejects placeholders like “TBD” and the names of AI tools, and it can check each approval against a GitHub review. Agents help you write; people decide.

Can we change the templates?

Yes. They live in design/templates in your repo. Every heading is required unless it’s marked optional, and the check follows your version.

Which languages are supported?

Templates come in English and Hebrew, right to left included. The CLI’s own messages are in English. More languages are welcome as contributions.