release

Release Coordination Skill

Run the full Paperclip maintainer release workflow, not just an npm publish.

This skill coordinates:

• stable changelog drafting via release-changelog
• canary verification and publish status from master
• Docker smoke testing via scripts/docker-onboard-smoke.sh
• manual stable promotion from a chosen source ref
• GitHub Release creation
• website / announcement follow-up tasks
• release-content Cases dogfood: a top-level release case with child blog_post and tweet_storm cases, all linked to the release issue/run

Trigger

Use this skill when leadership asks for:

• "do a release"
• "ship the release"
• "promote this canary to stable"
• "cut the stable release"

Preconditions

Before proceeding, verify all of the following:

1. .agents/skills/release-changelog/SKILL.md exists and is usable.
2. The repo working tree is clean, including untracked files.
3. There is at least one canary or candidate commit since the last stable tag.
4. The candidate SHA has passed the verification gate or is about to.
5. If manifests changed, the CI-owned pnpm-lock.yaml refresh is already merged on master.
6. npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
7. If running through Paperclip, you have issue context for status updates and follow-up task creation.

If any precondition fails, stop and report the blocker.

Inputs

Collect these inputs up front:

• whether the target is a canary check or a stable promotion
• the candidate source_ref for stable
• whether the stable run is dry-run or live
• release issue / company context for website and announcement follow-up

Step 0 — Release Model

Paperclip now uses a commit-driven release model:

1. every push to master publishes a canary automatically
2. canaries use YYYY.MDD.P-canary.N
3. stable releases use YYYY.MDD.P
4. the middle slot is MDD, where M is the UTC month and DD is the zero-padded UTC day
5. the stable patch slot increments when more than one stable ships on the same UTC date
6. stable releases are manually promoted from a chosen tested commit or canary source commit
7. only stable releases get releases/vYYYY.MDD.P.md, git tag vYYYY.MDD.P, and a GitHub Release

Critical consequences:

• do not use release branches as the default path
• do not derive major/minor/patch bumps
• do not create canary changelog files
• do not create canary GitHub Releases

Step 1 — Choose the Candidate

For canary validation:

• inspect the latest successful canary run on master
• record the canary version and source SHA

For stable promotion:

1. choose the tested source ref
2. confirm it is the exact SHA you want to promote
3. resolve the target stable version with ./scripts/release.sh stable --date YYYY-MM-DD --print-version

Useful commands:

git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version

Step 2 — Draft the Stable Changelog

Stable changelog files live at:

• releases/vYYYY.MDD.P.md

Invoke release-changelog and generate or update the stable notes only.

Rules:

• review the draft with a human before publish
• preserve manual edits if the file already exists
• keep the filename stable-only
• do not create a canary changelog file

Step 3 — Verify the Candidate SHA

Run the standard gate:

pnpm -r typecheck
pnpm test:run
pnpm build

If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.

For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.

Step 4 — Validate the Canary

The normal canary path is automatic from master via:

• .github/workflows/release.yml

Confirm:

1. verification passed
2. npm canary publish succeeded
3. git tag canary/vYYYY.MDD.P-canary.N exists

Useful checks:

npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5

Step 5 — Smoke Test the Canary

Run:

PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

Useful isolated variant:

HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

Confirm:

1. install succeeds
2. onboarding completes without crashes
3. the server boots
4. the UI loads
5. basic company creation and dashboard load work

If smoke testing fails:

• stop the stable release
• fix the issue on master
• wait for the next automatic canary
• rerun smoke testing

Step 6 — Preview or Publish Stable

The normal stable path is manual workflow_dispatch on:

• .github/workflows/release.yml

Inputs:

• source_ref
• stable_date
• dry_run

Before live stable:

1. resolve the target stable version with ./scripts/release.sh stable --date YYYY-MM-DD --print-version
2. ensure releases/vYYYY.MDD.P.md exists on the source ref
3. run the stable workflow in dry-run mode first when practical
4. then run the real stable publish

The stable workflow:

• re-verifies the exact source ref
• computes the next stable patch slot for the chosen UTC date
• publishes YYYY.MDD.P under dist-tag latest
• creates git tag vYYYY.MDD.P
• creates or updates the GitHub Release from releases/vYYYY.MDD.P.md

Local emergency/manual commands:

./scripts/release.sh stable --dry-run
./scripts/release.sh stable
git push public-gh refs/tags/vYYYY.MDD.P
./scripts/create-github-release.sh YYYY.MDD.P

Step 7 — Finish the Other Surfaces

Create or verify follow-up work for:

• website changelog publishing
• launch post / social announcement
• release summary in Paperclip issue context

These should reference the stable release, not the canary.

Step 8 — Emit Release-Content Cases

When Cases are enabled, every stable release-content run must materialize a deterministic case tree. This is part of the release dogfood path, not an optional artifact. If the API returns 403 Cases are disabled, stop and report that the operator must enable experimental.enableCases.

Use the current release issue's PAPERCLIP_COMPANY_ID, PAPERCLIP_API_URL, PAPERCLIP_API_KEY, and PAPERCLIP_RUN_ID. Include X-Paperclip-Run-Id on all writes so the case activity feed can attribute the run back to the issue.

Create or upsert the parent release case first:

POST /api/companies/:companyId/cases
{
  "caseType": "release",
  "key": "paperclip-release:vYYYY.MDD.P",
  "title": "Paperclip vYYYY.MDD.P release",
  "summary": "Stable release content package for Paperclip vYYYY.MDD.P.",
  "status": "in_progress",
  "fields": {
    "schema_version": 1,
    "version": "vYYYY.MDD.P",
    "release_date": "YYYY-MM-DD",
    "source_ref": "git-sha-or-ref",
    "stable": true,
    "channels": ["changelog", "blog_post", "tweet_storm"],
    "artifacts": {
      "changelog_path": "releases/vYYYY.MDD.P.md",
      "github_release_url": null
    },
    "verification": {
      "typecheck": "unknown",
      "tests": "unknown",
      "build": "unknown",
      "smoke": "unknown"
    },
    "notes": null
  }
}

The fields schema intentionally uses all generic JSON value types: strings, numbers, booleans, arrays, objects, and nulls. Send the complete fields object on each upsert because case fields replace as a whole object.

Write the parent body document immediately after the upsert:

PUT /api/cases/:releaseCaseId/documents/body
{
  "title": "Paperclip vYYYY.MDD.P release body",
  "format": "markdown",
  "body": "# Paperclip vYYYY.MDD.P\n\nRelease summary and links...",
  "changeSummary": "Initial release case body"
}

Then create or upsert these child cases with parentCaseId set to the release case id:

• blog_post, key paperclip-release:vYYYY.MDD.P:blog-post, status in_progress, body document key body
• tweet_storm, key paperclip-release:vYYYY.MDD.P:tweet-storm, status in_progress, body document key body

Use deterministic keys exactly so rerunning the release-content flow upserts the same three cases instead of duplicating them. After the child body documents are written, list the resulting case identifiers and links in the release issue and in the parent acceptance issue when one exists.

Failure Handling

If the canary is bad:

• publish another canary, do not ship stable

If stable npm publish succeeds but tag push or GitHub release creation fails:

• fix the git/GitHub issue immediately from the same release result
• do not republish the same version

If latest is bad after stable publish:

./scripts/rollback-latest.sh <last-good-version>

Then fix forward with a new stable release.

Output

When the skill completes, provide:

• candidate SHA and tested canary version, if relevant
• stable version, if promoted
• verification status
• npm status
• smoke-test status
• git tag / GitHub Release status
• website / announcement follow-up status
• release-content case tree links: parent release case plus blog_post and tweet_storm children
• rollback recommendation if anything is still partially complete