[robertodr]

🤖 AI text below 🤖

Stacked on #28 (docs/adoption-baseline); review only its own commits. Rebase onto main once the PRs below it are merged.

Summary

An agent skill for repository admins adopting release-tools: skills/adopt-release-tools/. It inspects the repository and GitHub read-only, plans with the admin, writes the adoption PR (stubs, publish workflow, just changelog, PR template, CHANGELOG.md with the earlier releases, Dependabot), and prepares every command that changes GitHub for the admin to run: no heredocs or placeholders in them, JSON payloads as files, the bot credentials extended one repository at a time. It reads the docs and stubs from a clone of the latest release (or a tag the admin names, e.g. a release candidate for a pilot), so it never carries its own copy. Installed with npx skills add Algorithmiq/release-tools --skill adopt-release-tools; documented in docs/adopting.md. tests/test_skill.py checks its frontmatter, the major version it is written for, that every release-tools path and heading it reads exists, and that it stops for the admin and hands over only literal commands. Tested with dry runs on internal repositories (not named here), with and without the skill.

Adversarial review across model tiers

The skill was stress-tested for executors weaker than the one that wrote it: Claude Haiku 5.5 and Sonnet 5.5 and GPT-5.6 (Luna, Terra, Sol), from no thinking to high. Each took a 22-question quiz on its decision points (graded against a hidden key), ran it on paper against a hostile CodeArtifact fixture, or reviewed it for clarity and consistency with the docs. The core safety rules held on every model; the failures were where the text left a choice open, and the GPT models answered those with full confidence instead of asking.

What changed in the skill:

• Authority: an explicit list of what the agent runs; it never opens issues or PRs on release-tools (both GPT quiz takers would have); never creates a tag, local or pushed.
• Waits: a fixed phase-2 message ending in "reply Plan approved", and Stop points in phases 2, 4, 5 and 6; a command that needs an unanswered value is not handed over but listed under Waiting for; one worked example of a handed-over command.
• CodeArtifact: phase 1 reads the organisation variables' values; an inlined value that differs is a question before phase 3, since the packages would move. With the variables missing, the skill asks an owner which values the organisation uses, then hands over step 5's commands with the answers.
• Workflows: jobs that ship something for the tag move into the publish workflow; the rest keep their other triggers, with push: tags in place of release; a build that also runs on PRs is copied; the admin decides whether moved workflows run for pre-release tags.
• Gaps: stub names already taken, integration_id of carried-over checks, querying only the index the repository publishes to, keeping hand-written changelog notes, local release.py/cliff.toml, re-runs on an open adoption PR.

Docs fixed alongside (the skill no longer works around them):

• docs/repository-setup.md, step 1: adds the repository to the bot's variable and secret by id, not with --repos, which replaces each list.
• Step 8: finds every ruleset of main through rules/branches/main, whatever its name, and adds the PR checks, a required_status_checks rule and the bot's bypass only where missing, so a second run changes nothing. Checked against the API on a scratch repository; tests/test_repository_setup.py runs its jq.
• docs/adopting.md: a VERSION file kept in step with the tags next to setuptools-scm goes in version-files.

Edits were re-checked by rerunning the quiz and the CodeArtifact dry run on GPT-5.6 Luna and Claude Haiku 5.5 at low thinking until they converged.

Checklist

• Bug fix for the current release: add the backport label (or ask a maintainer to)
• just lint and just test pass
• docs/adopting.md, docs/organisation-setup.md, and docs/repository-setup.md updated if the stubs, inputs or setup changed
• Breaking change or deprecation: the Migration section says what consumers must change