Skip to content

Procedures

Six jobs that repeat in every repository. For each: when it runs, which commands, what counts as success, and what a failure means.

1. Auditing a repository

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.md

Success: 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.

2. README, AGENTS.md and images

When: a new project, or the README stopped answering "how do I run this".

  1. Start from reference/readme-template.md and reference/agents-template.md.
  2. Fill in facts: commands, paths, versions, numbers with a source.
  3. Render the banner: python tools/ghagent.py assets render --write, then place the image above the first section and run assets check.
  4. 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.

3. Releasing a version

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.0

Success: 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.

4. The wiki

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               # publish

The 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.

5. Images

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 --title "Project" --tagline "What it does." --command "project --help" --write
python tools/ghagent.py assets check

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.

6. Metadata and publication

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 --http

Success: 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.

When everything is broken

  1. python tests/run_tests.py — does the pack itself work.
  2. python tools/ghagent.py verify-install --profile <profile> — is it the right copy.
  3. python tools/ghagent.py doc --root . --json — what exactly is wrong, with file and line.
  4. Only then edit files. Editing by feel restores the same defects.