diff --git a/.claude/commands/release.md b/.claude/commands/release.md new file mode 100644 index 00000000..695b5d81 --- /dev/null +++ b/.claude/commands/release.md @@ -0,0 +1,15 @@ +--- +description: Prepare or publish an Agent Note release with the repo-local Markdown workflow. +argument-hint: [--push|--dry-run] +--- + +# Agent Note Release + +Use the repo-local `agentnote-release` skill. + +1. Use the provided version argument, accepting `x.y.z` or `vx.y.z`. +2. For an actual release, switch to `main`, pull, and ensure unrelated dirty files are not present. +3. Normalize the version: package metadata uses `x.y.z`; the git tag is always `vx.y.z`. +4. Follow the skill's manual release steps: update package metadata, rebuild, run checks, preview with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`, commit, tag, and push only when publishing. +5. Verify the release workflow, GitHub Release, and both npm packages after pushing. +6. Report the commands run and final release status. diff --git a/.claude/skills/agentnote-release/SKILL.md b/.claude/skills/agentnote-release/SKILL.md new file mode 100644 index 00000000..9d622ca2 --- /dev/null +++ b/.claude/skills/agentnote-release/SKILL.md @@ -0,0 +1,57 @@ +--- +name: agentnote-release +description: Prepare and publish Agent Note releases with the repo-local Markdown workflow, including version bump validation, release note preview, tag creation, workflow monitoring, and npm/GitHub verification. +--- + +# Agent Note Release Workflow + +Use this skill when the task asks to release Agent Note, bump a version, cut a tag, publish npm packages, or verify a release. + +## Prepare + +1. Confirm the target version from the user request, accepting either `x.y.z` or `vx.y.z`. Use `x.y.z` for package metadata and `vx.y.z` for the git tag. +2. Switch to `main` and pull the latest changes before an actual release. +3. Check the working tree. Do not release with unrelated dirty files. +4. If the user only wants a rehearsal or passes `--dry-run`, do not edit files, commit, tag, or push; only inspect state, run safe checks when useful, and preview the release notes. + +## Release + +Follow these steps instead of relying on a release script: + +1. Update `packages/cli/package.json` to `x.y.z`. +2. Run `npm install` from the repository root so npm updates `package-lock.json` and synchronizes `packages["packages/cli"].version` to `x.y.z`. +3. Run `npm -w packages/cli run build`. +4. Run `npm -w packages/cli run typecheck`. +5. Run `npm -w packages/cli run lint`. +6. Run `npm -w packages/cli test`. +7. Preview release notes with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`. +8. Stage `packages/cli/package.json`, `package-lock.json`, and the rebuilt `packages/cli/dist/cli.js`. +9. Commit only those release files as `chore: bump version to x.y.z` with `Release note: skip`. +10. Create the annotated tag with `git tag -a vx.y.z -m vx.y.z`. +11. Push `main` and `vx.y.z` only when ready to publish. + +## Guardrails + +- Do not manually push a release tag before the package version bump commit is on `main`. +- If release notes look like an implementation log, fix commit subjects or `Release note:` bodies before tagging. +- If any step fails after a local commit or tag, inspect the repository state before retrying; do not create duplicate tags. +- Keep release plumbing commits hidden with `Release note: skip`. + +## Verify + +After pushing a release tag: + +1. Watch the release workflow until completion. +2. Verify the GitHub Release exists for `v`. +3. Verify npm publishes both `agent-note@` and `@wasabeef/agentnote@`. +4. If release notes need copy edits after publication, update the GitHub Release body directly and keep the source commit guidance for future releases. + +## Report + +End with: + +- Version released or prepared +- Commands run +- Workflow status +- GitHub Release URL +- npm package versions confirmed diff --git a/.codex/commands/release.md b/.codex/commands/release.md new file mode 100644 index 00000000..695b5d81 --- /dev/null +++ b/.codex/commands/release.md @@ -0,0 +1,15 @@ +--- +description: Prepare or publish an Agent Note release with the repo-local Markdown workflow. +argument-hint: [--push|--dry-run] +--- + +# Agent Note Release + +Use the repo-local `agentnote-release` skill. + +1. Use the provided version argument, accepting `x.y.z` or `vx.y.z`. +2. For an actual release, switch to `main`, pull, and ensure unrelated dirty files are not present. +3. Normalize the version: package metadata uses `x.y.z`; the git tag is always `vx.y.z`. +4. Follow the skill's manual release steps: update package metadata, rebuild, run checks, preview with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`, commit, tag, and push only when publishing. +5. Verify the release workflow, GitHub Release, and both npm packages after pushing. +6. Report the commands run and final release status. diff --git a/.codex/skills/agentnote-release/SKILL.md b/.codex/skills/agentnote-release/SKILL.md new file mode 100644 index 00000000..9d622ca2 --- /dev/null +++ b/.codex/skills/agentnote-release/SKILL.md @@ -0,0 +1,57 @@ +--- +name: agentnote-release +description: Prepare and publish Agent Note releases with the repo-local Markdown workflow, including version bump validation, release note preview, tag creation, workflow monitoring, and npm/GitHub verification. +--- + +# Agent Note Release Workflow + +Use this skill when the task asks to release Agent Note, bump a version, cut a tag, publish npm packages, or verify a release. + +## Prepare + +1. Confirm the target version from the user request, accepting either `x.y.z` or `vx.y.z`. Use `x.y.z` for package metadata and `vx.y.z` for the git tag. +2. Switch to `main` and pull the latest changes before an actual release. +3. Check the working tree. Do not release with unrelated dirty files. +4. If the user only wants a rehearsal or passes `--dry-run`, do not edit files, commit, tag, or push; only inspect state, run safe checks when useful, and preview the release notes. + +## Release + +Follow these steps instead of relying on a release script: + +1. Update `packages/cli/package.json` to `x.y.z`. +2. Run `npm install` from the repository root so npm updates `package-lock.json` and synchronizes `packages["packages/cli"].version` to `x.y.z`. +3. Run `npm -w packages/cli run build`. +4. Run `npm -w packages/cli run typecheck`. +5. Run `npm -w packages/cli run lint`. +6. Run `npm -w packages/cli test`. +7. Preview release notes with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`. +8. Stage `packages/cli/package.json`, `package-lock.json`, and the rebuilt `packages/cli/dist/cli.js`. +9. Commit only those release files as `chore: bump version to x.y.z` with `Release note: skip`. +10. Create the annotated tag with `git tag -a vx.y.z -m vx.y.z`. +11. Push `main` and `vx.y.z` only when ready to publish. + +## Guardrails + +- Do not manually push a release tag before the package version bump commit is on `main`. +- If release notes look like an implementation log, fix commit subjects or `Release note:` bodies before tagging. +- If any step fails after a local commit or tag, inspect the repository state before retrying; do not create duplicate tags. +- Keep release plumbing commits hidden with `Release note: skip`. + +## Verify + +After pushing a release tag: + +1. Watch the release workflow until completion. +2. Verify the GitHub Release exists for `v`. +3. Verify npm publishes both `agent-note@` and `@wasabeef/agentnote@`. +4. If release notes need copy edits after publication, update the GitHub Release body directly and keep the source commit guidance for future releases. + +## Report + +End with: + +- Version released or prepared +- Commands run +- Workflow status +- GitHub Release URL +- npm package versions confirmed diff --git a/.cursor/commands/release.md b/.cursor/commands/release.md new file mode 100644 index 00000000..695b5d81 --- /dev/null +++ b/.cursor/commands/release.md @@ -0,0 +1,15 @@ +--- +description: Prepare or publish an Agent Note release with the repo-local Markdown workflow. +argument-hint: [--push|--dry-run] +--- + +# Agent Note Release + +Use the repo-local `agentnote-release` skill. + +1. Use the provided version argument, accepting `x.y.z` or `vx.y.z`. +2. For an actual release, switch to `main`, pull, and ensure unrelated dirty files are not present. +3. Normalize the version: package metadata uses `x.y.z`; the git tag is always `vx.y.z`. +4. Follow the skill's manual release steps: update package metadata, rebuild, run checks, preview with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`, commit, tag, and push only when publishing. +5. Verify the release workflow, GitHub Release, and both npm packages after pushing. +6. Report the commands run and final release status. diff --git a/.cursor/skills/agentnote-release/SKILL.md b/.cursor/skills/agentnote-release/SKILL.md new file mode 100644 index 00000000..9d622ca2 --- /dev/null +++ b/.cursor/skills/agentnote-release/SKILL.md @@ -0,0 +1,57 @@ +--- +name: agentnote-release +description: Prepare and publish Agent Note releases with the repo-local Markdown workflow, including version bump validation, release note preview, tag creation, workflow monitoring, and npm/GitHub verification. +--- + +# Agent Note Release Workflow + +Use this skill when the task asks to release Agent Note, bump a version, cut a tag, publish npm packages, or verify a release. + +## Prepare + +1. Confirm the target version from the user request, accepting either `x.y.z` or `vx.y.z`. Use `x.y.z` for package metadata and `vx.y.z` for the git tag. +2. Switch to `main` and pull the latest changes before an actual release. +3. Check the working tree. Do not release with unrelated dirty files. +4. If the user only wants a rehearsal or passes `--dry-run`, do not edit files, commit, tag, or push; only inspect state, run safe checks when useful, and preview the release notes. + +## Release + +Follow these steps instead of relying on a release script: + +1. Update `packages/cli/package.json` to `x.y.z`. +2. Run `npm install` from the repository root so npm updates `package-lock.json` and synchronizes `packages["packages/cli"].version` to `x.y.z`. +3. Run `npm -w packages/cli run build`. +4. Run `npm -w packages/cli run typecheck`. +5. Run `npm -w packages/cli run lint`. +6. Run `npm -w packages/cli test`. +7. Preview release notes with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`. +8. Stage `packages/cli/package.json`, `package-lock.json`, and the rebuilt `packages/cli/dist/cli.js`. +9. Commit only those release files as `chore: bump version to x.y.z` with `Release note: skip`. +10. Create the annotated tag with `git tag -a vx.y.z -m vx.y.z`. +11. Push `main` and `vx.y.z` only when ready to publish. + +## Guardrails + +- Do not manually push a release tag before the package version bump commit is on `main`. +- If release notes look like an implementation log, fix commit subjects or `Release note:` bodies before tagging. +- If any step fails after a local commit or tag, inspect the repository state before retrying; do not create duplicate tags. +- Keep release plumbing commits hidden with `Release note: skip`. + +## Verify + +After pushing a release tag: + +1. Watch the release workflow until completion. +2. Verify the GitHub Release exists for `v`. +3. Verify npm publishes both `agent-note@` and `@wasabeef/agentnote@`. +4. If release notes need copy edits after publication, update the GitHub Release body directly and keep the source commit guidance for future releases. + +## Report + +End with: + +- Version released or prepared +- Commands run +- Workflow status +- GitHub Release URL +- npm package versions confirmed diff --git a/.gemini/commands/release.md b/.gemini/commands/release.md new file mode 100644 index 00000000..695b5d81 --- /dev/null +++ b/.gemini/commands/release.md @@ -0,0 +1,15 @@ +--- +description: Prepare or publish an Agent Note release with the repo-local Markdown workflow. +argument-hint: [--push|--dry-run] +--- + +# Agent Note Release + +Use the repo-local `agentnote-release` skill. + +1. Use the provided version argument, accepting `x.y.z` or `vx.y.z`. +2. For an actual release, switch to `main`, pull, and ensure unrelated dirty files are not present. +3. Normalize the version: package metadata uses `x.y.z`; the git tag is always `vx.y.z`. +4. Follow the skill's manual release steps: update package metadata, rebuild, run checks, preview with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`, commit, tag, and push only when publishing. +5. Verify the release workflow, GitHub Release, and both npm packages after pushing. +6. Report the commands run and final release status. diff --git a/.gemini/skills/agentnote-release/SKILL.md b/.gemini/skills/agentnote-release/SKILL.md new file mode 100644 index 00000000..9d622ca2 --- /dev/null +++ b/.gemini/skills/agentnote-release/SKILL.md @@ -0,0 +1,57 @@ +--- +name: agentnote-release +description: Prepare and publish Agent Note releases with the repo-local Markdown workflow, including version bump validation, release note preview, tag creation, workflow monitoring, and npm/GitHub verification. +--- + +# Agent Note Release Workflow + +Use this skill when the task asks to release Agent Note, bump a version, cut a tag, publish npm packages, or verify a release. + +## Prepare + +1. Confirm the target version from the user request, accepting either `x.y.z` or `vx.y.z`. Use `x.y.z` for package metadata and `vx.y.z` for the git tag. +2. Switch to `main` and pull the latest changes before an actual release. +3. Check the working tree. Do not release with unrelated dirty files. +4. If the user only wants a rehearsal or passes `--dry-run`, do not edit files, commit, tag, or push; only inspect state, run safe checks when useful, and preview the release notes. + +## Release + +Follow these steps instead of relying on a release script: + +1. Update `packages/cli/package.json` to `x.y.z`. +2. Run `npm install` from the repository root so npm updates `package-lock.json` and synchronizes `packages["packages/cli"].version` to `x.y.z`. +3. Run `npm -w packages/cli run build`. +4. Run `npm -w packages/cli run typecheck`. +5. Run `npm -w packages/cli run lint`. +6. Run `npm -w packages/cli test`. +7. Preview release notes with `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header`. +8. Stage `packages/cli/package.json`, `package-lock.json`, and the rebuilt `packages/cli/dist/cli.js`. +9. Commit only those release files as `chore: bump version to x.y.z` with `Release note: skip`. +10. Create the annotated tag with `git tag -a vx.y.z -m vx.y.z`. +11. Push `main` and `vx.y.z` only when ready to publish. + +## Guardrails + +- Do not manually push a release tag before the package version bump commit is on `main`. +- If release notes look like an implementation log, fix commit subjects or `Release note:` bodies before tagging. +- If any step fails after a local commit or tag, inspect the repository state before retrying; do not create duplicate tags. +- Keep release plumbing commits hidden with `Release note: skip`. + +## Verify + +After pushing a release tag: + +1. Watch the release workflow until completion. +2. Verify the GitHub Release exists for `v`. +3. Verify npm publishes both `agent-note@` and `@wasabeef/agentnote@`. +4. If release notes need copy edits after publication, update the GitHub Release body directly and keep the source commit guidance for future releases. + +## Report + +End with: + +- Version released or prepared +- Commands run +- Workflow status +- GitHub Release URL +- npm package versions confirmed diff --git a/AGENTS.md b/AGENTS.md index 9e5fc050..2647bf61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -145,7 +145,7 @@ Each `UserPromptSubmit` increments a turn counter. File changes inherit the curr - **Keep release notes human-sized.** A multi-commit PR should normally produce one clear release bullet per user-visible change, not one bullet per review fix. Put the public wording on the primary implementation commit with `Release note: `, and add `Release note: skip` to follow-up commits such as `address review findings`, `tighten fallback`, `bound window`, or generated bundle syncs unless they describe a distinct user-visible outcome. - **Write release notes as natural English sentences.** The generator capitalizes the first character as a safety net, but do not rely on that to fix awkward wording. Prefer `Release note: Codex commits made from cmux sessions are now recorded reliably.` over `Release note: recover codex env sessions`. - **PR titles should be release-summary quality.** Write PR titles as a user-facing outcome, not an implementation step. Even though GitHub Releases are generated from commits, a good PR title is the easiest review-time signal that the eventual release note will be understandable. -- **Preview release notes before merging release-sensitive PRs.** If `git-cliff --config .github/cliff.toml --latest --strip header` reads like an implementation log, rewrite commit subjects/bodies before merge or tag. Do not leave low-level cleanup commits visible just because tests pass. +- **Preview release notes before merging release-sensitive PRs.** If `git-cliff --config .github/cliff.toml --latest --strip header` reads like an implementation log, rewrite commit subjects/bodies before merge. Before tagging, use the release command below so the preview targets the next version. - **Do not rely on merge commits for release copy.** Release notes include merged PR links from `Merge pull request...` commits, but the user-facing bullets still come from implementation commits and `Release note:` lines. Version bumps and generated bundle sync commits stay hidden. - **Structural vs behavioral changes** must not be mixed in a single commit. Renames/reformats separate from feature/fix commits. - **Before committing**, all four checks must pass (run from `packages/cli/`): @@ -153,7 +153,7 @@ Each `UserPromptSubmit` increments a turn counter. File changes inherit the curr 2. `npm run typecheck` — tsc --noEmit 3. `npm run lint` — biome check 4. `npm test` — node:test (requires build first) -- **Version bumps** go in a dedicated `chore: bump version to x.y.z` commit. Tag `vx.y.z` triggers the release workflow (test → GitHub Release → npm publish). +- **Version bumps** go in a dedicated `chore: bump version to x.y.z` commit. Prefer the repo-local `agentnote-release` skill or `/release` command; `x.y.z` and `vx.y.z` inputs both create the `vx.y.z` tag. Push the tag only when ready to trigger the release workflow (test → GitHub Release → npm publish). ## Constraints diff --git a/CLAUDE.md b/CLAUDE.md index b1e32d16..b4363a07 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -145,7 +145,7 @@ Each `UserPromptSubmit` increments a turn counter. File changes inherit the curr - **Keep release notes human-sized.** A multi-commit PR should normally produce one clear release bullet per user-visible change, not one bullet per review fix. Put the public wording on the primary implementation commit with `Release note: `, and add `Release note: skip` to follow-up commits such as `address review findings`, `tighten fallback`, `bound window`, or generated bundle syncs unless they describe a distinct user-visible outcome. - **Write release notes as natural English sentences.** The generator capitalizes the first character as a safety net, but do not rely on that to fix awkward wording. Prefer `Release note: Codex commits made from cmux sessions are now recorded reliably.` over `Release note: recover codex env sessions`. - **PR titles should be release-summary quality.** Write PR titles as a user-facing outcome, not an implementation step. Even though GitHub Releases are generated from commits, a good PR title is the easiest review-time signal that the eventual release note will be understandable. -- **Preview release notes before merging release-sensitive PRs.** If `git-cliff --config .github/cliff.toml --latest --strip header` reads like an implementation log, rewrite commit subjects/bodies before merge or tag. Do not leave low-level cleanup commits visible just because tests pass. +- **Preview release notes before merging release-sensitive PRs.** If `git-cliff --config .github/cliff.toml --latest --strip header` reads like an implementation log, rewrite commit subjects/bodies before merge. Before tagging, use the release command below so the preview targets the next version. - **Do not rely on merge commits for release copy.** Release notes include merged PR links from `Merge pull request...` commits, but the user-facing bullets still come from implementation commits and `Release note:` lines. Version bumps and generated bundle sync commits stay hidden. - **Structural vs behavioral changes** must not be mixed in a single commit. Renames/reformats separate from feature/fix commits. - **Before committing**, all four checks must pass (run from `packages/cli/`): @@ -153,7 +153,7 @@ Each `UserPromptSubmit` increments a turn counter. File changes inherit the curr 2. `npm run typecheck` — tsc --noEmit 3. `npm run lint` — biome check 4. `npm test` — node:test (requires build first) -- **Version bumps** go in a dedicated `chore: bump version to x.y.z` commit. Tag `vx.y.z` triggers the release workflow (test → GitHub Release → npm publish). +- **Version bumps** go in a dedicated `chore: bump version to x.y.z` commit. Prefer the repo-local `agentnote-release` skill or `/release` command; `x.y.z` and `vx.y.z` inputs both create the `vx.y.z` tag. Push the tag only when ready to trigger the release workflow (test → GitHub Release → npm publish). ## Constraints diff --git a/docs/architecture.md b/docs/architecture.md index 5e8bf07d..132062bc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -617,20 +617,37 @@ should still be written as a clear sentence in the commit body. The canonical npm package is `agent-note`. The workflow also publishes `@wasabeef/agentnote` from the same built `dist/` as a reserved alias package, but end-user documentation should continue to point to `agent-note`. +Preferred release workflow: + +Use the repo-local `agentnote-release` skill or `/release` command when asking +Codex, Claude, Cursor, or Gemini to prepare or publish a release. The skill is a +Markdown workflow on purpose: it keeps release policy near the agent +instructions without adding another release script to maintain. + +The requested version may be written as either `X.Y.Z` or `vX.Y.Z`. The package +version is always `X.Y.Z`, and the git tag is always the annotated `vX.Y.Z` +tag. + Release steps: 1. Update the CLI package version in `packages/cli/package.json`. -2. Keep the workspace lockfile in sync. At minimum, update the `packages/cli` entry in `package-lock.json` so the committed workspace metadata matches the published package version. +2. Run `npm install` from the repository root so npm updates `package-lock.json` + and synchronizes the `packages/cli` entry with the new package version. 3. Run the release checks locally: - `npm -w packages/cli run build` + - `npm -w packages/cli run typecheck` + - `npm -w packages/cli run lint` - `npm -w packages/cli test` 4. Review the generated release note locally before tagging: - - `git-cliff --config .github/cliff.toml --latest --strip header` + - `git-cliff --config .github/cliff.toml --unreleased --tag vX.Y.Z --strip header` 5. If the generated note reads like an implementation log, rewrite the relevant commit subjects or add `Release note:` / `Release note: skip` lines before tagging. -6. Commit the version bump to `main`. -7. Create and push the matching git tag, for example `vX.Y.Z`. +6. Stage `packages/cli/package.json`, `package-lock.json`, and the rebuilt + `packages/cli/dist/cli.js`. +7. Commit the version bump to `main` as `chore: bump version to X.Y.Z` with + `Release note: skip`. +8. Create and push the matching git tag, for example `vX.Y.Z`. Important: diff --git a/docs/engineering.md b/docs/engineering.md index 737f05cc..2299b792 100644 --- a/docs/engineering.md +++ b/docs/engineering.md @@ -112,7 +112,7 @@ subject as public copy unless the commit type is intentionally internal. - Keep multi-commit PRs readable in the generated release note. Review-fix follow-up commits in a multi-commit PR should usually use `Release note: skip` unless they describe a distinct user-visible change. - The release generator capitalizes the first character of each bullet as a safety net. Still write natural English yourself; this only fixes mechanical lower-case commit subjects. - A PR title is not the release-note source, but it should still read like the top-level release summary for the PR. If the title would be a bad release bullet, improve it before opening or merging the PR. -- Before tagging, run `git-cliff --config .github/cliff.toml --latest --strip header`. If the output reads like an implementation log, rewrite commit subjects/bodies before cutting the release. +- Before tagging, prefer the repo-local `agentnote-release` skill or `/release` command so agents follow the same version bump, build, tests, release note preview, commit, and `vx.y.z` tag workflow. The skill accepts `x.y.z` or `vx.y.z`, but the package version is always `x.y.z` and the git tag is always `vx.y.z`. If running the steps manually, run `git-cliff --config .github/cliff.toml --unreleased --tag vx.y.z --strip header` and rewrite commit subjects/bodies before cutting the release if the output reads like an implementation log. Good commit body shape: