re0-readme

Audit a repository's README, AGENTS.md and manifests with the bundled script, then move, rewrite or keep each flagged line so it lives in the file whose reader needs it, and correct each manifest that disagrees with the repository.

Goal

README.md serves a person deciding whether and how to use the repository. AGENTS.md serves an agent working inside it: layout, commands, gates, conventions. Each line lives in the file whose reader needs it. A fact both readers need takes one form per reader (the address a person opens in README, the configuration an agent maintains in AGENTS.md); neither file restates the other's procedure, and each links rather than copies. The manifests a host or registry shows before either file is opened (package.json, .claude-plugin/ and .codex-plugin/ plugin files, marketplace files, each skill's agents/openai.yaml) answer to the repository's one name, point at its own address, and list exactly the skill folders it ships, so a rename that reaches README but not a manifest leaves the old name on every host that lists it.

The trigger is a README or AGENTS.md that is about to be written, was just written, or is under review, or a line in one suspected of serving the other file's reader. The input is the repository root (the repository the request is about, or the working directory's when none is named), and optionally the kind, extra local-state folder names, and whether the run may rewrite or must only report.

Every run reports the baseline audit, its kind and source, each finding's rule id, file, line and severity, and a keep list with reasons. A review-only run reports proposed moves and stops without edits, an after audit or a hosted audit. An already-green run reports the baseline and stops unchanged. A rewrite reports the edited files, the after audit and the hosted audit or its unresolved failure.

When the baseline audit is green, review every finding and the intended changes, including manifest corrections; stop unchanged only if none needs action. Zero edits is a successful run.

Workflow

1. Run the audit before any edit and keep its output as the baseline. From this skill's folder:

   node scripts/audit.mjs [<repo-root>] [--kind app|cli|library|skills] [--loop-dir <name>]... [--host <owner/repo>] [--strict] [--json] [--rules]

   It reports each finding with its rule id, file, line and severity, sorted by file, line, then rule id. --json prints the result as one JSON object; --rules prints every rule id with its severity per kind. Exit codes: 0 no fail finding; 1 a fail finding, any finding under --strict, or AGENTS.md missing; 2 a usage error or an unreadable input (unknown kind, a root that is not a directory, a package.json that does not parse). An exit of 2 is a broken run, never a red audit: fix the command or the input and run again. When only CLAUDE.md exists, read it as the agent guide and report the missing AGENTS.md failure; a rewrite may create AGENTS.md as the guide or a link to CLAUDE.md, then rerun the audit. A review proposes that repair without writing.

2. Check the kind. The kind is detected from repository files unless --kind is given; compare it with what the repository ships and pass --kind when detection is wrong. A dot folder the repository's own .gitignore excludes is treated as local state, and --loop-dir adds one more name per use, so pass it for a local-state folder the .gitignore does not name. The kind decides severity: commands are product surface for a CLI, agent vocabulary is the subject of a skills catalog, pictures are product for an app.
3. Read every finding in context. A match is a lead, never a verdict: a troubleshooting variable can belong in a README, and a contributor test command can stay as a note. Decide move, rewrite, or keep for each finding, and write the reason for each keep into the keep list, which goes in the report rather than a file. When a fact is copied into both files, or into a third doc, beyond the one-form-per-reader split, call the Skill tool with "ssotize" (paperthin:ssotize).
4. Stop here on a review request. A request to review, audit or check reports the baseline, the proposed move for each finding and the keep list, and edits nothing. Continue only when the request is to write, fix or rewrite the files.
5. Rewrite README for its reader, in the language that reader reads, which the repository's owner or its sibling repositories set, never the language the code happens to be written in: lead with one sentence saying what the product is, then what it does today as measured, then a visible result or usage example, the shortest working setup, supported environments, dependencies that matter, and links to deeper docs. A product that does less than it was built to do says so near the top, with the measurement, and says what it was designed for only as the goal; a README describing the design as the present misleads the reader the file exists for. In list tables, turn grouping columns into sections, show status with an icon and a word, and give the legend once. Keep operational detail only where it helps a person use or contribute. When stack, vendor or tool nouns in README stand for a mechanism, call the Skill tool with "detool" (paperthin:detool).
6. For a visual product, put real product images before long explanation. Capture each after the scene has finished loading its fonts, images and data, and inspect a frame before publishing. From the day the product runs on phones or other devices, show their screens beside the desktop screen and capture them with a repository script using committed example data. Image sizes and folders follow the repository's convention.
7. Where motion shows the product better than a still, embed a video the host plays. A repository-relative or raw video link is only a download. On GitHub the player is a https://github.com/user-attachments/assets/<id> URL alone in its paragraph, the address GitHub gives a file attached to an issue or pull request comment: drop the file into a comment box, which returns the URL, or attach it from GitHub's CLI to a comment it posts. Post the comment that carries the file, since how long GitHub keeps an upload no posted comment links is unverified, and keep the original in the repository or a release asset, since a deleted attachment stops playing. Directly above or below the player put a poster image or GIF with alt text, linked to that kept original, and a line saying what the video shows, for hosts and agents that cannot play it. Then check each surface that renders the README: on the host, play it signed in and, for a public repository, signed out (a private repository's attachments open only to readers with access to it); on a surface that cannot play video (a package registry page, a mobile client, a plain-text copy for agents), the poster, its link and the line are all present. A surface not checked, or a run with no browser, leaves the video unverified.
8. Rewrite AGENTS.md for its reader, the agent, in English unless the repository's contract names another language for it; a README written for Korean readers does not move AGENTS.md into Korean. Open with which document owns which kind of fact, then the repository map, run commands, gates with what each protects, failure rules with their evidence, document conventions and commit conventions. After the owner table, call the Skill tool with "re0-order" (paperthin:re0-order) to put sections and listings in one stated order. A rule a check enforces names that check beside it, so an agent can run it; a measured case stays one sentence of evidence, and explanation meant for a person moves to README. Link contracts and evidence in their original language rather than translating them. When either file has bloated past its load-bearing density, call the Skill tool with "debloat" (paperthin:debloat).
9. Align the manifests the audit names: give each the repository's name (an npm name in its lowercase form), point each address at the repository's own origin, list every skill folder a plugin ships and nothing else, and give each skill an agents/openai.yaml whose default prompt names $<skill>. A manifest the repository generates is fixed at its generator.
10. Rerun the audit and read both files and the manifests as their intended readers would.
11. Audit the hosted surface with node scripts/audit.mjs --host <owner/repo>. Review the description against the README opening and its claims, topics, homepage authority, community profile gaps, README size and, when a custom social preview is set, its size and suitability. The host audit reports only: propose corrections for its findings. A setting that trades one gain for a loss is printed as an option, never a finding, and never fails a run: no custom social preview keeps GitHub's default card with live stars, forks and contributors, so the report tells the owner it can be changed and leaves the choice to them.
12. Taste-test the rewrite: call the Skill tool with "sip" (paperthin:sip) before the approval stop.
13. Propose the gate, and end there. When the repository keeps a gate list, propose adding the audit to it as a vendored copy of the script with a comment naming where it came from, so the gate runs on a fresh clone; never point a gate at a path that exists on one machine. The human decides, and nothing is added to the gate list or CI before approval.

Rules

• When the host has no Skill tool, read and follow each named installed skill directly; if it is unavailable, report the missing step and do not claim it ran.
• The script owns the rule table. Name the script, its flags and exit codes, and never restate the rules; --rules prints them.
• An explanation never changes the exit code. An accepted note can pass without --strict; a kept fail stays red. Correct the kind, or propose a change to the repository's own copy of a rule when justified, or report the gate as unresolved. Never claim a prose exception passed it.
• Moving content loses nothing: a line leaving one file lands in the other, in a linked doc, or in the keep list with its reason. Deleting a fact outright needs the human's approval.
• Review requests report only. Rewrite only when the request is to write, fix or rewrite the files.
• Edit safely: assert each target line exists before replacing it and report a MISS, edit unicode-safe, act per occurrence, never by blanket sweep.
• Contracts, ledgers, changelogs and release notes are out of scope.
• Three changes wait for the human's explicit approval, and the run reports each as a proposal until it arrives: adding the audit to the repository's gate list or CI (step 13); deleting a fact that has no other home; changing a rule in the repository's vendored copy of the script.

Verification

Before finishing, confirm:

1. Every report includes the baseline and kind source; a rewrite also includes the after audit and hosted result, while a review or already-green run stops at its stated exit.
2. Every finding is moved, rewritten, or kept with a stated reason, or has a proposed disposition in a review, and no fail finding is reported as passed by explanation.
3. No fact was lost: each moved line is findable in its new home.
4. For a rewrite, README opens with what the product is, and the agent guide opens with which document owns what.
5. For a rewrite, README states what the product does today as measured, in the language its reader reads, and the hosted description says the same, or its new line is proposed.
6. For a rewrite that embeds a video, every surface step 7 names passed its check, or the report names the video unverified with each surface not checked.
7. Any gate change waited for approval, and every approval stop still open is named in the report.