GitHub README Framing and Authoring Protocol v2

README FRAMING AND AUTHORING PROTOCOL v2

Use this file before writing, rewriting, restructuring, or materially reframing a repository README.

Purpose

Derive the correct README from the real project, the real reader, and the real job the README must perform.

Do not assume every repository needs the same README.
Do not assume every README should be comprehensive.
Do not assume every README should mirror familiar GitHub templates.
Do not assume the existing README is correct.
Do not let the most visible files alone define the whole repository.

Core rule

Build the smallest correct README that accurately represents the real project, fits the real reader, uses the real reader's language, and performs the real job the README needs to do.

Operating posture

This protocol is README-specific.
It is not a generic output protocol.
It exists to help the AI derive the right README from repository truth, not from template momentum, vague confidence, or inherited wording.

Interaction rules
Follow the phases in order.
Do not skip directly to drafting, formatting, badges, or polish.
Before writing, close the project model, the README role, the reader model, the language boundary, and the section model.
If ambiguity remains and could materially change reader fit, README role, claims, structure, language, or next action, stop and ask before proceeding.
When asking the operator, ask one thing at a time.
Keep materially distinct ambiguities separate. Do not bundle unrelated questions.
For any question that risks confusion or rework, make clear what kind of answer is needed, give a concrete example when useful, and state why the answer matters.
An unresolved ambiguity does not pass to the next phase.
Use real evidence from the workspace.
Do not invent features, workflows, maturity, stability, support level, or status.
Do not generate sections, setup steps, examples, badges, architecture notes, feature lists, or contribution guidance unless they are justified by the real project and the real README role.
Do not optimize for completeness by default. Optimize for correctness, clarity, fit, orientation value, and reader usefulness.
Treat an existing README as gated material. Do not read it unless operator authorization is explicitly given.
Do not let familiar GitHub conventions override the actual needs of the project.
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
whether the repository is primarily something to use, install, read, adapt, study, deploy, extend, evaluate, or reference

Possible project types include:

application
library
CLI tool
framework
template or starter
documentation repository
content repository
research repository
artifact repository
showcase repository
mixed repository
internal operational repository

Possible primary units include:

source repository
package
CLI
deployable application
documentation surface
static site
content collection
research artifact
reusable template
portfolio or showcase artifact

Questions to close in this phase:

what is this project in practical terms
what does it let a reader or user do
who is most likely to arrive at this repository
what should that reader understand within the first seconds
what should that reader be able to do next
what kind of misunderstanding would most damage the README

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

PHASE 2 - Inspect the workspace

Inspect the workspace enough to make sound README decisions.

Read only enough to close the README decision perimeter.
Do not force a full read of every file if unnecessary.
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.

Determine and report:

high-level repository structure
manifests and package descriptors, if any
entry points
core modules or core surfaces
executable surfaces, if any
scripts or commands relevant to running, building, testing, or using the project
configuration surfaces
dependency signals
deployment signals
documentation surfaces other than README
licensing signals
contribution or governance signals, if present
whether the repository appears stable, evolving, experimental, archival, or mixed
whether there are public-facing claims already encoded elsewhere in the workspace
whether the repository contains multiple reader surfaces that should not be collapsed into one README voice
README gate rule
if a README already exists, do not read it in this phase
do not use it for initial project understanding
do not treat it as a primary source
access to the existing README requires explicit operator authorization
without authorization, the existing README remains out of scope
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.

Determine and report:

the README's primary job
the README's secondary job, if any
the primary reader
the secondary reader, if any
the reader's level: expert, informed, beginner, evaluator, maintainer, mixed, or other justified level
the relationship between the README and the reader: peer, instructional, operational, reference, evaluative, mixed
the primary reader action the README should enable
what happens if the README fails: low stakes, moderate stakes, or high stakes
whether the README should prioritize orientation, setup, usage, trust, explanation, reference, or navigation
whether the README should stand mostly alone or mainly route into deeper docs
whether the README should be narrow and operational or broad and explanatory

Possible README roles include:

orientation surface
quickstart surface
usage surface
technical entrypoint
documentation gateway
installation guide
project overview
reference surface
portfolio-facing overview
research framing surface
adaptation or integration surface

Rules:

do not assume every README is mainly a quickstart
do not assume every README is mainly a project overview
do not assume every README should route into a docs tree
do not assume every project needs the same reader action
do not let a secondary reader distort the README away from the primary reader

If the README's primary role or primary reader remains materially ambiguous, stop and ask.
Do not draft until both are closed.

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.
A structurally correct README can still fail if it sounds internal, abstract, machine-like, overbuilt, or alien to the real reader.

Determine and report:

whether the README should be technical-first or orientation-first
whether it should be concise, moderate, or expansive
whether the tone should be sober, practical, explanatory, direct, or mixed
whether it should foreground setup, usage, understanding, reference, or navigation
whether it should be written mainly for newcomers, practitioners, maintainers, evaluators, or mixed readers
the real reader's natural vocabulary
which terms are normal and clear for that reader
which terms would sound internal, abstract, technical, machine-like, inflated, or framework-native
preferred wording, if known
forbidden or risky wording, if known

Rules:

do not let tone overstate project maturity, polish, stability, or support
do not let style distort the real nature of the project
do not choose a more expressive or formal posture unless the project clearly justifies it
do not default to internal system taxonomy when plain reader language exists
if a project term must be used, explain it where necessary instead of assuming reader familiarity
if the correct editorial posture or language boundary cannot be inferred and would materially change the README, stop and ask

Do not let editorial polish substitute for unresolved framing.

PHASE 5 - Design the README model

Before writing full prose, decide and report the README structure.

Determine the section model before drafting.
If the README contains sections with different jobs, different readers, or different technical depth, define that split explicitly.
Do not let the whole README collapse into one voice by default.

Determine and report:

recommended title form
recommended opening pattern
what belongs above the fold
which sections are required
which sections are optional
which sections should be excluded
what order best fits the README role
what claims are justified
what claims are not justified
what details should stay in deeper docs rather than the README
whether badges are justified
whether installation instructions are justified
whether quickstart is justified
whether usage examples are justified
whether configuration documentation is justified
whether project structure is justified
whether architecture notes are justified
whether API reference belongs here or elsewhere
whether contributing guidance belongs here or elsewhere
whether the README changes register across sections
where that section split begins and ends
what each section is trying to do
how technical each section is allowed to be

Possible sections include:

title
one-line description
project overview
why it exists
status
features or capabilities
installation
quickstart
usage
examples
configuration
project structure
architecture
development
limitations
roadmap
documentation links
contributing
license

Rules:

treat these as options, not defaults
do not generate section bureaucracy
do not include common sections just because they are common
if a section is skipped, know why
if a section is included, justify why
prefer the smallest correct structure
keep onboarding, explanation, reference, and deep technical detail separate when they serve different jobs

If section choice, section split, or claim perimeter remains materially ambiguous, stop and ask.
Do not proceed to drafting with an unstable section model.

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.
Do not let one strong local section define the whole README voice.

Drafting rules:

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 over-describe secondary or incidental parts of the project
do not let section count substitute for clarity
do not let the README become a dump of everything in the repository
keep the README aligned to the role defined earlier
keep language inside the confirmed language boundary
if the opening is reader-simple and later sections are more technical, preserve that distinction intentionally

If commands, examples, configuration, installation steps, or environment claims cannot be verified from the workspace, stop and ask before asserting them.
Do not use confident wording to hide missing evidence.

PHASE 7 - Review against project truth and reader truth

Before finalizing, produce a concise review that states:

what the README is trying to do
who the README is for
what the README foregrounds
what the README deliberately keeps out
which project claims it makes
which claims it avoids
which sections were included and why
which sections were excluded and why
whether the README has a section split and why
which points still need confirmation
which risks remain
which open assumptions remain, if any
which conflicts were found and how they were resolved, if any

Check for:

overstatement of maturity
overstatement of scope
invented features
generic template drag
missing core orientation
excessive focus on secondary parts of the project
mismatch between tone and project reality
mismatch between language and reader reality
internal or machine-like vocabulary where reader language should be used
setup steps that are not grounded in the repository
claims not supported by workspace evidence
section bleed between onboarding, explanation, and reference

Do not finalize the README until this review is complete.
If unresolved issues remain after review and could materially change the README, stop and ask.

PHASE 8 - Optional existing README audit

This phase is gated.
Only enter this phase if the operator explicitly authorizes reading the existing README.
If authorization is granted, read the existing README as material to audit, not as a primary source of truth.

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
whether the final result should be a revision, restructuring, or full rewrite

Rules:

do not let the old README override the project model already established
preserve only what remains true and useful
discard language that is stale, inflated, structurally misleading, or outside the confirmed language boundary
Final safeguards
Never assume every repository needs a comprehensive README.
Never assume every README should begin with feature bullets.
Never assume every project needs badges.
Never assume installation or quickstart belongs in every README.
Never assume contribution guidance belongs in the README rather than elsewhere.
Never assume the existing README is correct.
Never read the existing README without operator authorization.
Never optimize for template completeness.
Never use prose quality to hide unresolved ambiguity.
Always optimize for a README that is justified, accurate, readable, and fitted to the real project and the real reader.