iso-readme

iso-readme

Write a fresh README or refine an existing one to the house look defined in STYLE.md, then commit only the README file(s) and push. Runs in any repo, under Claude Code or Codex.

Read STYLE.md before writing — it is the single source of truth for badges, layout, voice, and writing rules (each rule carries a stable anchor like B4/L1). Before committing, clear every applicable gate in CHECKLIST.md — the Definition of Done.

Input

/iso-readme [path]

• path given — a README file or a directory (use its README.md).
• no arg — target the repo-root README.md. If the repo is a monorepo, offer to also scan subdirs that carry their own manifest (apps/*, packages/*); do not scan them unprompted.

Step 1: Detect context

Pick the layout (see STYLE.md "Layouts by context"):

Signal	Context	Layout
A SKILL.md sits in the same dir, or path is skills/<name>/README.md	skill	skill layout
Repo-root README, or an application dir	root / app	centered + badges
Manifest declares a published package (name+version, library not app)	lib / pkg	lib layout

Ambiguous → top-level defaults to root/app; a dir with SKILL.md is a skill; ask only if still unclear.

Step 2: Detect stack (stack-agnostic)

Parse whatever manifest exists to derive badge signals:

Manifest	Stack
package.json	node/TS/JS; frameworks from dependencies (next, react, express…)
pyproject.toml / setup.py / requirements.txt	python; framework from deps (django, fastapi…)
Cargo.toml	rust
go.mod	go
composer.json	php
Gemfile	ruby
none	docs-only → license badge only (if LICENSE exists), or no badges

Step 3: Write or refine

• README missing → generate fresh from the matching STYLE.md skeleton.
• README exists → refine: preserve all real content (install steps, env vars, credits, commands) — restyle layout + badges only. Never invent features or commands.
• Derive badges from Step 2, curate to 3–6 identity badges (primary lang/runtime · 1–2 defining frameworks · license) using the STYLE.md hex table. Add a missing tech as a new row in STYLE.md.
• Icon realism: use only a logo= slug you've verified. Look up brands at simpleicons.org; if absent, try React Icons ri:Si<Name> (e.g. OpenAI → ri:SiOpenai); only then fall back to logo=false + an emoji in the label. A miss renders blank. Don't hand-wave hex-table slugs as "done" — the Step 4 DoD curl-verifies every logo= badge (gate U1), so a typo or table-rot surfaces regardless. See STYLE.md "Icons".
• Pick the structure before writing the content [V11]: a table only holds values that fit on one line. The moment a column would carry a sentence — Why, Does, Notes — it is a bullet list with a bold lead term, and any short column becomes a leading marker (- 🔒 **\file`** — sentence.`). GitHub sizes columns to their widest cell, so the prose column starves its neighbours and the narrow cell is what visibly breaks.
• Format/quality: .svg (crisp, GitHub-safe), logoColor as bare hex (fff, never white), light brand colors → dark bg hex + bright logoColor. Measure real language bytes before picking language badges; don't assume.