README to Landing Page

Transform a project's README.md into a concise, visual, developer-friendly landing page.

Core Principle: Show, Don't Tell

Developers skim — they don't read walls of text. The output README must:

• Prefer visuals over prose — use mermaid diagrams for architecture, workflows, data flow
• Be concise — every sentence must earn its place; cut ruthlessly
• Be scannable — badges, tables, code blocks, diagrams; minimize paragraphs
• Be direct — lead with what matters, skip the preamble
• No emoji — never use emoji in headings, body text, badges, or section labels

If something can be a diagram, make it a diagram. If something can be a table, make it a table. If something can be a one-liner, don't write three sentences.

Anti-Slop Rules

AI-generated READMEs have predictable tells. Slop signals "nobody reviewed this" and kills credibility. See references/anti-slop-rules.md for the full banned-phrase list and structural patterns to avoid.

Quick test: read each sentence and ask "does this give the reader information they didn't already have?" If not, cut it.

Repo Sync Before Edits (mandatory)

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty: git stash push -u -m "pre-sync", sync, then git stash pop. If origin is missing or conflicts occur, stop and ask the user.

Workflow

Step 1: Gather Context

Read project files to build a picture:

File	Purpose
README.md	Source material (required)
package.json / pyproject.toml / Cargo.toml / go.mod	Name, description, version
CHANGELOG.md	Momentum signals
LICENSE	Risk reversal ("MIT licensed")
docs/	Existing detailed docs to preserve

Also check: GitHub stars, forks, download stats, notable users. If purpose or audience is unclear, ask.

Step 2: Identify Audience & Value Prop

Determine these three things — write them down before proceeding:

1. Who — primary audience (developers, data scientists, ops teams, etc.)
2. Pain — what's frustrating about the status quo
3. Benefit — one sentence, becomes the H1 headline

Step 3: Select Framework

Project Type	Framework	Approach
CLI tools, libraries, infra	PAS	Problem -> Agitate -> Solution
Apps, platforms, end-user products	AIDA	Attention -> Interest -> Desire -> Action
Strong narrative / user request	StoryBrand	Hero -> Guide -> Plan -> CTA

Tell the user which you picked. Let them override.

Step 4: Back Up Original

cp README.md README.backup.md

Step 5: Rewrite README.md

Follow the section flow in references/section-templates.md (hero, how it works, features, quick start, examples, comparison, social proof, FAQ, CTA, collapsed technical details). Each template includes good vs. bad patterns and exact length budgets.

Key rules across all sections:

• H1 = value proposition (<=10 words), not the project name
• Hero <=5 lines (excluding badges)
• Each feature description <=15 words
• One copy-paste-runnable command per code block
• Quick Start <=5 steps
• All original technical content preserved in <details> blocks

Step 6: Self-Review Checklist

Before presenting to the user, verify:

Check	Rule
Code blocks	Each independently-runnable command is in its own block
Mermaid diagrams	>=1 diagram showing how the project works
Hero length	<=5 lines (excluding badges)
Feature descriptions	<=15 words each
Quick Start	<=5 commands
Paragraphs	No paragraph exceeds 3 sentences
Total prose	Diagrams + tables + code >= 50% of content
Original content	All preserved in <details> blocks
Fabricated data	None — real numbers or placeholders only
No emoji	Zero emoji anywhere in the output
No slop phrases	None of the banned phrases from references/anti-slop-rules.md
No filler	Every sentence adds information the reader didn't have
No rhetorical questions	No "Tired of X?" or "Want to Y?" patterns

If any check fails, fix it before presenting.

Step 7: Present to User

Briefly explain:

1. Framework chosen
2. Where original content lives (README.backup.md + collapsed sections)

Ask for feedback. Do NOT commit unless asked.

Expected Output

For a CLI tool called "fastbuild", the rewritten README.md opens with:

![stars](https://img.shields.io/github/stars/acme/fastbuild)
![license](https://img.shields.io/badge/license-MIT-blue)

# Incremental builds in under a second

fastbuild watches your source tree and recompiles only changed modules —
no config files, no daemon, no warm-up time.

[**Get Started ->**](#getting-started)

## How It Works

` ` `mermaid
graph LR
    A[Source files] --> B[fastbuild watcher]
    B --> C{Changed?}
    C -->|Yes| D[Compile changed modules]
    C -->|No| E[Skip]
    D --> F[Output bundle]
` ` `

| Feature | What you get |
|---|---|
| Zero config | Works out of the box — no setup files |
| Incremental | Recompiles only changed modules |
| Fast | < 1s on codebases with 10k+ files |

Original content is preserved in README.backup.md and in <details> blocks at the end of the new README.

Edge Cases

• No README.md found — Offer to create one from scratch using project manifest files.
• README is already marketing-style — Offer targeted section-by-section refinements; preserve what works.
• Insufficient context for value prop — Ask the user: what it does, who it's for, what problem it solves.
• No real social proof — Skip the section entirely; never fabricate stars, downloads, or testimonials.
• Highly technical README (API reference) — Preserve all content in <details> blocks; landing-page sections stay brief.
• Project with no visual output — Use code-before/after comparisons and terminal snippets instead of screenshots.
• README longer than 300 lines — Preserve full original in README.backup.md; summarize technical sections as collapsed <details> blocks.

Acceptance Criteria

• Original README backed up to README.backup.md before any rewrite
• Rewritten README uses one of PAS, AIDA, or StoryBrand and names which one was chosen
• H1 is the value proposition (<=10 words), not the project name
• At least one mermaid diagram shows how the project works
• Hero section is <=5 lines (excluding badges)
• Each feature description is <=15 words
• Quick Start has <=5 steps; each independently-runnable command in its own code block
• No banned slop phrases appear in the output
• All original technical content preserved in <details> blocks
• No fabricated data — real numbers or [placeholder] markers only
• Zero emoji in the output
• Self-review checklist (13 checks) passes before presenting

Step Completion Reports

After each major step, output a status report. See references/step-reports.md for the format and phase-specific checks.

Guidelines

• One code block per copy-paste unit. Commands that can run independently must be in separate code blocks. Only combine commands that must run together.
• Never fabricate data. Use real numbers or leave [placeholder] markers.
• Respect the project's voice. A security tool != a startup pitch.
• H1 = value proposition, not the project name.
• Preserve all original content in collapsed sections.
• One primary audience. Don't try to speak to everyone.
• When in doubt, cut text. A shorter README that gets read beats a longer one that doesn't.

Error Handling

• No README.md found -> Offer to create from scratch using project files.
• Already marketing-style -> Offer targeted refinements, not full rewrite.
• Insufficient context -> Ask: what it does, who it's for, what problem it solves.