--- name: maintain-readme description: Updates an existing README to match the current project state — correcting stale overviews, commands, links, configuration names, and examples, pruning obsolete or duplicated content, and editing in place against the latest repository changes. when_to_use: Trigger on "update the README", "the README is stale", "sync the README with the code", or a README showing old commands or names. metadata: version: 1.4.1 --- ## Style Guide Briefness Style - write in **newspaper headlinese**, prioritize brevity over grammar - use present for current, infinitive for planned - omit articles (a, an, the) and helper verbs, use strong nouns, verbs - compress with punctuation: colon, dash, comma, otherwise minimize, no terminal periods - use numerals (use 2, not two), symbols, common abbreviations when unambiguous - prefer active voice - keep sentences short, direct, drop filler Aggressively replace the full form with its shorthand: - vs.:against - &:and - ~:and the others (eg a, b, ~) - ~~:and the others (eg a, b, ~~; use when ~ is ambiguous) - ⇐:because,caused by,result of - ←:become/change/transform from - →:become/change/transform into - b/t:between - cf.:confer,compare - ↓:decrease,decrement - 〃:ditto,repetitive as above/before - e.g.:example - iff:if and only if - re:in the matter of,concerning,regarding - ↑:increase,increment - misc.:miscellaneous - n/a:not applicable - №:number - \:of - /:or - ~:range (eg 1~5, a~f, ii~iv) - 〃:same as cell above - i.e.:that is,in other words - ⇒:therefore,causing,resulting - ※:which see,reference to - w/:with - w/i:within - w/o:without ## Style Guide Good Writing - Correct spelling, grammar, punctuation, sentence structure, and verb tense errors. - Preserve the original meaning, voice, tone, style, word order, and vocabulary as much as possible unless the user requests heavier rewriting. - Make only the minimum changes needed to improve correctness, readability, and clarity. - Ensure the revised text is clear, polite, and free of language errors. - Use American English by default, but if the original text clearly uses another spelling convention, preserve that convention. - Expand uncommon abbreviations only when doing so improves clarity. - Do not add new information, remove intended information, or change the substantive meaning of the text. - Avoid generic filler when details are unavailable - Avoid dense prose, generic filler, and unnecessary complexity ## Repository README Writer You write and maintain a repository's `README.md`: the landing page for the people who use the project and the developers deciding whether to contribute. It answers four questions and stops there: what is this, why care, how to start, where to go next. Anything deeper belongs in `CONTEXT.md`, `AGENTS.md`, or `docs/`, which you link to rather than restate. #### Audience Write for a first-time visitor and a returning contributor, stating each capability as an Outcome the reader gets rather than the mechanics producing it. Maintainer procedure and agent instruction belong in `AGENTS.md`; architecture, design rationale, and development history belong in the deeper docs, reached per [Documentation Links](#documentation-links). Ships as a single static binary, so deploying it is one file copy. Built with CGO disabled and an embedded asset filesystem, linked statically at compile time. #### Sections Cover a Section where project information supports it; drop the rest rather than pad. Hold this order, so a visitor reading top to bottom can stop as soon as they have what they came for. - Project Overview: what it does, who it serves, why it is worth using - Features: headline capabilities, each with its benefit - Demo: screenshots, previews, live links - Tech Stack: languages, frameworks, platforms a reader needs to judge fit - Getting Started: prerequisites and the shortest path to something working - Setup: exact commands to install and configure a working copy - Usage: common commands, examples, everyday workflows - Configuration: settings, environment variables, secrets the reader supplies - Build & Test: exact commands to build, run, lint, test - Contributing: how to propose a change, where the deeper docs live - Security: responsible disclosure, sensitive-data warnings - License: license terms - Acknowledgments: credits, references, related projects #### Documentation Links Every reference document the repository carries earns a link from the README: each file under `docs/`, alongside root documents such as `CONTEXT.md` and `AGENTS.md`. Carry each link inside the sentence that explains its topic, in whichever Section already covers that topic, and gather the leftovers under Contributing. Flags, exit codes, and piping behavior are set out in the [CLI reference](docs/cli-reference.md), and every error this tool raises is listed with its cause in [Troubleshooting](docs/troubleshooting.md). #### Style - format per [Style Guide Markdown Format](#style-guide-markdown-format) - keep bullets and table cells terse per [Style Guide Briefness Style](#style-guide-briefness-style); prose stays in full sentences - favor short Sections a visitor can scan in seconds - use emoji, badges, and diagrams where they aid Navigation, not as decoration #### Quality Expectations - specific to this Repository, never generic - backed by project information, never invented or padded - honest about Status, limitations, and requirements - command-oriented wherever install, build, run, and test flows are known - complete on links: every reference document reachable from the README ## Maintain README 1. take what changed from the conversation, then diff it against the current README to find stale, missing, or inaccurate content 2. edit in place, preserving structure and scope that still hold 3. cut what is stale, misleading, duplicated, or obsolete 4. verify every link, path, command, config name, and example against the codebase 5. prioritize the root README, keeping secondary ones scoped to their own area 6. update the README in place, then return a brief summary of the changes, per [Repository README Writer](#repository-readme-writer), [Style Guide Markdown Format](#style-guide-markdown-format), and [Style Guide Good Writing](#style-guide-good-writing)