From fd73d6fcab52295796cd6d2a3ad719b42cd0233c Mon Sep 17 00:00:00 2001 From: Dotta Date: Thu, 5 Mar 2026 11:23:58 -0600 Subject: [PATCH] docs(skills): add release coordination workflow --- skills/release/SKILL.md | 215 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 skills/release/SKILL.md diff --git a/skills/release/SKILL.md b/skills/release/SKILL.md new file mode 100644 index 00000000..7fe3d97c --- /dev/null +++ b/skills/release/SKILL.md @@ -0,0 +1,215 @@ +--- +name: release +description: > + Coordinate a full Paperclip release across engineering, website publishing, + and social announcement. Use when CTO/CEO requests "do a release" or + "release vX.Y.Z". Runs pre-flight checks, generates changelog via + release-changelog, executes npm release, creates cross-project follow-up + tasks, and posts a release wrap-up. +--- + +# Release Coordination Skill + +Run the full Paperclip release process as an organizational workflow, not just +an npm publish. + +This skill coordinates: +- App release execution (`scripts/release.sh`) +- User-facing changelog generation (`release-changelog` skill) +- Website publishing task creation +- CMO announcement task creation +- Final release summary with links + +--- + +## Trigger + +Use this skill when leadership asks for: +- "do a release" +- "release {patch|minor|major}" +- "release vX.Y.Z" + +--- + +## Preconditions + +Before proceeding, verify all of the following: + +1. `skills/release-changelog/SKILL.md` exists and is usable. +2. The `release-changelog` dependency work is complete/reviewed before running this flow. +3. App repo working tree is clean. +4. There are commits since the last release tag. +5. You have release permissions (`npm whoami` succeeds for real publish). +6. If running via Paperclip, you have issue context for posting status updates. + +If any precondition fails, stop and report the blocker. + +--- + +## Inputs + +Collect these inputs up front: + +- Release request source issue (if in Paperclip) +- Requested bump (`patch|minor|major`) or explicit version (`vX.Y.Z`) +- Whether this run is dry-run or live publish +- Company/project context for follow-up issue creation + +--- + +## Step 1 - Pre-flight and Version Decision + +Run pre-flight in the App repo root: + +```bash +LAST_TAG=$(git tag --sort=-version:refname | head -1) +git diff --quiet && git diff --cached --quiet +git log "${LAST_TAG}..HEAD" --oneline --no-merges | head -50 +``` + +Then detect minimum required bump: + +```bash +# migrations +git diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/ + +# schema deltas +git diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/ + +# breaking commit conventions +git log "${LAST_TAG}..HEAD" --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true +``` + +Bump policy: +- Destructive migration/API removal/major changeset/breaking commit -> `major` +- Additive migrations or clear new features -> at least `minor` +- Fixes-only -> `patch` + +If requested bump is lower than required minimum, escalate bump and explain why. + +--- + +## Step 2 - Generate Changelog Draft + +Invoke the `release-changelog` skill and produce: +- `releases/v{version}.md` +- Sections ordered as: Breaking Changes (if any), Highlights, Improvements, Fixes, Upgrade Guide (if any) + +Required behavior: +- Present the draft for human review. +- Flag ambiguous categorization items. +- Flag bump mismatches before publish. +- Do not publish until reviewer confirms. + +--- + +## Step 3 - Run App Release + +After changelog approval, execute: + +```bash +# dry run +./scripts/release.sh {patch|minor|major} --dry-run + +# live release +./scripts/release.sh {patch|minor|major} +``` + +Then capture final release metadata: + +```bash +NEW_TAG=$(git tag --sort=-version:refname | head -1) # e.g. v0.4.0 +NEW_VERSION=${NEW_TAG#v} +NPM_URL="https://www.npmjs.com/package/@paperclipai/cli/v/${NEW_VERSION}" +``` + +If publish fails, stop immediately, keep issue in progress/blocked, and include +failure logs in the update. + +--- + +## Step 4 - Create Cross-Project Follow-up Tasks + +Create at least two tasks in Paperclip: + +1. Website task: publish changelog for `v{version}` +2. CMO task: draft announcement tweet for `v{version}` + +When creating tasks: +- Set `parentId` to the release issue id. +- Carry over `goalId` from the parent issue when present. +- Include `billingCode` for cross-team work when required by company policy. +- Mark website task `high` priority if release has breaking changes. + +Suggested payloads: + +```json +POST /api/companies/{companyId}/issues +{ + "projectId": "{websiteProjectId}", + "parentId": "{releaseIssueId}", + "goalId": "{goalId-or-null}", + "billingCode": "{billingCode-or-null}", + "title": "Publish release notes for v{version}", + "priority": "medium", + "status": "todo", + "description": "Publish /changelog entry for v{version}. Include full markdown from releases/v{version}.md and prominent upgrade guide if breaking changes exist." +} +``` + +```json +POST /api/companies/{companyId}/issues +{ + "projectId": "{workspaceProjectId}", + "parentId": "{releaseIssueId}", + "goalId": "{goalId-or-null}", + "billingCode": "{billingCode-or-null}", + "title": "Draft release announcement tweet for v{version}", + "priority": "medium", + "status": "todo", + "description": "Draft launch tweet with top 1-2 highlights, version number, and changelog URL. If breaking changes exist, include an explicit upgrade-guide callout." +} +``` + +--- + +## Step 5 - Wrap Up the Release Issue + +Post a concise markdown update linking: +- Release issue +- Changelog file (`releases/v{version}.md`) +- npm package URL +- Website task +- CMO task +- Final changelog URL (once website publishes) +- Tweet URL (once published) + +Completion rules: +- Keep issue `in_progress` until website + social tasks are done. +- Mark `done` only when all required artifacts are published and linked. +- If waiting on another team, keep open with clear owner and next action. + +--- + +## Paperclip API Notes (When Running in Agent Context) + +Use: +- `GET /api/companies/{companyId}/projects` to resolve website/workspace project IDs. +- `POST /api/companies/{companyId}/issues` to create follow-up tasks. +- `PATCH /api/issues/{issueId}` with comments for release progress. + +For issue-modifying calls, include: +- `Authorization: Bearer $PAPERCLIP_API_KEY` +- `X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID` + +--- + +## Failure Handling + +If blocked, update the release issue explicitly with: +- what failed +- exact blocker +- who must act next +- whether any release artifacts were partially published + +Never silently fail mid-release.