Skip to content

The open-source app everyone uses to manage agents at work

docs(skills): add release coordination workflow

Dottafd73d6fcab52
diff --git a/skills/release/SKILL.md b/skills/release/SKILL.md
new file mode 100644
index 0000000000..7fe3d97c6a
--- /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.