Skip to content
Back to search

vibe-prd

SkillWorks with CodexGitHub

Write the contract before the code, get the docs back from the code. spec → SPEC.md, prd → 左图右注 interactive PRD. Agent skill for Claude Code, Cursor, Codex and Windsurf.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gugusiyuan49--vibe-prd/badge.svg)](/listings/gugusiyuan49--vibe-prd)

HTML

<a href="/listings/gugusiyuan49--vibe-prd"><img src="/api/listings/gugusiyuan49--vibe-prd/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add gugusiyuan49/vibe-prd

That installs one skill folder (`SKILL.md` and two templates) into Claude Code, Cursor, Codex, Windsurf and the other agents that read [Agent Skills](https://agentskills.io). Then:

| Agent | Plan a feature → `SPEC.md` | Document a page → `PRD_Viewer.html` | | --- | --- | --- | | Claude Code, Cursor | `/vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `/vibe-prd prd ./prototype.html` | | Codex | `$vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `$vibe-prd prd ./prototype.html` | | Windsurf | `@vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `@vibe-prd prd ./prototype.html` | | Any agent | "Spec this before coding: an ERP reconciliation dashboard" | "Write a 左图右注 PRD for ./prototype.html" |

No `npx`? Copy `skills/vibe-prd/` into `~/.claude/skills/` (or `~/.cursor/skills/`, `~/.codex/skills/`, `~/.codeium/windsurf/skills/`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 158 lines
  1. <div align="center">
  2. # vibe-prd · 左图右注
  3. **Write the contract before the code. Get the docs back from the code.**
  4. One agent skill with two engines. `spec` turns a one-line idea into a `SPEC.md` contract before any code exists.
  5. `prd` turns an HTML or React prototype you already have into a clickable, single-file **left-UI / right-annotation** PRD.
  6. [![License: MIT](https://img.shields.io/badge/license-MIT-2563EB?style=flat-square)](LICENSE)
  7. [![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-0F172A?style=flat-square)](#30-second-quick-start)
  8. [![Cursor](https://img.shields.io/badge/Cursor-compatible-0F172A?style=flat-square)](#30-second-quick-start)
  9. [![Codex](https://img.shields.io/badge/Codex-compatible-0F172A?style=flat-square)](#30-second-quick-start)
  10. [![Windsurf](https://img.shields.io/badge/Windsurf-compatible-0F172A?style=flat-square)](#30-second-quick-start)
  11. [![Live demo](https://img.shields.io/badge/live%20demo-open%20it-E11D48?style=flat-square)](https://gugusiyuan49.github.io/vibe-prd/examples/b2b-inventory-workbench/)
  12. English · [简体中文](README_zh.md)
  13. </div>
  14. Vibe coding gets you a working page in 10 minutes. Then you spend two hours in a fix-one-break-two loop, and when your team lead asks for the spec, there isn't one.
  15. **vibe-prd fixes both ends.** Before you build, it makes your agent write the state machine, the edge cases and the API contract. After you build, it reads the page back and hands you a PRD your PM, QA and backend can click through.
  16. ![Hover a red badge on the prototype and its annotation card scrolls into view on the right; hover a card and the prototype jumps to that region](assets/demo-reverse-prd.gif)
  17. **[Open the live demo](https://gugusiyuan49.github.io/vibe-prd/examples/b2b-inventory-workbench/)**: a vibe-coded B2B inventory and Kingdee ERP reconciliation workbench, reverse-engineered into a PRD. Hover the red badges.
  18. ![/vibe-prd spec writes SPEC.md with a role matrix, a state machine, a 5-category edge-case matrix, the schema and a 5-step checklist, and no business code](assets/demo-forward-spec.gif)
  19. ## How it works
  20. ```text
  21. ┌─────────────────────────── vibe-prd ───────────────────────────┐
  22. │ │
  23. one-line ────▶│ spec · FORWARD │──▶ SPEC.md
  24. idea │ roles → state machine → 5-category edge cases → schema & API │ contract first,
  25. │ → 5-step checklist. No business code until you say "go". │ code second
  26. │ │
  27. ├────────────────────────────────────────────────────────────────┤
  28. │ │
  29. prototype ───▶│ prd · REVERSE │──▶ PRD_Viewer.html
  30. .html / .tsx │ scan DOM → number regions → extract rules, fields, formulas │ live UI on the left,
  31. │ → find the missing guardrails → Mermaid → one HTML file │ annotations on the right
  32. │ │
  33. └────────────────────────────────────────────────────────────────┘
  34. ```
  35. ## 30-second quick start
  36. ```bash
  37. npx skills add gugusiyuan49/vibe-prd
  38. ```
  39. That installs one skill folder (`SKILL.md` and two templates) into Claude Code, Cursor, Codex, Windsurf and the other agents that read [Agent Skills](https://agentskills.io). Then:
  40. | Agent | Plan a feature → `SPEC.md` | Document a page → `PRD_Viewer.html` |
  41. | --- | --- | --- |
  42. | Claude Code, Cursor | `/vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `/vibe-prd prd ./prototype.html` |
  43. | Codex | `$vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `$vibe-prd prd ./prototype.html` |
  44. | Windsurf | `@vibe-prd spec "Build an ERP inventory reconciliation dashboard"` | `@vibe-prd prd ./prototype.html` |
  45. | Any agent | "Spec this before coding: an ERP reconciliation dashboard" | "Write a 左图右注 PRD for ./prototype.html" |
  46. No `npx`? Copy `skills/vibe-prd/` into `~/.claude/skills/` (or `~/.cursor/skills/`, `~/.codex/skills/`, `~/.codeium/windsurf/skills/`).
  47. ## What you get
  48. ### `spec` → `SPEC.md`
  49. Five modules, always in this order ([full example](examples/b2b-inventory-workbench/SPEC.md)):
  50. 1. **Overview and roles**: goal, success metric, non-goals, and a role × capability matrix (✅ / ⛔ / 🔶 needs approval).
  51. 2. **Core state machine**: a Mermaid `stateDiagram-v2` with every cancel, timeout and rollback path, plus a transition table.
  52. 3. **5-category edge-case matrix**: empty state, boundary values, network and timeouts, concurrency, permissions. At least two cases each, with the UI copy and the backend fallback.
  53. 4. **Data schema and API contract**: SQL DDL, TypeScript types, endpoints with idempotency and permissions, error codes.
  54. 5. **Atomic checklist**: at most five steps, each with an acceptance check you can run.
  55. The agent writes no business code until you reply `go`, then builds one step at a time.
  56. ### `prd` → `PRD_Viewer.html`
  57. One HTML file. No build step, no server, no framework.
  58. - **Left:** your real prototype, still clickable. A numbered red badge sits on each business region. Switch between desktop, tablet (768 px) and mobile (375 px).
  59. - **Right, three tabs:** UI annotations (interaction rules, field dictionary, formulas, AI guardrail warnings), State and architecture (Mermaid state, flow and ER diagrams), Edge cases and tracking events.
  60. - **Two-way sync:** hover a badge and its card scrolls into view and glows blue. Hover a card and the prototype scrolls to that region, outlines it in red and flashes the badge.
  61. - **Built for review:** drag to resize, hide the badges, light or dark theme, and export to PDF (A4 landscape, every annotation expanded).
  62. - **Works anywhere:** double-click to open. Offline, diagrams fall back to their Mermaid source. On a phone, you switch between the prototype and the PRD.
  63. The guardrail warnings are the part reviewers remember. From the demo:
  64. > **High** · `settle()` overwrites the Kingdee book quantity with no confirmation, no reason code and no approval threshold. One misclick changes the books.
  65. > **Fix:** confirm the quantity and amount, require a reason code, route amounts over ¥5,000 to a manager, and write back through an adjustment document.
  66. ## Why vibe-prd?
  67. | | Raw vibe coding | With vibe-prd |
  68. | --- | --- | --- |
  69. | Starting point | "build me a dashboard" and the code starts | `spec`: a contract you can review in two minutes |
  70. | States | implied, scattered across click handlers | one state machine, every exit path named |
  71. | Edge cases | found by your users | 5 categories, written down before the code |
  72. | Data and API | whatever the first prompt produced | DDL, types, idempotency keys, error codes |
  73. | "Done" means | it looks fine | five acceptance checks you can run |
  74. | Handover | "read the code" | one HTML file: click the UI, read the rules |
  75. | Hidden gaps | invisible until production | guardrail warnings that name the function |
  76. ## The demo
  77. [`examples/b2b-inventory-workbench`](examples/b2b-inventory-workbench) holds all three stages of one feature:
  78. | File | What it is |
  79. | --- | --- |
  80. | [`raw-prototype.html`](examples/b2b-inventory-workbench/raw-prototype.html) | The page as vibe coding left it: filters with natural-language search, KPI cards, a reconciliation table, a transfer drawer, ERP sync. It works, and it skips a few guardrails on purpose. |
  81. | [`SPEC.md`](examples/b2b-inventory-workbench/SPEC.md) | Forward mode: the contract you would have written first. |
  82. | [`index.html`](examples/b2b-inventory-workbench/index.html) | Reverse mode: the prototype on the left, a full PRD on the right. |
  83. Run it locally by double-clicking `index.html`, or:
  84. ```bash
  85. git clone https://github.com/gugusiyuan49/vibe-prd.git
  86. open vibe-prd/examples/b2b-inventory-workbench/index.html # Windows: start, Linux: xdg-open
  87. ```
  88. ## Repository layout
  89. ```text
  90. vibe-prd/
  91. ├── skills/vibe-prd/
  92. │ ├── SKILL.md # the skill: routing, both modes, data contract, Mermaid rules
  93. │ └── templates/
  94. │ ├── spec-template.md # skeleton for SPEC.md
  95. │ └── left-right-prd.html # the single-file 左图右注 viewer
  96. ├── examples/b2b-inventory-workbench/
  97. │ ├── raw-prototype.html
  98. │ ├── SPEC.md
  99. │ └── index.html
  100. └── assets/ # README GIFs
  101. ```
  102. ## FAQ
  103. **Does my code leave my machine?** No. The skill runs inside your agent, and the viewer is a local file. The only network request is the Mermaid script (jsDelivr, then unpkg, then npmmirror).
  104. **Can it document React or Vue?** Yes. The agent captures the rendered DOM if the app is running, or ports the component to static HTML with the same class names (SKILL.md, step B1).
  105. **Which language does it write in?** Yours. Chinese in, Chinese out. Code identifiers stay in English.
  106. **How do I fix a wrong annotation?** Edit the `window.VIBE_PRD` object at the bottom of the generated HTML and reload. Badge numbers that don't match an annotation are flagged in the toolbar and in the console.
  107. ## Star history
  108. If vibe-prd saved you one bug loop, a ⭐ helps the next person find it.
  109. [![Star history chart](https://api.star-history.com/svg?repos=gugusiyuan49/vibe-prd&type=Date)](https://star-history.com/#gugusiyuan49/vibe-prd&Date)
  110. ## License
  111. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.