Readme Writer

README Writer

Write the README a recruiter or judge sees first. For a hackathon project the README is a landing page, not API docs: it leads with proof (demo, awards, the result), stays scannable, and is honest about what a weekend build is and is not. Aim for the bar set by repos like DispatcherAI, TalkTuahBank, and AdaptEd: a centered hero, real badges, a clickable demo poster, and tables instead of walls of text.

What "great" means here

• Proof before prose. The demo video, the placement, and the headline stats appear before any paragraph of explanation.
• Scannable. Tables, feature cards, and collapsible sections beat long lists. A reader should grasp the project in fifteen seconds of scrolling.
• Honest about scope. A short "build context" note about what was cut for a 24-to-36 hour build earns more credibility than pretending it is production software.
• Recruiter-optimized. Team cards link out to GitHub and LinkedIn. The live link and Devpost are one click from the top.
• True. Every award, statistic, prize figure, and rank is real and sourced. Never invent one to fill a section. If a fact is unknown, omit that block.

Gather the facts

Detect first, ask second. Read what the repo already tells you before interviewing the user.

Auto-detect from the repo:

• AGENTS.md and PRD.md at the root for project name, summary, problem, features, and stack.
• package.json (name, dependencies) and folders like client/, server/, app/ for the real stack and layout.
• Existing .github/assets/, public/, or assets/ for logos, headshots, and hero images.
• LICENSE for the license badge, and the git remote for the owner/repo used in raw asset URLs.

Then ask only for what the repo cannot reveal:

• Project name and a one-line tagline that names the stakes, not the tech ("Voice banking for the 1.7 billion adults without a bank account").
• The problem, with one real statistic and its source. No invented numbers.
• Three to five headline features (the "what it does" cards).
• Demo video: the YouTube URL or ID, used for the clickable poster.
• Live deployment URL and Devpost URL, if any.
• Awards and placement, with the exact sponsor track names. Only real ones.
• Event facts: name, dates, venue, hacker count, team or submission count, prize pool.
• Team: names, roles, GitHub handles, LinkedIn URLs, and headshot paths.
• Any open-source artifacts to surface (model, dataset, design doc, Figma).

If something is unknown after asking, leave a clearly marked <!-- TODO --> placeholder rather than a broken link or a guessed fact.

The skeleton

Use this section order. Most items are optional: include one only when the facts exist, and skip what would be thin. The three exemplars each drop or reorder pieces (AdaptEd has no top stats strip; TalkTuahBank folds the numbers into the hero), so treat this as a menu, not a mandatory checklist.

1. Hero (centered): a logo, theme-aware art, or a clickable product screenshot linking to the live site; # Name; a one-line tagline that names the stakes; a short context sentence.
2. Badge rows: primary CTAs (Live, Demo, Devpost, GitHub), then awards, then a repo-vitals row (stars, forks, license), then stack chips. A centered text jump-nav row (see the design language) can stand in for or sit beside the CTA badges.
3. Table of contents (optional, for longer READMEs): an anchor-linked list of the sections below.
4. Demo poster: a clickable YouTube thumbnail with a one-line caption.
5. Stats strip (optional): a table of build time, prize total, rank, team size, event scale. Alternatives the exemplars use: fold the numbers into the hero sentence, or move them to a bottom "spec sheet" table instead of a top strip.
6. TL;DR or The Problem: What, Why, How fast, Result. Frame the problem with one sourced stat; an optional blockquote of the core thesis with a <sub> attribution reads well here.
7. Awards table (optional): Award and Sponsor or Track.
8. Live links & artifacts table (optional): deployment, Devpost, demo, open-source model or dataset, design docs.
9. What it does: feature cards in a two or three column table, each with an emoji heading.
10. Architecture: a Mermaid flowchart plus a short prose walk-through; long call flows go in <details> (use <details open> on the primary diagram when there are several).
11. Tech stack: a table by layer (telephony, inference, frontend, hosting) or grouped lists.
12. Routes / page map (optional): a Route and Purpose table when the live site is itself part of the story.
13. Repository layout: a fenced tree with inline comments, usually inside <details>.
14. Quick start: run commands, split into deployable frontend versus original backend when relevant, in <details>.
15. Team cards: headshot, name, role, GitHub and LinkedIn links.
16. Event spec sheet (optional): event, dates, venue, hackers, prize pool, what you won.
17. Build context & tradeoffs (optional but recommended): honest notes on hackathon scope, plus a "what is in this repo vs. what ran in production" note if the repo was rebuilt afterward. For a rebuilt project, a two-column "What changed" table (Original build versus This repo) makes the diff concrete.
18. Acknowledgements and License (optional): thanks to sponsors, the license.
19. Footnotes & sources (optional): a <details> citing every stat, the Devpost and demo links, and any branding or license notes. This is how you make the "every stat is sourced" rule visible to a reader.
20. Footer (centered): "Built in N hours at Event," the live and repo links, and an optional ↑ back to top link.

The design language

This is what separates a winner README from a default one. Use these recipes.

Badges (shields.io). Two weights, used consistently:

• CTAs and awards: style=for-the-badge with a dark labelColor=0A0B0D so they read as a row. https://img.shields.io/badge/Live-yourapp.com-7BFFB2?style=for-the-badge&labelColor=0A0B0D
• Stack chips: style=flat-square with the tool's logo and brand color. https://img.shields.io/badge/Next.js-000?style=flat-square&logo=nextdotjs&logoColor=white

Awards can take either weight: bold for-the-badge badges in the CTA row (DispatcherAI, AdaptEd), or a secondary row of flat-square chips (TalkTuahBank). Pick by how dense the hero already is.

Wrap each badge in a link to the relevant page. Find the right logo slug on simpleicons.org and use the brand hex. A representative set:

Repo-vitals badges come from the GitHub endpoints and make a good live row in the hero; pass &color= and &label= to match the palette:

• https://img.shields.io/github/stars/<owner>/<repo>?style=flat-square&color=F2C744&label=Stars
• https://img.shields.io/github/license/<owner>/<repo>?style=flat-square&color=64A8F0

Hero jump-nav (optional). Instead of or beside the CTA badges, a centered <p> of bolded links reads as a nav bar. Mix external links (suffix an ↗) with in-page anchors, separated by  · :

<p>
  <a href="YT_URL"><strong>Demo reel&nbsp;↗</strong></a>
  &nbsp;·&nbsp;
  <a href="#architecture">Architecture</a>
  &nbsp;·&nbsp;
  <a href="#run-it">Run it</a>
</p>

Demo poster. Do not embed a raw link. Use YouTube's auto-generated thumbnail as a clickable poster:

<a href="https://www.youtube.com/watch?v=VIDEO_ID">
  <img src="https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg" width="780" alt="Watch the demo" />
</a>

If maxresdefault.jpg is missing for that video, fall back to hqdefault.jpg, or ship a custom poster in .github/assets/.

Layout. GitHub Markdown has no grid, so use HTML <table> for anything multi-column: feature cards, the team row, the stats strip. Center the hero and footer with <div align="center">. Use valign="top" so columns align.

Collapsibles. Push long content out of the main scroll with <details><summary><b>...</b></summary>: the repo tree, local setup, a step-by-step call flow, a footnotes-and-sources list. When several sit together (for example multiple architecture diagrams), mark the primary one <details open> so it stays visible.

Callouts. Use GitHub alerts sparingly for the one thing that matters: > [!NOTE], > [!TIP], > [!IMPORTANT]. A common, high-value one is a "what is in this repo vs. production" note.

Architecture diagram. A Mermaid flowchart with short node labels and classDef color coding to group subsystems. Keep it readable at a glance; move the detailed sequence into a <details> list below it.

Section rhythm (optional). A consistent leading glyph on every H2 gives the README an identity: an emoji per section (DispatcherAI) or one repeated bar like ▌ (AdaptEd). Choose once, then apply it throughout.

Anchor links. GitHub builds a heading's anchor by lowercasing it, dropping punctuation and HTML entities, and turning spaces into hyphens (so ## The Problem becomes #the-problem). Use that to wire the table of contents and the jump-nav.

Typography. Reach for HTML entities for fine control:   to keep words together, ‑ for a non-breaking hyphen (2‑minute), – for ranges (Nov 16–17), · or · as a separator, → or ↗ for "go" links, … for elisions, and — for an aside (a comma, parentheses, or a colon often reads just as cleanly). Render routes, keystrokes, and UI chips as keycaps with <kbd>, and use <sub> or <sup> for captions.

Team cards. The base card is a headshot, name, role, and GitHub plus LinkedIn links in a <table> cell. Variations worth borrowing from the exemplars: a one-line contribution blurb per person, a ⭐ marker on the author, the GitHub link as a badge image rather than text, rounded headshots via an inline border-radius style, and a github.com/<handle>.png?size=120 avatar when no headshot file exists.

Dark and light hero (optional). Serve theme-aware art with <picture> and prefers-color-scheme sources.

Write it

Produce the full README.md, not an outline. Match the voice of the exemplars: confident, concrete, and brief. Favor a benefit-first tagline over a feature list. In the problem section, state the stakes and one sourced number, then pivot to the build.

Start the hero from this shape and fill it with real facts:

<div align="center">

<img src=".github/assets/logo.svg" width="84" alt="Name mark" />

# Project Name

### One-line tagline that names the stakes.

<a href="LIVE_URL"><img alt="Live" src="https://img.shields.io/badge/Live-yourapp.com-7BFFB2?style=for-the-badge&labelColor=0A0B0D" /></a>
<a href="YT_URL"><img alt="Demo" src="https://img.shields.io/badge/Demo-3_min_video-FF0000?style=for-the-badge&labelColor=0A0B0D&logo=youtube&logoColor=white" /></a>
<a href="DEVPOST_URL"><img alt="Devpost" src="https://img.shields.io/badge/Devpost-Submission-003E54?style=for-the-badge&logo=devpost&logoColor=white" /></a>

</div>

Keep the README a landing page. If setup runs long, collapse it. If the architecture has ten steps, show the diagram and hide the prose in <details>.

Asset handling

• Reference images by repo-relative path (./.github/assets/hero.png) or raw URL (https://raw.githubusercontent.com/<owner>/<repo>/main/...). Be consistent.
• Store new art in .github/assets/. If a needed image does not exist, insert a labeled <!-- TODO: add .github/assets/hero.png --> placeholder instead of a link that 404s.
• Team headshots can fall back to GitHub avatars: https://github.com/<handle>.png?size=120.
• If the repo has its own asset or OG-image generation (for example an opengraph-image.tsx), offer to reuse it rather than inventing a new pipeline.

Set the repository metadata (About)

The README is the page; the repo's "About" box is the search-and-preview layer that decides whether anyone opens the page at all. It shows under the repo name, in GitHub search results, and on the social card when the link is shared. After writing the README, set it from the same facts so the three stay consistent.

Set three fields:

• Description: one sentence, the tagline or a tightened version of it. Lead with what it does, not the stack, and keep it under about 120 characters so it does not truncate.
• Website: the live deployment URL, or the demo video link if there is no live site.
• Topics (tags): five to twelve lowercase, hyphenated tags pulled from the real stack and domain, plus hackathon and the event or sponsor tech where relevant (for example nextjs, fastapi, openai, voice-ai, hackathon). GitHub allows up to twenty, each lowercase and at most fifty characters. Pick the ones a recruiter or judge would actually search, not every dependency.

Apply them with the GitHub CLI from inside the repo, since the agent can run it directly:

gh repo edit \
  --description "One line on what it does, under ~120 characters" \
  --homepage "https://yourapp.com" \
  --add-topic nextjs,fastapi,openai,voice-ai,hackathon

--add-topic merges with any existing topics rather than replacing them; run gh repo edit --help to confirm the flags for the installed version. If gh is missing or not authenticated, do not guess credentials: fall back to the "About" gear on the repo's GitHub page and hand the user the exact description and topic list to paste. Never invent a description or a tag that misrepresents the project.

Verify

Before finishing, check:

• Exactly one # H1.
• Every link resolves and every badge URL is well-formed.
• The YouTube ID in the poster matches the demo link.
• Every referenced image exists in the repo or is marked TODO.
• The Mermaid block parses (balanced brackets, valid node ids).
• The repo description, website, and topics are set and match the README, with no invented claims.
• No fabricated awards, stats, prize figures, or team details.

Preview in a Markdown renderer. Note that GitHub-only features (alerts, Mermaid, <picture> theming) render on GitHub but not in every previewer, so confirm on the repo when possible.

Final output

Return:

1. README.md: written to the repo root (after showing a diff if one already exists).
2. Repo metadata: the description, website, and topics applied via gh, or the exact values to paste if gh was unavailable.
3. Asset checklist: which images exist and which are TODO.
4. Facts used vs. omitted: what was included and which sections were skipped for lack of real facts.
5. Next steps: for example, run demo-prep for the matching demo script, capture a custom poster, or pin the repo.

Boundaries

• Never invent awards, statistics, prize amounts, ranks, or team information. Omit over guess.
• Do not overwrite an existing README without showing the change and getting a go-ahead.
• Set the repo's About metadata (description, website, topics) from the same facts, and never invent a description or tag that misrepresents the project.
• Keep it a landing page, not exhaustive documentation. Deep setup and long flows belong in <details>.
• Match the repo's real stack and structure. The README describes what exists, not an aspirational version.