GitHub README Authoring Protocol v2 — Smallest README

Phase 1 — Classify the Project

Determine and report: project name, project type, primary purpose, primary audience, current maturity, primary user or reader, primary public or operational unit, whether the repository is product-facing, developer-facing, research-facing, content-facing, internal-facing, or mixed, and whether the repository is primarily something to use, install, read, adapt, study, deploy, extend, evaluate, or reference.

TypeDescriptionapplicationA runnable software applicationlibraryImportable or linkable code for reuseCLI toolA command-line interfaceframeworkAn opinionated structure or runtime scaffoldtemplate or starterA starting point or scaffolddocumentation repositoryWritten documentation as the primary outputcontent repositoryWritten, media, or mixed contentresearch repositoryExperimental work, studies, or findingsartifact repositoryCompiled or packaged release artefactsshowcase repositoryPortfolio or demonstration workmixed repositoryMore than one type in meaningful proportioninternal operational repositoryTooling, configs, scripts not intended for public use

UnitExamplessource repositoryThe repo itself is the artefactpackagenpm, PyPI, RubyGems, etc.CLICommand-line tooldeployable applicationA runnable build or containerdocumentation surfaceRendered docsstatic siteGitHub Pages or similarcontent collectionA set of articles, files, or mediaresearch artifactPapers, notebooks, datasetsreusable templateStarter files, scaffoldportfolio or showcase artifactDemonstration or portfolio entry

Stop and ask if classification remains materially ambiguous. Do not proceed with README role selection or section design on unresolved project classification.

Phase 2 — Inspect the Workspace

Read only enough to close the README decision perimeter. Determine and report: high-level repository structure, manifests and package descriptors, entry points, core modules, executable surfaces, scripts relevant to running or building the project, configuration surfaces, dependency signals, deployment signals, documentation surfaces other than the README, licensing signals, contribution or governance signals, whether the repository appears stable or experimental, whether there are public-facing claims already encoded elsewhere, and whether the repository contains multiple reader surfaces that should not be collapsed into one README voice.

Do not compensate for missing evidence by falling back to generic README conventions. If workspace evidence is insufficient to support justified framing, stop and ask.

Phase 3 — Determine the README Role and Reader Action

Before drafting anything, decide and report what job the README must perform. Close the reader before closing the structure. Do not design a README for a generic GitHub visitor if the real reader is narrower or more specific.

RoleWhen to useorientation surfaceReader needs to understand what the project isquickstart surfaceReader needs to go from zero to running quicklyusage surfaceReader knows what it is; needs to use ittechnical entrypointReader is a developer or integratordocumentation gatewayREADME routes into a deeper docs treeinstallation guidePrimary job is getting it installedproject overviewBroad summary for evaluators or newcomersreference surfaceLookup-oriented; reader returns repeatedlyportfolio-facing overviewEvaluator or employer audienceresearch framing surfaceAcademic or experimental contextadaptation or integration surfaceReader is adapting or embedding the project

Phase 4 — Determine Editorial Posture and Language Boundary

Before defining sections, decide and report how the README should sound and what kind of language it is allowed to use. Tone is not decoration — language is part of reader fit.

Determine and report: whether the README should be technical-first or orientation-first, whether it should be concise, moderate, or expansive, the appropriate tone (sober, practical, explanatory, direct, or mixed), the real reader’s natural vocabulary, which terms are normal and clear for that reader, which terms would sound internal or inflated, and any preferred or forbidden wording.

Phase 5 — Design the README Model

Before writing full prose, decide and report the README structure. Determine and report: recommended title form, recommended opening pattern, what belongs above the fold, which sections are required, which are optional, which should be excluded, the order that best fits the README role, which claims are justified, which claims are not justified, and what details should stay in deeper docs rather than the README.

Phase 6 — Draft the README

Write the README only after the model is defined. Write each section for its actual reader, actual job, and allowed technical depth.

Write in plain, direct language.

Avoid filler, ceremony, and generic GitHub mood.

Start with what the project is and what it does.

Make examples, commands, and setup steps accurate and project-real.

Make claims proportionate to the actual maturity and scope.

Prefer concrete explanation over generic marketing language.

Do not let section count substitute for clarity.

Phase 7 — Review Against Project Truth and Reader Truth

Before finalising, produce a concise review stating: what the README is trying to do, who it is for, what it foregrounds, what it deliberately keeps out, which project claims it makes, which claims it avoids, which sections were included and why, which sections were excluded and why, and which risks remain.

Overstatement of maturity or scope

Invented features

Generic template drag

Missing core orientation

Mismatch between tone and project reality

Internal or machine-like vocabulary where reader language should be used

Setup steps not grounded in the repository

Claims not supported by workspace evidence

Do not finalise the README until this review is complete.

Phase 8 — Optional Existing README Audit (Gated)

If authorised, determine and report: what the existing README gets right, what it gets wrong, what it overstates, what it understates, what should be preserved, what should be revised, what should be removed, and whether the final result should be a revision, restructuring, or full rewrite.