diff --git a/AGENTS.md b/AGENTS.md index 12134fa9..433928db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,7 +80,7 @@ pnpm exec knip # unused code/dependency check (CI's - Each package under `packages/` is published independently with its own semver. Merging a changeset (`pnpm changeset`) to `main` makes `changesets/action` open/update a `chore: update changelog and release` PR; merging that PR bumps the affected packages' versions, regenerates their CHANGELOGs (via `.changeset/generator.ts`), and publishes to npm. Any other push to `main` touching `packages/` also publishes an `@next` snapshot (`pnpm run publish:snapshot` → `scripts/publish-snapshot.mjs`, run by the `snapshot` job). That script wraps `changeset publish` in `scripts/run-with-retry.mjs`, retrying up to 3 times (20s apart) because `changeset publish` fires one concurrent OIDC token exchange per package and npm intermittently 404s a subset instead of rate-limiting; already-published versions are skipped on retry. `pnpm run publish` (the tagged-release path, invoked by `changesets/action` via `release.yml`) does not use this retry wrapper yet. - `pkg.pr.new` continuous preview releases (`.github/workflows/pkg-pr-new.yml`): every push to any branch builds the packages and publishes preview tarballs via `pnpm exec pkg-pr-new publish`, so unreleased changes from any branch/PR can be installed directly without waiting for a real release. - `.github/workflows/pullfrog.yml` runs an AI coding agent (the Pullfrog Action) on `workflow_dispatch` with a `prompt` input, used for scheduled/manual maintenance tasks. `.github/workflows/renovate-changeset.yml` adds the changeset for Renovate dependency PRs touching `packages/**`. -- CI runs on GitHub-hosted runners (`ubuntu-24.04-arm` for `ci.yml` and `pkg-pr-new.yml`, `ubuntu-latest` for `release.yml`) — not Blacksmith, despite some now-superseded PR history. +- CI runs on GitHub-hosted runners (`ubuntu-26.04-arm` for `ci.yml` and `pkg-pr-new.yml`, `ubuntu-latest` for `release.yml`) — not Blacksmith, despite some now-superseded PR history. - Adding a new package: add a matching `packages:` entry to **both** `.github/labels.yml` (label sync) and `.github/labeler.yml` (path-based auto-labeling on PRs) — these can drift independently (e.g. `plugin-subcommands-advanced` currently has no `labeler.yml` path mapping, and its `labels.yml` entry is misspelled `packages:plugins-subcommands-advanced`, so it's never auto-applied) — add its name to the `scopes` list of `semantic-pull-requests.yml`, and append its `tsconfig.consumption.json` (if any) to the root `typecheck` script. - `tests/http-framework-peer-range.test.ts` (part of `pnpm test`, so the CI `unit` job) fails when any non-private package's `peerDependencies["@wolfstar/http-framework"]` excludes the framework version the workspace installs (its devDependency, kept on the latest release by Renovate), when a package declaring that peer doesn't also devDepend on it, or when the packages' peer ranges accept different majors (a package whose range starts at a later major, like `plugin-scheduled-tasks`' `^6.1.0`, only has to match from that major up). When Renovate bumps the framework to a new major, widen **every** plugin's peer range (`^x || ^.0.0`) in the same PR **and** add a patch changeset per package — a peer-range change on `main` isn't published without one (that is how `plugin-api`/`plugin-logger`/`plugin-subcommands-advanced` shipped `^3`-only peers to npm after the v5 bump, #121). - Non-trivial structural work (cross-package parity ports, manager/API redesigns, new plugin scaffolding) gets a design doc under `docs/superpowers/` before implementation: a plan at `docs/superpowers/plans/-.md` and, for anything with real design decisions, a matching spec at `docs/superpowers/specs/--design.md` (e.g. `docs/superpowers/specs/2026-10-05-message-types-parity-design.md`). PR descriptions for such changes link the spec/plan instead of re-explaining the design. Check this directory for prior art before redesigning an area that already has one.