From b73ef8fc47beed551ab2417bc495735dee39437a Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 00:38:08 +0200 Subject: [PATCH] Add README cleanup task --- README.md | 13 ++++ tasks/readme-cleanup.task.md | 133 +++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 tasks/readme-cleanup.task.md diff --git a/README.md b/README.md index 02ba693..8954446 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,19 @@ reference it from a project task. The receiving agent must still read that project's own instructions and adapt the brief to its existing CI, tools, metadata, and commit conventions. +## Task catalog + +- [`add-jenkins.task.md`](tasks/add-jenkins.task.md) adds a maintainable Jenkins + pipeline. +- [`ci-coverage-badges.task.md`](tasks/ci-coverage-badges.task.md) generates and + publishes version, test, and coverage badges. +- [`make-release-script.task.md`](tasks/make-release-script.task.md) integrates + a safe `rust_realease` wrapper. +- [`readme-cleanup.task.md`](tasks/readme-cleanup.task.md) streamlines a README, + links advanced documentation, and verifies CI-backed badges. +- [`semi-harden-ci.task.md`](tasks/semi-harden-ci.task.md) adds focused Rust + dependency security and policy gates. + ## Publishing Tasks are private to the repository by default: diff --git a/tasks/readme-cleanup.task.md b/tasks/readme-cleanup.task.md new file mode 100644 index 0000000..5c9b461 --- /dev/null +++ b/tasks/readme-cleanup.task.md @@ -0,0 +1,133 @@ + + + +# Clean up a repository README + +Apply this task to one repository at a time. Read its local agent instructions, +README, documentation tree, package metadata, and CI configuration before +editing. Preserve unrelated work, follow the repository's commit policy, and +do not push, trigger CI, or publish assets unless explicitly requested. + +## Establish the documentation contract + +Treat the repository and its executable configuration as the source of truth. +Before rewriting prose: + +1. identify the intended audience and the project's current purpose, support + status, canonical owner and project name, default branch, and license; +2. run or otherwise verify the shortest supported install, build, and usage + path rather than copying stale commands; +3. locate authoritative contributor, configuration, deployment, release, + troubleshooting, security, and architecture documentation; +4. inspect inbound links, relative links, anchors, badges, screenshots, and + commands so useful references are not silently broken; and +5. note content that is duplicated, obsolete, speculative, or too detailed for + first-time readers. + +Do not invent features, compatibility promises, commands, support channels, or +publication state. Preserve legally or operationally required notices. Keep +project-specific terminology where it is meaningful, and explain it before +using unexplained abbreviations. + +## README structure + +Make the README a concise entry point. Prefer this order when it fits the +project, adapting or omitting sections rather than creating empty headings: + +1. project title and verified status badges; +2. one short explanation of what the project does and who it is for; +3. prerequisites and the smallest working installation or setup path; +4. a minimal usage example with its expected result; +5. links to configuration and task-oriented documentation; +6. development and contribution commands; and +7. license and support information. + +Use descriptive link text and relative links for files within the repository. +Keep heading levels ordered, use one term consistently for each concept, label +code fences, and keep commands directly runnable from the stated directory. +Avoid tables of contents for short READMEs, repeated navigation blocks, +marketing filler, exhaustive option references, and prose that merely restates +command output. + +Preserve existing information until it is proven obsolete or has a clear new +home. A shorter README is not successful if maintainers lose necessary +operational knowledge. + +## Advanced documentation + +Keep the basic install and first-use path in the README. When advanced material +makes that path hard to scan, move cohesive topics into the repository's +existing documentation structure. If no suitable structure exists and the +material justifies a separate page, create a small `docs/` area following the +project's naming conventions and add an **Advanced** section to the README that +links directly to each new page. + +Advanced topics can include architecture, uncommon configuration, production +deployment, CI internals, release procedures, performance tuning, and detailed +troubleshooting. Do not move essential prerequisites, safety warnings, or the +only working example out of the README. Ensure moved pages link back or provide +enough context to be usable when opened directly. Update all affected relative +links and avoid creating placeholder pages. + +## Verify CI-backed badges + +Determine whether the README is expected to show the current default-branch +version, test, and coverage badges. Resolve ``, ``, +``, and `` from the canonical repository and CI +configuration, not merely from the checkout directory. Check these exact +public URLs after substitution: + +```text +/coverage////version.svg +/coverage////test.svg +/coverage////coverage.svg +``` + +Verification must cover the complete path from generation to publication: + +- inspect CI and tracked scripts to confirm all three SVGs are generated from + authoritative version, test, and coverage results; +- confirm CI validates the files as regular and nonempty, archives exactly the + intended badges, and publishes them only from the default branch to the path + represented by the public URLs; +- check that the default branch, owner, project, filenames, asset mount, and + public origin agree across CI, scripts, server documentation, and README; +- if network access is available, request each public URL, require a successful + response with SVG content, and parse it as XML; distinguish a live but stale + badge from a missing, invalid, or unpublished badge; and +- verify badge alt text is meaningful and place the three badge images directly + below the README title without linking them to a report CI does not retain. + +Do not treat the presence of a README image URL, a workspace SVG, or an archive +pattern as proof that CI publishes the badge. Do not claim the public badges are +live until a successful default-branch build has generated and published all +three and their public responses have been checked. + +If the project intentionally provides these badges and the existing pipeline +is incomplete, make the smallest in-scope correction when it is straightforward +and verify it. For a missing or materially broken badge pipeline, apply +[`ci-coverage-badges.task.md`](ci-coverage-badges.task.md) as a separate logical +change instead of embedding a large CI redesign in the README cleanup. Until +publication is verified, remove or clearly avoid introducing broken badge +images and report the exact gap. + +## Verification + +Before committing: + +1. render or preview the README and every new documentation page; +2. check local links, anchors, image references, and code-block formatting with + the project's Markdown tooling when available; +3. run every changed quick-start and development command that is safe and + locally reproducible, and state which commands could not be exercised; +4. search for stale references to renamed or moved headings and files; +5. verify the three badge generation and publication paths as described above, + recording whether the public URL check was performed or unavailable; +6. inspect the diff for lost information, accidental reflow, project identifiers + copied from examples, secrets, and unrelated edits; and +7. commit the README, any moved documentation, and directly related fixes as + focused, reviewable changes. + +Report the final README organization, documentation moved or removed, commands +and links checked, the status of each expected badge URL, the commit ID, and any +CI or network verification that remained unavailable.