1---
2name: readme-forge
3description: Generate a README in alxx's personal style. Use when user says "write a README", "create README", "readme for this project", "update README", or needs a repo README.
4disable-model-invocation: true
5argument-hint: "[repo path or leave blank for current]"
6---
7
8# README Forge
9
10Generate a README following alxx's personal style.
11
12## Step 1: Analyze the Repository
13
14Target: $ARGUMENTS (if blank, use current working directory).
15
16Read the codebase to understand:
17- What it does (one sentence)
18- Who it's for
19- Tech stack and architecture
20- How to install and run it
21- Key features
22- Build/test commands
23- License
24- Dependencies and credits
25
26Read existing README if one exists. Check CLAUDE.md, package.json, go.mod, Makefile, Cargo.toml for project metadata.
27
28## Step 2: Apply alxx's README Pattern
29
30Every README follows this exact structure. Do not skip sections, do not reorder.
31
32### Structure
33
34```markdown
35# Project Name
36
37OR replace h1 with a banner image:
38- Full-width branded banner at `assets/project-github-banner.png` (recommended: ~2075x208px, 10:1 aspect ratio)
39- Followed by `---` separator
40- Optional: centered badge row (CI, coverage, tests) under the separator using `<p align="center">`
41- When banner is present, use `## 🚀 Overview` (with rocket emoji)
42- When no banner (just h1), use `## Overview` (no emoji)
43
44**Bold tagline - one line, punchy, states the core value prop.**
45
46## Overview (or 🚀 Overview if banner present)
47
48What this is in 2-3 sentences. Include a **bold analogy** comparing it to something familiar
49(e.g. "Git for agent context", "your Teams data in your terminal").
50
51***Bold italic one-liner for the key technical differentiator.***
52
53## Quickstart
54
55Copy-paste commands to get running. No explanation between commands unless critical.
56Start from git clone or go install, end with the app running.
57
58```bash
59git clone ...
60cd ...
61make setup
62make dev
63```
64
65## Why
66
672-3 sentences on the problem. Why existing solutions suck.
68Direct, slightly opinionated. No corporate speak.
69
70## Features
71
72- **Feature Name** - what it does, one line
73- **Feature Name** - what it does, one line
74- **Feature Name** - what it does, one line
75
76Bold the feature name, dash separator, brief description. 5-8 features max.
77
78## Vision (optional - include only for ambitious/platform projects, skip for focused tools)
79
80Where this is going. 2-3 sentences. Forward-looking but concrete.
81Mention what's next without over-promising.
82
83## Architecture
84
85Mermaid diagram showing the main flow. Keep it simple - major components and their connections.
86Flowchart LR preferred (left-to-right reads naturally).
87
88```mermaid
89flowchart LR
90 A[Input] --> B[Core]
91 B --> C[Output]
92```
93
94
95## Contributing
96
972-3 lines. "PRs welcome. For major changes, open an issue first."
98Mention CLA if one exists. Keep it short.
99
100## Legal
101
102One line on licensing. Mention any API usage disclaimers if relevant.
103
104## License
105
106One line linking to LICENSE file. e.g. `[MIT](LICENSE)`
107```
108
109**Sections can vary from project to project** - not every project needs Why, Vision, or Architecture. Adapt based on what's relevant. But the style is always kept: short, concise, dense, no fluff. Every section earns its place or gets cut.
110
111## Step 3: Style Rules
112
113These are non-negotiable:
114
115- **h1 or banner** - either `# Name` or full-width banner image with `---` separator
116- **Bold tagline** directly under h1/banner, no gap
117- **Overview** - first section is always Overview. use 🚀 emoji only when banner is present, plain `## Overview` otherwise
118- **Blockquote pitch** for the audience, in or after overview
119- **Bold analogy** in overview (comparing to something familiar)
120- **Bold italic** (`***text***`) for punchy one-liners
121- **Bold feature names** with dash separator in features list
122- **Mermaid diagram** - always include one, flowchart LR preferred
123- **Quickstart must be copy-paste** - someone should be able to run every command in order
124- **FAQ is optional** - rarely used, only include for projects with common objections (e.g. "why not X?"). if something needs explaining, prefer putting it in the relevant section
125- **No badges** unless the project has CI set up
126- **Bold key phrases in longer text** - in paragraphs, `**bold**` the important terms/concepts so readers can scan (e.g. "Nebula is **Git for agent context & tasks**")
127- **Dense, no fluff** - every sentence carries information
128- **No "Getting Started" header** - use "Quickstart" for apps/CLIs, "Install" for packages/skills/libraries
129- **No separate "Installation" header** - fold into Quickstart or Install
130- **No "Usage" header** - fold into Quickstart or Features
131- **No long dashes** - never use "—" (em dash), use "-" or commas instead
132- **No AI slop** - no "furthermore", "it's worth noting", "comprehensive"
133- **Casual but professional** - not corporate, not too informal for a repo README
134
135## Step 4: Tone Calibration
136
137Read the project's CLAUDE.md or existing docs to match tone. If it's a serious infrastructure tool, lean professional. If it's a personal tool, lean slightly casual. Never go full bro-mode in a public README.
138
139Key phrases that fit alxx's style:
140- "No middleman" / "no admin consent"
141- "Single binary" / "your data, your machine"
142- "Local-first, privacy-first"
143- Direct comparisons: "Every existing X requires Y. This needs none of that."
144- Forward-looking vision without buzzwords
145
146## Step 5: Generate
147
148Write the full README following the structure above. Include sections that are relevant to the project, skip ones that aren't. Keep the order.
149
150## Step 6: Validate
151
152- [ ] h1 or banner image at top
153- [ ] Bold tagline under h1/banner
154- [ ] Overview as first section (🚀 emoji only if banner present)
155- [ ] Blockquote audience pitch
156- [ ] Overview with bold analogy
157- [ ] Bold italic differentiator line
158- [ ] Quickstart with copy-paste commands
159- [ ] Why section (problem statement)
160- [ ] Features with bold names + dash + description
161- [ ] Vision section (optional - only for platform/ambitious projects)
162- [ ] Mermaid architecture diagram
163- [ ] Contributing section (short)
164- [ ] Legal section
165- [ ] Credits section (if applicable)
166- [ ] FAQ only if truly needed (rare)
167- [ ] No "Getting Started", "Installation", or "Usage" headers
168- [ ] No AI slop phrases
169- [ ] Under 200 lines (aim for 80-150)
170- [ ] Every command in Quickstart actually works