| name | modernize-repo |
| description | Bring one repo fully current: settings baseline, a release that publishes without long-lived tokens, dependency PRs that merge themselves, and proof it all works. Use this skill when asked to 'modernize this repo', 'bring it up to standard', 'fix everything about this repo', or after a sweep flags a repo as broken. |
Modernize Repo
Orchestrates the other skills into one pass over a single repository, in the order their dependencies require. Diagnose first; each phase gates the next.
When to use
- A repo predates the current conventions and should match the others
- A release-health sweep flagged the repo and it needs end-to-end repair
- Handing one repo to an agent to bring current without further instruction
Not for: sweeping many repos (do that first, then run this per repo), or authoring reusable workflow content in the owner's .github.
Phases
Run in order. Each phase's failures make the next phase's diagnosis ambiguous, so do not parallelize.
1. Establish what is broken
Never start by applying config. A verify failure masks a missing secret behind it, so a repo can look like one class and be another.
gh repo view <o>/<r> --json isFork,isArchived,visibility,pushedAt
gh run list --repo <o>/<r> --limit 5
gh secret list --repo <o>/<r>
Record the failing job's name and duration before reading any log — they identify the class faster. Then decide whether the repo is worth the work at all:
gh api repos/<o>/<r>/contents/package.json --jq .content | base64 -d | jq '{name, private, workspaces}'
npm view <pkg> version
A private root whose workspace packages are all private: true publishes nothing; a red release there may not be worth fixing. Say so and stop rather than repairing a pipeline with no output.
2. Decide the repo's home
A user-owned repo has neither org-level secrets nor a merge queue. If the repo publishes and the owner has a suitable org, transferring removes the root cause instead of routing around it — but it is a one-way door and the target is the user's call, never the agent's.
Transfer before the later phases, not after: trusted publishing pins owner/repo and silently stops matching.
3. Settings baseline
Invoke apply-repo-baseline. Check mode first, apply after showing the diff.
Two couplings matter for what follows: a repo whose release uses OIDC needs default_workflow_permissions: write, and strict_required_status_checks_policy must be false if a merge queue is coming.
GitHub Projects is off by default (has_projects: false in assets/repo-settings.json). Issues are where the work is tracked; a repo-level Projects tab nobody curates is one more stale surface. Turn it back on only when the repo actually runs a board, and say so. This toggle only governs the repo's own Projects tab — org- or user-level Projects (v2) linked to the repo are unaffected, so disabling it does not orphan an existing board.
The About panel is part of the same phase: where the repo has Pages and no deliberate homepage, point homepage at the Pages URL. The Include in the home page → Packages checkbox has no API at all, so it ends up in the report as a manual step rather than something this pass can do or verify. Both are in the baseline's § About panel.
4. Package manager — convert to pnpm
pnpm is the standard, and yarn or npm is a legacy state to migrate, not a property to preserve.
Convert whenever possible; defer only for a concrete blocker, and name it. "It currently works" is
not one. Leave bun alone where a repo already uses it — both its verify and its OIDC release
workflow exist, so it is a supported destination.
This cannot be a separate PR from the release pipeline below. Changing package manager breaks a
yarn-* release workflow, so release.yml moves in the same commit or publishing breaks — and
since the release is moving anyway, migrate it to changesets in the same pass
(setup-secretless-release). The two conversions are cheaper together than apart.
For a repo bound for cyberuni this is a precondition rather than a preference: the org carries
no yarn-* workflows at all, so there is nothing for either job to call.
pnpm's strict, non-hoisted node_modules stops masking whatever the repo was resolving by accident.
Everything below is a pre-existing bug surfacing, not a regression you introduced — say so in the
PR, or the diff reads as gratuitous churn:
| symptom | cause | fix |
|---|
TS2307: Cannot find module 'assert' / 'events' | dep undeclared; yarn was hoisting it in | declare @types/node |
TS2318: Cannot find global type 'Array' | an explicit lib replaces the default set, so lib: ["DOM"] alone loads no ES lib | set each config's lib to match its own target |
TS2339 on a method a dependency adds | module augmentation — see below | declare the members on the subclass |
TS1005 / TS1109 inside a dependency's .d.ts | its syntax is newer than your TypeScript | pin that dependency. skipLibCheck skips type checking, not parsing, and does not help |
depcheck says a dep is unused | bin-only in scripts, or referenced only by a config file | add to .depcheckrc.yml, one package per line |
| a devDependency missing only in CI | lost while rewriting package.json | diff the old and new dependency lists explicitly |
Those first two are usually the same accident: the hoisted @types/node is often where the ES lib
was quietly coming from, so fixing one exposes the other.
A dependency that ships a module augmentation stops augmenting. Where a package augments
another package from inside its own directory, pnpm resolves that specifier to its own copy — a
different module identity than the @types/* your repo sees — so the augmentation never merges.
Re-declaring it in typings/ makes it worse: anchored there it becomes an ambient declaration
that shadows the module instead of merging into it, and a class can no longer extend it at all
(TS2689). Declare the members on the subclass, in the file that uses them.
Native postinstalls and the lockfile soak are covered in modernize-toolchain; both apply here
too. Prove the result with pnpm install --frozen-lockfile before opening the PR.
Skipping the packages/<name> layout move avoids the .gitignore anchoring trap entirely — /cjs
and /esm stop matching under a subdirectory, leaving build output untracked but not ignored.
5. Release pipeline
Invoke setup-secretless-release. It covers the OIDC migration, the semantic-release → changesets
migration, trusted-publisher registration, the one-time version-PR approval, and merge queue setup.
changesets is the standard, so a repo still on semantic-release migrates here rather than
staying. Combine it with the phase above where both apply — the release workflow has to move anyway.
Do not proceed until a release has actually published — a green run is not proof:
npm view <pkg> version
6. Legacy CI layout, if present
A repo still on a single nodejs.yml (calling typescript-build / typescript-test / npm-release) predates the pull-request.yml + release.yml split and will not satisfy a code / all-checks required context.
Decide before migrating: archive the repo, delete the workflow, or migrate. Do not sink effort into a pipeline for a package nobody consumes.
7. Toolchain, build, tests and dependencies
Invoke modernize-toolchain. It is a whole phase, not a bump pass.
Do the toolchain swap before the version bumps. Most of an old repo's outdated list is deleted
by the swap, and the deleted ones are the expensive upgrades. On color-map, 11 of 18 outdated
packages were removed rather than upgraded. Bumping first throws that work away.
Do not split dependencies, toolchain and build into separate missions — the split is what creates
the wasted bumps.
8. Dependency automation
One updater and one merge mechanism. A third-party bot's direct merge action bypasses a merge queue rather than feeding it, so retire those rules where a queue exists and let Renovate's platformAutomerge and Dependabot's gh pr merge --auto enqueue natively.
Majors stay manual; they break builds in ways CI catches but humans should choose to absorb.
9. Prove it
Claiming done without evidence is the failure mode this whole pass exists to remove.
What decides the release depends on the tool, and the answer changed with the merge baseline.
On changesets — the destination for every repo here — the changeset file decides, and the PR
title publishes nothing. So the failure mode is omission: a PR that changes the published package
with no changeset produces a green release run that publishes nothing, and npm view <pkg> version never moves. That is the quiet way a "finished" repo fails its own proof below.
On a repo not yet migrated, commit messages decide. Under the merge-commit baseline that is
worse than it used to be: every branch commit reaches main and gets analyzed, so a stray feat:
in a WIP commit cuts an unintended release. It is one more reason to migrate before proving.
Either way, pick against what the published artifact does, not how much work the PR was:
| The PR... | Bump | semantic-release type |
|---|
| adds public API | minor | feat: |
| changes what ships, without new API — a rebuild, different emitted output | patch | fix: |
| changes only repo-internal things — repo layout, test runner, CI | no changeset | refactor: / chore: / ci: |
Two toolchain PRs on color-map were titled feat: and each cut a minor while adding no API. No
semver contract broke — a minor is a safe superset of a patch — but the changelog now advertises
features that do not exist.
| Claim | Proof |
|---|
| Publishes | npm view <pkg> version shows the new version |
| Secretless | gh secret list shows no NPM_TOKEN / CI_GITHUB_TOKEN, and a release has published since |
| Provenance | npm view <pkg>@<v> dist.attestations |
| Installable | install the published tarball and exercise the public API |
| Queue serializes | two trivial PRs; the second's gh-readonly-queue/main/pr-<N>-<sha> base is the first's merge commit |
Delete any temporary validation artifacts in the same pass.
What NOT to do
- Do not apply settings before diagnosing; you will fix the wrong class and mask the real one.
- Do not transfer a repo after registering trusted publishing — the config pins
owner/repo.
- Do not fabricate a required status check to get a checkless PR through.
- Do not treat a green release run as proof of publication.
- Do not repair pipelines for repos that publish nothing without saying so first.
- Do not run this across many repos at once; sweep first, then per repo.
- Do not leave a repo on yarn or semantic-release because it currently works. Both are legacy states; migrate, or name the blocker that stopped you.
- Do not convert a bun repo to pnpm as part of this pass. bun has both a verify and an OIDC release workflow, so it is a supported destination — that is a separate decision.
- Do not land a package-manager change and its release-workflow change in separate PRs. The old release workflow breaks the moment the lockfile does.
References
- apply-repo-baseline — settings, rulesets, Actions token, file layout
- modernize-toolchain — the build/lint/test/dependency swap phase 7 delegates to
- setup-secretless-release — OIDC migration, trusted publishers, merge queue; its
references/failure-catalogue.md carries the diagnostic signatures for phase 1
- setup-changesets — if the repo has no changesets setup yet
- verification-before-done — the evidence bar phase 9 applies
