From dca7115142222040148e4407380720cc5ef2881b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Kr=C3=A1l?= Date: Thu, 12 Nov 2026 14:43:49 +0100 Subject: [PATCH] Bring an existing README to the standard in update mode Update mode now fixes what is outdated, unsupported, or duplicated and brings the structure to the README standard, keeping the author's prose and logo. Scenario 5's invariant follows, and its re-run passes. Closes #25. --- CHANGELOG.md | 4 ++++ skills/github-readme-generator/SKILL.md | 4 +++- tests/scenarios.md | 10 ++++++---- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 37c3444..1242e3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Update mode brings an existing README to the README standard — header shape, + section names and order — while keeping the author's prose and logo, instead + of changing only the outdated parts. Scenario 5's invariant follows (#25). + - The benchmark keeps every Markdown page an agent writes besides the README under `pages/` in the case directory, and lists them in `meta.json`. The scorer accepts those pages as link targets and checks the links inside them diff --git a/skills/github-readme-generator/SKILL.md b/skills/github-readme-generator/SKILL.md index dce3267..e44f0eb 100644 --- a/skills/github-readme-generator/SKILL.md +++ b/skills/github-readme-generator/SKILL.md @@ -93,7 +93,9 @@ and state it in the handover summary. branding, useful hand-written explanation, and working links. A registry badge or docs link the README already carries counts as evidence when its slug matches the manifest, even offline — keep it and report it as unverified. Fix - only what is outdated, unsupported, duplicated, or badly ordered. + what is outdated, unsupported, or duplicated, and bring the structure to the + standard in `references/readme-structure.md` — header shape, section names + and order — keeping the author's prose and the existing logo inside it. - **Audit** — analysis only. Write nothing. Return findings with sources and a recommended fix order. Cover the README, and the two public surfaces beside it — repository metadata, and the community health files a README links to — as diff --git a/tests/scenarios.md b/tests/scenarios.md index cd60695..05f9ab2 100644 --- a/tests/scenarios.md +++ b/tests/scenarios.md @@ -58,9 +58,11 @@ per-package commands are not mixed into the root instructions. *Setup:* an existing README with a valid logo and hand-written prose, plus outdated commands, dead links, and wrong version numbers. -Invariants: the logo and valid author-written text survive; only the outdated -commands, links, and versions change; heading structure stays consistent; the -diff touches nothing but `README.md`. +Invariants: the logo and valid author-written text survive; every outdated +command, link, and version is fixed; the structure follows the README standard +— header shape, section names and order — with no section invented beyond what +the repository evidences; heading structure stays consistent; the diff touches +nothing but `README.md`. ## 6. Insufficient evidence @@ -164,7 +166,7 @@ means the scenario has not been run since this log was started. | 2 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `npm start` and `npm test` from scripts, `npm install` backed by the lock file, Node 20 from `engines`, configuration limited to the four `.env.example` names, no deployment section. | | 3 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. `Installation` clones the remote and runs `npm install --global .` (no publish evidence), the smallest invocation `slugify "Hello, World!"` → `hello-world` comes from the tests, and the full help is referenced as `slugify --help`, not transcribed. | | 4 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. The root README explains the npm workspace, links all three package READMEs, and shows only root `npm install` and `npm test`. | -| 5 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Partial (#25). Logo and hand-written paragraph survive, all five stale items fixed, only `README.md` changed. But the header was rebuilt and sections renamed and added to follow the README standard — more than the outdated parts this scenario allows. | +| 5 | 2026-11-12, Claude Code 2.1.322, `claude -p "Update the README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. Logo and the author's paragraph survive verbatim; all five stale items fixed (version pin, `require`, `npm run serve`, dead `docs/GUIDE.md` link, Node 14); header rebuilt to the standard shape with the project name as title, sections Requirements, Installation, Quick start, Testing, License, each backed by the repository; only `README.md` changed. | | 6 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. No install command, license claim, badge, or `TODO`; the handover names the missing manifest, license, and tests. Minor: a Python version was inferred from annotation syntax, disclosed as an inference. | | 7 | 2026-11-12, Claude Code 2.1.322, `claude -p "Audit this README and tell me what's wrong." --permission-mode acceptEdits --setting-sources project` | Pass for the no-metadata variant; the with-metadata variant was not run (no readable GitHub remote offline). Nothing written, findings cite file and line, a fix order is given, the dead `docs/usage.md` link and all five missing community health files are reported, and metadata is called unreadable rather than empty, with a description and seven topics proposed as text. | | 8 | 2026-11-12, Claude Code 2.1.322, `claude -p "Write a README for this repository." --permission-mode acceptEdits --setting-sources project` | Pass. Only the four `.env.example` names are documented; the `.env`-only variable and every local value are absent from the README and the output. Minor: an unsourced `. ./.env` and `curl` example in Quick start. |