Skip to content

Latest commit

 

History

History
148 lines (117 loc) · 8.38 KB

MIGRATION.md

File metadata and controls

148 lines (117 loc) · 8.38 KB

Migration from 1.1.0 to 1.2.0

1.2.1 note. Behaviour did not change. The PyPI distribution is now github-agent-cli, because github-agent and ghagent are taken on PyPI by unrelated projects. The console script is still ghagent and ghagent --version still prints github-agent X.Y.Z; if you installed the wheel manually, replace pip install github-agent with pip install github-agent-cli. Everything below applies unchanged. This guide is for the owner of a repository that uses github-agent — either as a CLI, as a pack installed into an agent skill root, or as a checking step in CI. It records what moved, what changed meaning, and what needs an action. Version 1.2.0 does not break the 1.1.0 workflow: the commands, flags, exit codes and file contracts are the same, so most repositories have nothing to migrate.

At a glance

Area 1.1.0 1.2.0
Install clone the repository, run python tools/ghagent.py uv tool install github-agent-cli, pipx install github-agent-cli or pip install github-agent-cli; console script ghagent
Source tree the only way to run unchanged: python tools/ghagent.py <command> still works and is what the pack's own docs use
Pack installation install --profile … --write from a clone unchanged, still from a clone; the wheel ships the CLI only and refuses install/selftest with exit 2
Rule catalogue inside a 296-line AGENTS.md AGENTS.md is a map under 120 lines; the catalogue is docs/RULES.md
Wiki workflow split between AGENTS.md and docs/PROCEDURES.md docs/WIKI.md
Modules, exit codes, tests AGENTS.md docs/ARCHITECTURE.md
Packaging and release not documented docs/PACKAGING.md, pyproject.toml, action.yml, Dockerfile, .pre-commit-hooks.yaml
Long-form rules AGENTS.md docs/RULES.md; docs/IMPORT.md and docs/PROCEDURES.md stay and are linked from the map
AGENTS.md length no limit new rule agents.md-length warns above 120 lines
README internals first installation first; the badge block names the CI workflow, the supported Python range, the licence, the runtime dependency count and the self-test count
Version source tools/ghalib/util.py unchanged — PACK_VERSION in tools/ghalib/util.py is the only place the number lives

Step by step

1. Update the tool

CLI only:

uv tool install --upgrade github-agent     # or: pipx upgrade github-agent
pip install --upgrade github-agent         # pip into the active environment
ghagent --version                          # must print: github-agent 1.3.0

From a clone, for the pack:

git -C <checkout> pull
python tools/ghagent.py selftest            # must print PASS

The clone is not optional for the pack commands: install, verify-install, uninstall, snippet and selftest copy or test files that a wheel does not contain, so in a wheel installation they exit 2 with a message that names the missing tree. That is the intended behaviour, not a broken install.

2. Refresh an installed pack

If the pack lives in an agent skill root, reinstall and verify it:

python tools/ghagent.py install --profile harness --write     # or --profile autoclaw
python tools/ghagent.py verify-install --profile harness

install overwrites the copied files and rewrites .install.json; the manifest now records version 1.2.0, so a stale copy is visible instead of silently trusted. Profile paths and --target are unchanged — see docs/IMPORT.md.

3. Read the new map, not the old monolith

AGENTS.md now answers "what do I run and what must I not break" and links to the detail. If you kept a local copy of the old AGENTS.md in your own rules, replace the copy; the rules themselves did not change, they moved:

You looked for In 1.1.0 In 1.2.0
Rule ids and file contracts AGENTS.md docs/RULES.md
Platform traps (15 rows) AGENTS.md docs/RULES.md
Wiki manifest, sidebar, footer, publication AGENTS.md, docs/PROCEDURES.md docs/WIKI.md
Module list, exit codes, test doctrine AGENTS.md docs/ARCHITECTURE.md
Import into AutoClaw2, HARNESS, SagaAI docs/IMPORT.md docs/IMPORT.md (unchanged)
Recurring jobs with success criteria docs/PROCEDURES.md docs/PROCEDURES.md (unchanged)
Packaging, release, pre-commit, Action not documented docs/PACKAGING.md

4. Expect one new warning

ghagent doc --root . now runs agents.md-length: an AGENTS.md longer than 120 lines is reported as a warning, not an error, and the exit code stays 0. The limit applies to the root AGENTS.md of the examined tree only — AGENTS.ru.md and nested copies are not counted. The fix is not to delete content: keep the map (purpose, install, one command per job, the non-negotiable rules, the verification block, links) and move the detail into docs/, as this repository now does. A silent --ignore agents.md-length is allowed, but then the file is not a map and the person paying for it is the agent that reads it on every request.

5. Re-read the README contract before copying the new README

The README is now installation-first: package managers, optional PNG support, clone, Docker, pre-commit and CI come before the internals, and the link bar points at MIGRATION.md and docs/PACKAGING.md. The badge block changed with it: CI, the supported Python range, the licence, the runtime dependency count and the self-test count are named there. The audit contract did not move: 3–8 badges, one H1, a summary paragraph directly after it, installation, usage and licence sections, a language tag on every fence. Copying the sections is fine; copying the numbers is not, unless you measured them in your own repository.

6. Verify

ghagent selftest            # clone only
ghagent doc --root .
ghagent audit .
ghagent changelog check
ghagent assets check
ghagent privacy --root .

All six must exit 0. 1 means error-level findings printed with file:line; 2 means a wrong path or a command that needs the source tree.

Nothing you must change

If you only run github-agent against your own repository and did not install the pack:

  • No file in your repository becomes required. No new mandatory document, no new .ghagent.json field. The configuration file is still optional and its keys are unchanged.
  • No command is renamed or removed. audit, doc, privacy, assets, wiki, changelog, meta, install, verify-install, uninstall, snippet, report and selftest keep their flags and exit codes 0/1/2.
  • No new dependency appears. Python 3.11+ and the standard library are still enough; Pillow remains an optional extra for PNG output.
  • The wiki, changelog and README contracts are unchanged. The rules moved in this repository's documentation, not in the checker.
  • agents.md-length is a warning. A long AGENTS.md in your repository lowers nothing except the quality of your own map; it does not fail the build.

The two changes that do ask for an action are choices, not requirements: reinstall the pack if you want the new manifest version, and shorten AGENTS.md if you want to pay less context per agent request.

Troubleshooting

Symptom Cause Action
selftest exits 2 right after pip install github-agent-cli the wheel ships the CLI only clone the repository and run python tools/ghagent.py selftest from the clone
install exits 2 with "needs the source tree" same run install from a clone, not from the wheel
agents.md-length warns after upgrading the file is over 120 lines move detail into docs/ and link it from the map
ghagent --version prints 1.1.0 after an upgrade an older copy is first in PATH, or a virtual environment is active reinstall in the environment that provides ghagent; check pip list
a pre-commit hook cannot find ghagent the hook builds its own environment pin the hook repository to rev: v1.3.0; no global install is needed

Related: the rule catalogue is in docs/RULES.md, the packaging detail is in docs/PACKAGING.md, and the release history is in CHANGELOG.md.