Skip to content

Rework README first screen for discoverability - #32

Draft
Cyning12 wants to merge 1 commit into
mainfrom
cursor/readme-first-screen-rework-705d
Draft

Cyning12 wants to merge 1 commit into
mainfrom
cursor/readme-first-screen-rework-705d

Conversation

@Cyning12

Copy link
Copy Markdown
Owner

Summary

Rewrote the top section of README.md (and README.zh-CN.md) to make SpecWave's value proposition immediately clear to developers landing from external discovery sources (Hacker News, Reddit, awesome lists, HelloGitHub).

What Changed

Top Section (First Screen)

  • Added: Clear one-line value prop: "Write your AI coding rules once. SpecWave installs them natively into Cursor, Claude Code, Copilot, and 10 more tools."
  • Added: npm version and license badges
  • Added: Problem/solution comparison table showing the manual pain point vs. SpecWave's single-command approach
  • Added: Compact 13-host support table with what files are generated for each tool
  • Moved: Quick start section higher (after problem/solution)
  • Added: Plain-language "Why fail-closed gates?" section explaining exit codes without jargon
  • Added: TODO placeholder for terminal demo (recording tools not available in build environment; marked clearly rather than faking)
  • Added: Gentle star request at end of top section: "If this saves you time, a ⭐ helps others find it."

Structure

  • Kept all existing deep documentation (core concepts, detailed CLI commands, advanced features)
  • Reorganized flow: value prop → problem → solution → quick start → supported hosts → gates → features → installation → deep dive
  • Both English and Chinese READMEs updated with consistent structure

Verification

All claims verified against actual code:

  • 13 hosts confirmed from assets/ide/host-adapt/examples/mvp-hosts.yaml
  • Generated file paths confirmed from host-adapt README
  • CLI commands verified against actual CLI implementation

TODO (Left for Future)

  • Terminal demo: Add real recording (GIF/SVG) when vhs or asciinema is available. Placeholder marked clearly in README with HTML comment. Should show: npx spec-wave host apply --tools cursor,claude --yes → native files generated → verify gate check flow.

Rationale

The current README opens with internal concepts ("adapt table", "P0 gates", "Harness", "ICVO") that newcomers don't understand. This causes:

  • Visitors bouncing without understanding what the tool does
  • Zero stars despite promotion post views (per user context)

The new structure:

  1. 10-second clarity: Plain language, immediate value, concrete before/after comparison
  2. Show don't tell: Table of 13 tools + what files are generated (not abstract "multi-host")
  3. Build trust: Badges, real examples, verified claims, no invented features
  4. Lower friction: Quick start before deep concepts

Testing

  • Both README.md and README.zh-CN.md updated
  • All links functional (internal doc links preserved)
  • All claims verified against source code
  • No breaking changes to existing deep documentation
  • Consistent structure between English and Chinese versions

Related

  • Addresses the discoverability problem mentioned in user context (promotion posts got views but zero stars)
  • Complements existing documentation rather than replacing it
  • Makes the GitHub landing page work harder for organic discovery
Open in Web Open in Cursor 

- Add clear one-line value prop at top
- Add npm/license badges
- Lead with problem/solution comparison table
- Add compact 13-host support table with generated files
- Move quick start higher
- Add plain-language fail-closed gates explanation
- Add TODO placeholder for terminal demo (no vhs/asciinema available)
- Keep existing deep documentation but reorganize for better flow
- Add gentle star request at end of top section
- Mirror structure in Chinese README for consistency

This makes the value prop immediately clear to developers landing
from Hacker News, Reddit, awesome lists, or HelloGitHub.

Co-authored-by: Cyning12 <Cyning12@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants