# /readme [project]

High-conversion README + docs production.

## Structure

A high-conversion README follows this sequence:
1. **Hero** — one sentence: what it does + who it's for
2. **Problem** — why the default approach fails
3. **Solution** — what this does differently (not a feature list)
4. **Quick Start** — working in under 5 minutes (exact commands)
5. **How it Works** — for the reader who needs to understand before trusting
6. **Full Docs** — link to /docs or inline if small project
7. **Contributing / License** — last, not first

## Procedure

### Step 1 — Load brand context

Read `.claude/agent-memory/content-creator/brand-memories/{brand}.md`.

### Step 2 — Draft

Invoke `content-creator` agent. README rules:
- Hero line: specific — includes the problem it solves AND who it's for
- No "welcome to X" opener
- Quick Start: must work on copy-paste, zero modification
- Code blocks: use real examples, not `<your-value-here>` placeholders
- Badges: only if they reflect real CI/coverage/version status
- Screenshots: only if they show the actual interface, not a mock

### Step 3 — Audit

Invoke `auditor` agent. Checks:
- Hero line passes the "could this be any project?" test (if yes, not specific enough)
- Quick Start actually works (commands are real and in order)
- No marketing copy in technical sections
- Voice matches brand calibration

### Step 4 — Output

Print README markdown. If FAIL: print fix list.

## Docs extension

If `/readme --full` is specified: also draft:
- `/docs/getting-started.md`
- `/docs/configuration.md`
- `/docs/examples.md`
Each section follows the same quality gate.