release

Name: release
Author: IncomeStreamSurfer

69stars33forks

How to install release?

incomestreamsurfer/paperclip-surfers/release

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill release

Installs into the current project.

Summary

Coordinate a full Paperclip release across engineering verification, npm, GitHub, smoke testing, and announcement follow-up. Use when leadership asks to ship a release, not merely to discuss versioning.

Files · 1

View on GitHub

SKILL.md

1	# Release Coordination Skill
2
3	Run the full Paperclip maintainer release workflow, not just an npm publish.
4
5	This skill coordinates:
6
7	- stable changelog drafting via `release-changelog`
8	- canary verification and publish status from `master`
9	- Docker smoke testing via `scripts/docker-onboard-smoke.sh`
10	- manual stable promotion from a chosen source ref
11	- GitHub Release creation
12	- website / announcement follow-up tasks
13
14	## Trigger
15
16	Use this skill when leadership asks for:
17
18	- "do a release"
19	- "ship the release"
20	- "promote this canary to stable"
21	- "cut the stable release"
22
23	## Preconditions
24
25	Before proceeding, verify all of the following:
26
27	1. `.agents/skills/release-changelog/SKILL.md` exists and is usable.
28	2. The repo working tree is clean, including untracked files.
29	3. There is at least one canary or candidate commit since the last stable tag.
30	4. The candidate SHA has passed the verification gate or is about to.
31	5. If manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master`.
32	6. npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
33	7. If running through Paperclip, you have issue context for status updates and follow-up task creation.
34
35	If any precondition fails, stop and report the blocker.
36
37	## Inputs
38
39	Collect these inputs up front:
40
41	- whether the target is a canary check or a stable promotion
42	- the candidate `source_ref` for stable
43	- whether the stable run is dry-run or live
44	- release issue / company context for website and announcement follow-up
45
46	## Step 0 — Release Model
47
48	Paperclip now uses a commit-driven release model:
49
50	1. every push to `master` publishes a canary automatically
51	2. canaries use `YYYY.MDD.P-canary.N`
52	3. stable releases use `YYYY.MDD.P`
53	4. the middle slot is `MDD`, where `M` is the UTC month and `DD` is the zero-padded UTC day
54	5. the stable patch slot increments when more than one stable ships on the same UTC date
55	6. stable releases are manually promoted from a chosen tested commit or canary source commit
56	7. only stable releases get `releases/vYYYY.MDD.P.md`, git tag `vYYYY.MDD.P`, and a GitHub Release
57
58	Critical consequences:
59
60	- do not use release branches as the default path
61	- do not derive major/minor/patch bumps
62	- do not create canary changelog files
63	- do not create canary GitHub Releases
64
65	## Step 1 — Choose the Candidate
66
67	For canary validation:
68
69	- inspect the latest successful canary run on `master`
70	- record the canary version and source SHA
71
72	For stable promotion:
73
74	1. choose the tested source ref
75	2. confirm it is the exact SHA you want to promote
76	3. resolve the target stable version with `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
77
78	Useful commands:
79
80	```bash
81	git tag --list 'v*' --sort=-version:refname \| head -1
82	git log --oneline --no-merges
83	npm view paperclipai@canary version
84	```
85
86	## Step 2 — Draft the Stable Changelog
87
88	Stable changelog files live at:
89
90	- `releases/vYYYY.MDD.P.md`
91
92	Invoke `release-changelog` and generate or update the stable notes only.
93
94	Rules:
95
96	- review the draft with a human before publish
97	- preserve manual edits if the file already exists
98	- keep the filename stable-only
99	- do not create a canary changelog file
100
101	## Step 3 — Verify the Candidate SHA
102
103	Run the standard gate:
104
105	```bash
106	pnpm -r typecheck
107	pnpm test:run
108	pnpm build
109	```
110
111	If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.
112
113	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.
114
115	## Step 4 — Validate the Canary
116
117	The normal canary path is automatic from `master` via:
118
119	- `.github/workflows/release.yml`
120
121	Confirm:
122
123	1. verification passed
124	2. npm canary publish succeeded
125	3. git tag `canary/vYYYY.MDD.P-canary.N` exists
126
127	Useful checks:
128
129	```bash
130	npm view paperclipai@canary version
131	git tag --list 'canary/v*' --sort=-version:refname \| head -5
132	```
133
134	## Step 5 — Smoke Test the Canary
135
136	Run:
137
138	```bash
139	PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
140	```
141
142	Useful isolated variant:
143
144	```bash
145	HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
146	```
147
148	Confirm:
149
150	1. install succeeds
151	2. onboarding completes without crashes
152	3. the server boots
153	4. the UI loads
154	5. basic company creation and dashboard load work
155
156	If smoke testing fails:
157
158	- stop the stable release
159	- fix the issue on `master`
160	- wait for the next automatic canary
161	- rerun smoke testing
162
163	## Step 6 — Preview or Publish Stable
164
165	The normal stable path is manual `workflow_dispatch` on:
166
167	- `.github/workflows/release.yml`
168
169	Inputs:
170
171	- `source_ref`
172	- `stable_date`
173	- `dry_run`
174
175	Before live stable:
176
177	1.

People who liked this also viewed

6 picks

Type

release

69stars33forks

View on GitHub

How to install release?

incomestreamsurfer/paperclip-surfers/release

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill release

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Release Coordination Skill
2
3	Run the full Paperclip maintainer release workflow, not just an npm publish.
4
5	This skill coordinates:
6
7	- stable changelog drafting via `release-changelog`
8	- canary verification and publish status from `master`
9	- Docker smoke testing via `scripts/docker-onboard-smoke.sh`
10	- manual stable promotion from a chosen source ref
11	- GitHub Release creation
12	- website / announcement follow-up tasks
13
14	## Trigger
15
16	Use this skill when leadership asks for:
17
18	- "do a release"
19	- "ship the release"
20	- "promote this canary to stable"
21	- "cut the stable release"
22
23	## Preconditions
24
25	Before proceeding, verify all of the following:
26
27	1. `.agents/skills/release-changelog/SKILL.md` exists and is usable.
28	2. The repo working tree is clean, including untracked files.
29	3. There is at least one canary or candidate commit since the last stable tag.
30	4. The candidate SHA has passed the verification gate or is about to.
31	5. If manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master`.
32	6. npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
33	7. If running through Paperclip, you have issue context for status updates and follow-up task creation.
34
35	If any precondition fails, stop and report the blocker.
36
37	## Inputs
38
39	Collect these inputs up front:
40
41	- whether the target is a canary check or a stable promotion
42	- the candidate `source_ref` for stable
43	- whether the stable run is dry-run or live
44	- release issue / company context for website and announcement follow-up
45
46	## Step 0 — Release Model
47
48	Paperclip now uses a commit-driven release model:
49
50	1. every push to `master` publishes a canary automatically
51	2. canaries use `YYYY.MDD.P-canary.N`
52	3. stable releases use `YYYY.MDD.P`
53	4. the middle slot is `MDD`, where `M` is the UTC month and `DD` is the zero-padded UTC day
54	5. the stable patch slot increments when more than one stable ships on the same UTC date
55	6. stable releases are manually promoted from a chosen tested commit or canary source commit
56	7. only stable releases get `releases/vYYYY.MDD.P.md`, git tag `vYYYY.MDD.P`, and a GitHub Release
57
58	Critical consequences:
59
60	- do not use release branches as the default path
61	- do not derive major/minor/patch bumps
62	- do not create canary changelog files
63	- do not create canary GitHub Releases
64
65	## Step 1 — Choose the Candidate
66
67	For canary validation:
68
69	- inspect the latest successful canary run on `master`
70	- record the canary version and source SHA
71
72	For stable promotion:
73
74	1. choose the tested source ref
75	2. confirm it is the exact SHA you want to promote
76	3. resolve the target stable version with `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
77
78	Useful commands:
79
80	```bash
81	git tag --list 'v*' --sort=-version:refname \| head -1
82	git log --oneline --no-merges
83	npm view paperclipai@canary version
84	```
85
86	## Step 2 — Draft the Stable Changelog
87
88	Stable changelog files live at:
89
90	- `releases/vYYYY.MDD.P.md`
91
92	Invoke `release-changelog` and generate or update the stable notes only.
93
94	Rules:
95
96	- review the draft with a human before publish
97	- preserve manual edits if the file already exists
98	- keep the filename stable-only
99	- do not create a canary changelog file
100
101	## Step 3 — Verify the Candidate SHA
102
103	Run the standard gate:
104
105	```bash
106	pnpm -r typecheck
107	pnpm test:run
108	pnpm build
109	```
110
111	If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.
112
113	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.
114
115	## Step 4 — Validate the Canary
116
117	The normal canary path is automatic from `master` via:
118
119	- `.github/workflows/release.yml`
120
121	Confirm:
122
123	1. verification passed
124	2. npm canary publish succeeded
125	3. git tag `canary/vYYYY.MDD.P-canary.N` exists
126
127	Useful checks:
128
129	```bash
130	npm view paperclipai@canary version
131	git tag --list 'canary/v*' --sort=-version:refname \| head -5
132	```
133
134	## Step 5 — Smoke Test the Canary
135
136	Run:
137
138	```bash
139	PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
140	```
141
142	Useful isolated variant:
143
144	```bash
145	HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
146	```
147
148	Confirm:
149
150	1. install succeeds
151	2. onboarding completes without crashes
152	3. the server boots
153	4. the UI loads
154	5. basic company creation and dashboard load work
155
156	If smoke testing fails:
157
158	- stop the stable release
159	- fix the issue on `master`
160	- wait for the next automatic canary
161	- rerun smoke testing
162
163	## Step 6 — Preview or Publish Stable
164
165	The normal stable path is manual `workflow_dispatch` on:
166
167	- `.github/workflows/release.yml`
168
169	Inputs:
170
171	- `source_ref`
172	- `stable_date`
173	- `dry_run`
174
175	Before live stable:
176
177	1.

People who liked this also viewed

6 picks

Type