Move release guidance to repo agents file

[leoisadev1]

Summary

• Add repo-root AGENTS.md as the single local place for SDK/CLI release guidance.
• Remove extra release markdown docs and the repo skill markdown.
• Keep the actual release automation intact.

Validation

• git diff --check

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	May 30, 2026 12:17am

[greptile-apps]

Greptile Summary

This PR consolidates all SDK/CLI release guidance into a new AGENTS.md at the repo root, removing five scattered markdown files (docs/release/release-process.md, docs/release/major-version-agent-prompt.md, docs/release/migrations/README.md, skills/email-sdk/SKILL.md, and .changeset/README.md). No automation or code is touched.

• AGENTS.md accurately captures the day-to-day release workflow (changesets, bump selection, bun run release:ci, major-version gate, CI/publishing constraints) and the .changeset/README.md content is fully preserved.
• skills/email-sdk/SKILL.md contained adapter security rules, integration patterns, and a review checklist that are not carried over to AGENTS.md — this guidance is now absent from the repo.
• docs/release/major-version-agent-prompt.md held a structured agent runbook (task list + "do not publish/push" guards) for major-version reviews; AGENTS.md replaces it with two sentences, leaving agents with less structured guidance for that scenario.

Confidence Score: 4/5

Documentation-only change with no code or automation modifications; safe to merge, but some guidance content is dropped without a replacement location.

The core release workflow is accurately captured in AGENTS.md and no automation is touched. The concern is that the deleted SKILL.md carried adapter security rules and a review checklist that do not appear anywhere in the new file, and the major-version agent prompt is reduced to two sentences with no structured task list or do-not-publish safeguards. These are guidance gaps rather than broken functionality, but they could affect how a future agent handles a major release or SDK integration review.

skills/email-sdk/SKILL.md (deleted) and docs/release/major-version-agent-prompt.md (deleted) are worth a second look to confirm their non-release content is intentionally dropped or lives elsewhere.

Important Files Changed

Filename	Overview
AGENTS.md	New file consolidating release workflow guidance; migration note scoping to PR-only (not committed files) is a discoverability concern
skills/email-sdk/SKILL.md	Deleted; contained adapter security rules, integration patterns, and a review checklist that are not replicated in AGENTS.md
docs/release/release-process.md	Deleted; core release workflow is preserved in AGENTS.md, but one-time setup steps, Homebrew upgrade instructions, and Depot CLI commands are not
docs/release/major-version-agent-prompt.md	Deleted; structured agent prompt with explicit task list and guard rules for major-version reviews has no equivalent in AGENTS.md
docs/release/migrations/README.md	Deleted; per-version migration file convention (v1.md, v2.md…) is no longer defined anywhere in the repo
.changeset/README.md	Deleted; content fully and accurately preserved in the new AGENTS.md

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer makes SDK/CLI change] --> B[bun run changeset]
    B --> C[Commit .changeset/*.md with code PR]
    C --> D[Merge feature PR to main]
    D --> E{Pending changesets on main?}
    E -- Yes --> F[CI opens 'Version packages' PR]
    E -- No --> G[Wait for more changesets]
    F --> H{Major version?}
    H -- Yes --> I[Migration notes documented in PR?]
    I -- No --> J[Do NOT merge]
    I -- Yes --> K[Merge 'Version packages' PR]
    H -- No --> K
    K --> L[Bump version + update changelog]
    L --> M[Publish to npm via GitHub-hosted runner]
    M --> N[Create GitHub release/tag]

Loading

Comments Outside Diff (2)

1. skills/email-sdk/SKILL.md

   SDK integration/security guidance not preserved in AGENTS.md

   SKILL.md contained guidance that goes beyond release workflow — specifically adapter security rules ("Never log API keys, SMTP passwords, raw tokens, full message bodies"), adapter integration patterns (import paths, SMTP STARTTLS behaviour, allowInsecureAuth warning), and a review checklist (idempotency keys, provider error surfacing, field-mapping completeness). None of this appears in AGENTS.md.

   The PR description scopes the removal to "release guidance," but this security/integration content is substantively different from release mechanics. If there is another location where this guidance now lives (e.g. a global skill or internal wiki), that would resolve the concern — but as-is it is gone from the repo.

   Confidence this is an issue: 3/5

   

2. docs/release/major-version-agent-prompt.md

   Structured major-version review prompt removed with no replacement

   The deleted file contained a ready-to-use agent prompt with an explicit task list (inspect diff, check migration docs, add before/after examples, run validation commands) and hard rules ("do not publish", "do not push", "keep public upstream repos read-only"). AGENTS.md replaces this with two sentences. An agent asked to prepare a major release now has no structured runbook to follow — the risk is skipping validation steps or accidentally attempting to publish.

   If the intent is to keep that structured prompt somewhere, consider embedding it in AGENTS.md under a collapsible section or linking to a docs location.

   Confidence this is an issue: 2/5

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

_{Reviews (1): Last reviewed commit: "Move release guidance to repo agents fil..." | Re-trigger Greptile}

[greptile-apps]

Migration notes scoped to PR only, not committed as files

The old workflow required a committed file at docs/release/migrations/vX.md (enforced in both the SKILL.md and docs/release/migrations/README.md). This new wording — "migration notes in the PR that introduces the breaking change" — means the notes live only in the PR description, which becomes hard to discover once the PR is closed/merged.

Consider clarifying whether a committed file is still expected (e.g. in docs/release/migrations/ or inline in CHANGELOG), or explicitly note that the PR description is the intended permanent home. As written, a future maintainer or agent could easily miss migration guidance for a past major version.

Confidence this is an issue: 4/5

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!