Six jobs that repeat in every repository. For each: when it runs, which commands, what counts as success, and what a failure means.
When: the project is published, the README was written long ago, metadata was filled in by feel.
python tools/ghagent.py audit . --json > audit.json
python tools/ghagent.py audit --repo owner/name --http
python tools/ghagent.py report . --out AUDIT.mdSuccess: score at least 80%, no blocking findings, more than twenty items examined. A low
score is not a verdict but a work order: fix error first, warn second, leave info.
Failure: remote.unavailable means neither gh nor GITHUB_TOKEN is present. That is not
"all good": the metadata was not examined, and the report says so.
When: a new project, or the README stopped answering "how do I run this".
- Start from
reference/readme-template.mdandreference/agents-template.md. - Fill in facts: commands, paths, versions, numbers with a source.
- Render the banner:
python tools/ghagent.py assets render --write, then place the image above the first section and runassets check. - Verify:
python tools/ghagent.py doc --root ..
Success: one H1, a summary paragraph, at least three badges, installation, usage and
license sections present, every link alive, the banner referenced and the social preview
1280×640.
Failure: md.toc means the table of contents drifted from the headings. Do not fix it by
hand — an anchor is the heading lowercased with punctuation dropped and spaces turned into
hyphens.
When: [Unreleased] has accumulated changes.
python tools/ghagent.py changelog check
python tools/ghagent.py changelog suggest --since v1.1.0
python tools/ghagent.py changelog release 1.2.0 --write
python tools/ghagent.py changelog notes 1.2.0 > release-body.md
gh release create v1.2.0 --notes-file release-body.md --title v1.2.0Success: the new version has an ISO date, [Unreleased] is empty again, comparison links are
updated, changelog check is clean, and a human has read the release body.
Failure: changelog.duplicate means the version exists; changelog.empty-version means
there is nothing to release. An empty release makes the changelog meaningless.
When: documentation outgrew the README, or a wiki exists without navigation.
python tools/ghagent.py wiki init --repo owner/name --title "Project name" # when there is none
python tools/ghagent.py wiki build
python tools/ghagent.py wiki verify
python tools/ghagent.py wiki publish --repo owner/name # dry run
python tools/ghagent.py wiki publish --repo owner/name --push # publishThe very first publication needs one manual step: <repo>.wiki.git is created by GitHub only
when a first page is saved in the web interface. Until then the command answers
wiki.remote-missing with that instruction instead of failing on a push.
Success: build and verify clean, the dry run shows only expected files, the kept list
has been read, and after --push the page opens.
Failure: wiki.page-unlisted means a file exists that the manifest does not list; such a
page is invisible, which is why it is an error. wiki.image-relative means the image lives
inside the wiki sources: move it into the repository tree and reference it by absolute URL.
When: the repository has no picture, the link card looks empty, or a chart is needed in the README.
python tools/ghagent.py assets suggest
python tools/ghagent.py assets render --eyebrow "ONE COMMAND PER JOB" \
--summary "What it does, for whom." --tagline "One more sentence." \
--command "project --help" --output "usage: project [-h]" --write
python tools/ghagent.py assets checkThe card derives its fact pills from the tree (--facts auto); pass --fact "Label=Value" to add
one, and --output or --output-line for terminal output — the renderer draws no line it was not
given.
Success: assets/social-preview.png is 1280×640, under 1 MB, referenced from the README with
alt text, and assets check exits 0. Then upload the same file in Settings → Social
preview — that step is manual and the check prints it.
Failure: assets.social-dimensions means the image is smaller than 640×320 or not 1280×640;
assets.svg-social means an SVG was offered as a social preview, which the platform rejects;
assets.missing-file means the README points at a file that is not committed.
When: the repository is published, or the description and topics no longer match the content.
python tools/ghagent.py meta suggest
python tools/ghagent.py meta apply --repo owner/name --description "…" --topics a,b
python tools/ghagent.py meta apply --repo owner/name --description "…" --topics a,b --write
python tools/ghagent.py audit --repo owner/name --httpSuccess: the description is under 200 characters and starts with the category noun, topics
number 8–20 and are lowercase-hyphenated, the homepage answers 200, and reading back after the
write matches the request.
Failure: meta.topics-overflow means more than twenty topics were requested and only twenty
are stored. meta.verify means the write did not land — read the response instead of trusting
the call.
python tests/run_tests.py— does the pack itself work.python tools/ghagent.py verify-install --profile <profile>— is it the right copy.python tools/ghagent.py doc --root . --json— what exactly is wrong, with file and line.- Only then edit files. Editing by feel restores the same defects.