[goosewobbler]

Description

Brings over webdriverio/desktop-mobile#725, adapted to releasekit: AGENTS.md should hold only what an agent can't work out from the repo, and the contributor docs should stop contradicting package.json.

AGENTS.md is loaded into every agent session, so each line has to be something an agent would get wrong otherwise, can't find in package.json or config, and won't go stale. That rules out pinned tool versions. Conventions a linter can enforce are enforced instead: braces by #679, any by #682.

AGENTS.md

The architecture invariants stay as they are. Three sections are added, every claim checked on this repo:

• Commands:
  • Before pushing: pnpm lint, pnpm typecheck and pnpm test. The commit hook only checks staged files, and there's no pre-push hook. pnpm test skips @releasekit/version's own test/integration/, so that suite's command is named.
  • pnpm --filter <pkg> test skips Turborepo, so it can run against a stale dist/ in a dependency; build the dependencies first with pnpm turbo run build --filter=<pkg>^....
  • A package's own lint script runs Biome only.
  • Suites that run in CI but not in pnpm test, and when to run them.
• Gotchas:
  • Turborepo's strict env mode drops undeclared variables, so RELEASEKIT_NOTES_E2E=1 pnpm test silently skips the LLM e2e test; it only works through pnpm --filter.
  • When Vitest detects a coding agent it hides console output and passing tests; --reporter=default brings them back.
  • In a worktree under .claude/, pnpm lint finds no files and fails.
• Code conventions the linters don't check:
  • Test through the path a user hits.
  • A short rule on comments.

Trimmed after review: Turborepo's --force (general Turborepo knowledge), a "check just your files" lint tip, the script-by-script CI list (it's in package.json), the #654 known-failure link (stale once fixed), "avoid any" (now #682), and the Vitest major version.

CLAUDE.md removed

CLAUDE.md only imported AGENTS.md, and Claude Code reads AGENTS.md itself when there's no CLAUDE.md (from v2.1.277).

claude.yml pins anthropics/claude-code-action, which installs a Claude Code release past that. On PRs, the action restores CLAUDE.md from the base branch but not AGENTS.md, so the AGENTS.md content Claude sees comes from the PR head either way — removing CLAUDE.md doesn't change what a PR can inject. Nothing else in the repo refers to CLAUDE.md. (The action's prompt still says "follow the repository's CLAUDE.md"; with the file gone it relies on AGENTS.md being auto-loaded.)

Contributor docs that had drifted

• CONTRIBUTING.md:
  • It asked for Node ≥18 and npm install -g pnpm. It now asks for Node 22.12 or later (engines, since chore(deps): update package versions and lockfile #681) and pnpm 12 (packageManager, since chore(deps): update package versions and lockfile #681), and links pnpm's installation page.
  • It said linting uses "no Prettier or ESLint", but pnpm lint and the commit hook both run ESLint.
  • It said pnpm --filter @releasekit/version build builds the package's dependencies. It doesn't, so the example now uses pnpm turbo run build --filter=....
  • It linked BOOTSTRAP.md, removed in 2f5ef87.
  • Its package-layout tree didn't match forge and git; removed, as version: jsonOutput's disabled-mode guards are untested, and a test asserts the opposite of its title #725 did with its trees.
  • The commit-scope list was missing release.
• PR template: added @releasekit/release to Scope.
• Bug report: the Node version placeholder said 20.11.0, below the supported range.

Left as they were:

• README.md: no structure tree, and pnpm install && pnpm build && pnpm test works.
• The test commands in CONTRIBUTING and the PR template still say pnpm test: unlike desktop-mobile, here it doesn't run E2E — it runs the unit tests plus test/integration/, in about a minute.

Not carried over from #725: the README/setup trees and Agent OS/Corepack/Rust notes (none exist here); a "don't edit CHANGELOG.md" rule (per-package changelogs stopped at 0.20.0, so it would be false); a generated-files gotcha (#598 moved that into file banners and CI checks); "avoid null"/"use Result" rules (not verifiable here). Nothing on coverage, console or barrel files — those are enforced by #670, #668 and #669.

Found but left for separate changes: consumer docs still say Node 20+ while engines needs 22.12 (docs/action.md, packages/release/docs/ci-setup.md, and the notes, publish and release READMEs); the root version-output.json is a committed leftover from 0.2.0-next.12.

Related Issue(s)

Mirrors webdriverio/desktop-mobile#725. Pairs with #682.

Type of Change

• feat — New feature
• fix — Bug fix
• docs — Documentation change
• refactor — Code refactoring
• test — Adding or updating tests
• chore — Maintenance, dependencies, tooling
• Breaking change — Requires major version bump

Scope

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/config
• @releasekit/core
• CI / workflows
• Root / monorepo

Checklist

• Lint passes (pnpm lint)
• Tests pass (pnpm test)
• Typecheck passes (pnpm typecheck)
• Documentation updated (if applicable)
• Breaking changes noted in description (none)

Testing Notes

Docs only; every documented command was run:

• pnpm lint passes (the 29 warnings already on main). pnpm test passes 16/16 tasks, including @releasekit/integration-tests.
• pnpm turbo run build --filter='@releasekit/release^...' builds exactly the 7 dependencies.
• The CI-only suites pass locally: pnpm test:action:preview, pnpm test:action:release, pnpm test:harness:backfill, pnpm test:harness:multi, pnpm test:harness:multi-npm-disabled, pnpm exec tsx scripts/test-e2e.ts, pnpm exec tsx scripts/test-packages.ts.
• Strict env, with Ollama pointed at a dead port: RELEASEKIT_NOTES_E2E=1 pnpm turbo run test --filter=@releasekit/notes skipped both e2e tests; RELEASEKIT_NOTES_E2E=1 pnpm --filter @releasekit/notes test ran them and they failed on the connection, so the variable got through.
• Vitest reporter: run directly, a spec's console.log and ✓ lines were hidden and --reporter=default showed them; through Turborepo they showed anyway. std-env treats AI_AGENT, CLAUDECODE or CLAUDE_CODE as an agent, so unsetting CLAUDECODE alone isn't enough.
• .claude/ worktree: in a throwaway worktree under .claude/, biome check . reported "No files were processed" and exited 1.
• After merging chore(deps): update package versions and lockfile #681 (Biome 2.6, pnpm 12): the lint script, lint-staged config and .claude ignore are unchanged, so the AGENTS.md claims still hold.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HQN3v9Z4f1mu3xK4Z7K44e

[github-actions]

Standing release PR: #614 · v0.42.0 queued (4 packages) · open 82d 1h 38m · ✅ ready to merge

Release Preview — v0.41.2 → v0.41.3

Note: Labels on this PR are advisory in standing-pr mode. Bumps come from conventional commits in the standing PR; override by editing labels on the standing PR itself. Add release:immediate to bypass the standing PR and release this PR directly.

These changes will be added to the release PR (#614) when merged:

Changelog

monorepo 0.41.2 → 0.41.3

Changed

• drop the Vitest version from the reporter gotcha (agents)
• make noExplicitAny an error outside specs and mocks (biome) (PR #682)
• trim commands to what an agent can't infer; drop the any rule (agents)
• require pnpm 12 and drop the .nvmrc aside (contributing)
• drop the braces rule now that Biome enforces it (agents) (PR #679)
• say which suites pnpm test skips (agents)
• point the braces rule at #666 (agents)
• add commands and gotchas to AGENTS.md, and drop CLAUDE.md

All packages → 0.41.3 (sync versioning)

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/release

After merge — predicted release

No version escalation — this PR's changes will be included in the queued release without affecting the projected versions.

Package	Standing PR	This PR	After merge
monorepo	0.42.0	0.41.3	0.42.0

---

Updated automatically by ReleaseKit