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, and nothing moves on without a 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 pretend project. Nothing is installed and nothing leaves your browser. Run the suggested commands, edit the docs, and watch the decision gate stop you.

Try

Files

—edits save in this tab

~/your-project

fill and approve are sandbox shortcuts that write example text. In a real project, your team writes the docs, and a real person approves.

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`	Generated for development: the chosen direction, its Figma links and the criteria	Engineering

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 800 lines of plain Node.js. Your security team can read all of it.

No network, no telemetry

It only reads and writes Markdown files in your repository.

No new licenses

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

07Questions

Do designers need a terminal?

No. Every doc is plain Markdown. Designers and product managers edit them on github.com, or write in Figma or a doc and someone pastes it in. Whoever runs the tool, usually a developer, needs a few short commands.

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 won’t pass without a name. 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.