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
MIT licensed. Zero dependencies. No telemetry.
## Problem
About 40% of mobile users who reach checkout don’t complete it.
## Desired outcome
More completed mobile orders, fewer payment tickets.
## Appetite
Three weeks of a small team.
## No-gos
We don’t switch payment providers.
01Installation
npm i -D github:eranlipi/discovery-to-specnpx d2s initnpx github:eranlipi/discovery-to-spec initnode path/to/discovery-to-spec/bin/d2s.js initRequires 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.
Each “## heading” fills the field with the same name. Fields without a matching heading stay as they are.
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.
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.
04An AI assistant for the thinking
Development got fast. The thinking before it is now the slow part. The d2s assistant works in the chat you already use, Claude, ChatGPT or Gemini, and gets you to “what should we build” faster, without skipping the thinking.
Frames the problem
Asks the right questions, and pushes back when a request arrives as a solution.
Makes sense of research
Turns raw interview notes, tickets and data into insights with evidence and a confidence level. Quotes stay word for word, and names come out.
Lays out real directions
Two to four genuinely different directions, then the decision and the spec.
It never invents research and never approves for anyone. Each stage ends with a document that has your team’s headings, and Paste from AI in d2s fills the form from it.
- Download the skill: d2s-discovery-skill-v0.5.0.zip. Keep it zipped.
- In Claude, open Customize → Skills, choose + → Create skill → Upload a skill, pick the zip and turn the skill on.
- Start a chat and talk as usual. Claude uses the skill when you frame a problem, paste research or explore directions.
Skills need code execution, which settings call “Create and edit files”, and a paid plan. Without skills, create a Project and paste the instructions into its instructions.
- Copy the instructions with the button below.
- In ChatGPT, click New project in the sidebar and name it “d2s discovery”.
- Open the project’s ••• menu, choose Project settings, paste the instructions and save. Check that all of the text was saved.
- Start every chat about the feature inside the project, and talk as usual.
Projects work on every ChatGPT plan, Free included. Custom GPTs can no longer be created on personal accounts. On Business and Enterprise, you can create a Skill with the same instructions instead.
- In Gemini, open Skills from the sidebar, then choose Create → Create manually.
- Name it
d2s-discovery, and paste the description and the instructions with the buttons below. Click Create. - In any chat, type
/and choose the skill, then talk as usual.
Gemini skills are free on personal Google accounts. Gems are being retired, so use a skill.
These apps rename their menus from time to time. If a name here doesn’t match, look for it in the app’s settings or customize menu.
Try it in two minutes
Copy our sample interview notes, paste them into the assistant and ask “What comes out of this?”. Then copy the document it writes. In the sandbox above, reach the research stage (Use example text, then Next stage) and choose Paste from AI.
Read the instructions
05Six 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.
06Compatibility
- Figma
- GitHub
- Claude
- ChatGPT
- Gemini
- Claude Code
- Cursor
- Codex
- GitHub Copilot
- OpenSpec
Designers and product managers use the d2s assistant in Claude, ChatGPT or Gemini. 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.
07Easy 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.
08Questions
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.