release
Skill8 starsChanged 5 months agoMITView on GitHub
Create a new Prose release with automated testing, GitHub release, and local verification.
- Deletes or force-pushes
- Commits and pushes
193 other projects use a version of this.
Adopted by
Most recently taken up by
- yicheng47/runnertheir own version, first seen Nov 13, 2026
- eugene1g/agent-safehousetheir own version, first seen Nov 12, 2026
- BlockRunAI/ClawRoutertheir own version, first seen Nov 11, 2026
- cubeplexai/cubeplextheir own version, first seen Nov 10, 2026
- bex-co/bextheir own version, first seen Nov 10, 2026
- Yeachan-Heo/oh-my-claudecodetheir own version, first seen Nov 9, 2026
Used with
Projects with it also use create-agent-adapter, changelog-style and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcreate-agent-adapter
Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.
Also in 5 projects that use this
GrinvSkillchangelog-style
Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.
Also in 4 projects that use this
GrinvSkilldocs-consistency-check
Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.
Also in 4 projects that use this
Microsoft AzureSkillcomponent-release
Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.
Also in 4 projects that use this
Microsoft AzureSkilldocumentation-consistency
Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.
Also in 8 projects that use this
rivet-devSkilllaunch-graphics
Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.
Also in 3 projects that use this
- +3 more from Grinv
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- paperclipai/paperclip★ 114ksame name
- modelcontextprotocol/servers★ 92ksame name
- remotion-dev/remotion★ 73ksame name
- traefik/traefik★ 66ksame name
- usememos/memos★ 64ksame name
- tw93/Pake★ 64ksame name
- amruthpillai/reactive-resume★ 46ksame name
- reactive-resume/reactive-resume★ 46ksame name
- AmruthPillai/Reactive-Resume★ 45ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- accelerateSkill
- implement-issueSkill
- pipeline-engSkill
- pipeline-orchestrateSkill
- pipeline-peSkill
- pipeline-scorerSkill
- qa-acceleratedSkill
- qa-prSkill
- qa-webSkill
- releaseSkill
- review-feedbackSkill
- roadmap-prioritizationSkill
- roadmap-refinementSkill
- security-auditSkill
- accelerateSkill
- implement-issueSkill
- pipeline-engSkill
- pipeline-orchestrateSkill
- pipeline-peSkill
- pipeline-scorerSkill
- qa-acceleratedSkill
- qa-hitlSkill
- qa-prSkill
- qa-webSkill
- review-feedbackSkill
- roadmap-prioritizationSkill
- roadmap-refinementSkill
- screenshotsSkill
- security-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 6 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 178
Write it once, there, and commit it before tagging — the tag is what publishes it.
- Distinctive: line 223
If CI is not available or you want to publish manually:
- Very specific: line 267
Use git -C <path> rather than cd && git — compound chains get flagged for manual approval and block unattended agents.
- Distinctive: line 271
Not just the newest one. Find where the copy actually left off:
- Very specific: line 282
Check all of these in prose/index.html.
- Distinctive: line 301
Never invent a feature. Every claim traces back to a release note.
- Very specific: line 366
Do NOT use npm run dev — the smoke test must exercise the signed bundle.
- Distinctive: line 402
If any path fails, fix before tagging.
- Distinctive: line 473
Run through this before any release:
- Very specific: line 516
"Invalid signature": Check that Apple Distribution cert is in keychain and not expired
- Very specific: line 517
"Missing provisioning profile": Verify build/Prose_Distribution.provisionprofile exists and bundle ID matches ist.solo.prose
- Very specific: line 520
"Cannot find valid 3rd Party Mac Developer Installer": Use team ID (8PT2Y7QQ2F) as identity in mas: block, not cert name
- Very specific: line 521
afterPack error "Unsupported platform: mas": Ensure build/afterPack.cjs handles the mas case
- Very specific: line 524
Notarization hanging locally: Don't set notarize: true in config.
- Very specific: line 527
Missing secrets: Verify CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, SENTRY_AUTH_TOKEN are set in repo …
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Release Manager
Manages the full release workflow for Prose across two distribution channels:
- Mac App Store — signed
.pkguploaded via Transporter → TestFlight → App Store - GitHub Releases — signed
.dmg+.zippublished to GitHub for direct download + auto-update
Usage
/release [command]Commands
| Command | Description |
/release | Show current version, build number, and release status |
/release mas | Build and prepare MAS .pkg for Transporter upload |
/release github | Build DMG and create GitHub Release |
/release copy | Update the solo.ist/prose marketing copy after a release |
/release bump-build | Increment buildVersion and rebuild MAS .pkg |
/release bump-version <version> | Bump marketing version (e.g., 1.1.0) |
/release smoke | Build the DMG and walk 7 critical paths (~5 min) — fast pre-release sanity check |
/release status | Check TestFlight processing, GitHub Release, and CI status |
/release checklist | Run the full pre-release verification checklist |
Architecture
Version Numbers
Two version numbers, managed independently:
- Marketing version (
CFBundleShortVersionString): Set inpackage.json"version". Example:1.0.0. This is what users see. Must match the App Store Connect record. - Build number (
CFBundleVersion): Set inelectron-builder.yml"buildVersion". Example:"2". Incremented for each upload to App Store Connect. GitHub Releases don't care about this.
Signing Identities
| Build | Identity | Profile |
| DMG (direct download) | Developer ID Application | None (notarized via CI) |
| MAS (App Store) | Apple Distribution (via team ID 8PT2Y7QQ2F) | build/Prose_Distribution.provisionprofile |
MAS .pkg installer | 3rd Party Mac Developer Installer | N/A |
Bundle ID
ist.solo.prose — used across all builds. Must match provisioning profiles and App Store Connect.
Key Files
| File | Purpose |
package.json | Marketing version ("version") |
electron-builder.yml | Build number (buildVersion), signing config, targets |
build/entitlements.mac.plist | DMG entitlements (includes network.server for MCP) |
build/entitlements.mas.plist | MAS entitlements (sandbox, no network.server) |
build/entitlements.mas.inherit.plist | Child process entitlements for MAS |
build/Prose_Distribution.provisionprofile | MAS distribution profile |
build/afterPack.cjs | Electron fuse flipping |
.github/workflows/release.yml | CI: builds signed DMG on v* tag push |
Workflow: MAS Release (/release mas)
1. Pre-flight
git branch --show-current # Must be on release branch or main
git status --porcelain # Must be clean
node -p "require('./package.json').version" # Current marketing version
grep buildVersion electron-builder.yml # Current build number2. Build
# Clean previous builds
rm -rf dist/mas-arm64
# Build with MAS_BUILD flag (gates HTTP MCP server, auto-updater)
npm run build:mas3. Verify
# Check .pkg exists
ls -la dist/mas-arm64/*.pkg
# Verify version strings
plutil -p dist/mas-arm64/Prose.app/Contents/Info.plist | grep -E "CFBundleVersion|CFBundleShortVersion"
# Verify code signature
codesign --verify --deep --strict dist/mas-arm64/Prose.app
# Verify entitlements
codesign -d --entitlements - dist/mas-arm64/Prose.app 2>&1 | head -20Entitlements must include: app-sandbox, allow-jit, network.client, files.user-selected.read-write, bookmarks.app-scope
Entitlements must NOT include: network.server, get-task-allow
4. Upload to App Store Connect
xcrun altool --upload-app \
--type macos \
--file dist/mas-arm64/Prose-1.0.0-arm64.pkg \
--apiKey 73DLM4525G \
--apiIssuer f46c81a3-3264-4e9d-9b2f-93de6a302175The API key .p8 file lives at ~/.appstoreconnect/private_keys/AuthKey_73DLM4525G.p8.
5. Report
## MAS Build Uploaded
- **Version:** <version> (build <N>)
- **Package:** dist/mas-arm64/Prose-<version>-arm64.pkg
- **Signed:** Apple Distribution + 3rd Party Mac Developer Installer
- **Delivery UUID:** <from upload output>
### Next steps
1. Wait for processing in App Store Connect (~10 min)
2. Test via **TestFlight** on your Mac
3. **HUMAN ONLY:** When satisfied, submit for App Store review manually in App Store Connect
⚠️ **NEVER submit for App Store review programmatically.** This is always a human decision. The automated workflow stops at TestFlight upload.Workflow: GitHub Release (/release github)
1. Pre-flight
git branch --show-current # Should be main (after PR merge)
git status --porcelain # Must be clean2. Build
rm -rf dist/mac-arm64
npm run build:mac3. Verify
# Check outputs
ls -la dist/Prose-*-arm64.dmg dist/Prose-*-arm64-mac.zip
# Verify signature
codesign --verify --deep --strict dist/mac-arm64/Prose.app
# Verify entitlements include network.server (MCP)
codesign -d --entitlements - dist/mac-arm64/Prose.app 2>&1 | grep network.server4. Write the Release Notes
The notes live at resources/release-notes/<version>.md — one file per version, and
the single source of truth (#1058). That same file is bundled into the app (via
extraResources) and shown in the post-update modal, and becomes the GitHub Release
body: release.yml reads it by tag and appends the install/requirements boilerplate.
Write it once, there, and commit it before tagging — the tag is what publishes it.
There is no separate RELEASE_NOTES.md; it was removed in 1.9.0 after sitting stale at
v1.2.0 for six releases, which is the exact drift this one-file rule prevents.
VERSION=$(node -p "require('./package.json').version")
# Commits since last release, to write the notes from
git log $(git tag --list 'v*' --sort=-v:refname | head -1)..HEAD --oneline --no-merges
# Confirm the file the release will actually read
test -f "resources/release-notes/${VERSION}.md" || echo "MISSING — write this first"Template — user-facing changes only. Do not include Installation or Requirements
sections: release.yml appends those to the GitHub Release, and in the in-app modal
they would be noise.
# Prose v<version>
<One sentence description.>
## <Grouping — e.g. Tables, Fixes, Removed>
- <Feature or fix, in user-facing terms>The modal renders a deliberately small markdown subset — ##/### headings, bullets,
paragraphs, and inline bold/italic/code/links. Anything else shows as literal text, so
keep to those (see components/releaseNotes/renderNotes.tsx).
5. Tag and Publish
VERSION=$(node -p "require('./package.json').version")
# Create tag
git tag "v${VERSION}"
git push origin "v${VERSION}"The tag push triggers release.yml which builds, signs, notarizes, and publishes the DMG + ZIP to GitHub Releases automatically.
If CI is not available or you want to publish manually:
gh release create "v${VERSION}" \
--title "Prose v${VERSION}" \
--notes-file "resources/release-notes/${VERSION}.md" \
"dist/Prose-${VERSION}-arm64.dmg" \
"dist/Prose-${VERSION}-arm64-mac.zip"6. Update the marketing copy
The release is not finished when the tag is published. Run /release copy (next section) to bring solo.ist/prose up to the version you just shipped — nothing in CI does this, and the page has drifted five releases behind before.
Workflow: Post-release Marketing Copy (/release copy)
Run this after a GitHub release publishes (and again when a MAS version clears review, if the App Store link or availability changed). The marketing site is a separate repo and nothing in CI touches it — if this step is skipped, solo.ist/prose silently falls behind. It sat pinned at v1.6.2 through five releases because this section didn't exist.
Where the copy lives
| Repo | Path | What it is |
solo-ist/solo-ist (~/Code/solo.ist) | prose/index.html | The solo.ist/prose page — hand-authored HTML, no build step |
solo-ist/solo-ist | COPY.md | Canonical copy mirror for solo.ist and its project pages |
solo-ist/prose | docs/app-store-copy.md | App Store listing copy — canonical here, not in the site repo |
Vercel deploys solo-ist/solo-ist on push to main. prose/index.html has no build step — it ships exactly as authored, so a typo is live the moment the PR merges.
1. Pre-flight
git -C ~/Code/solo.ist fetch origin
git -C ~/Code/solo.ist status --porcelain
gh release list --repo solo-ist/prose --limit 10Working tree must be clean. Branch off freshly-fetched main:
git -C ~/Code/solo.ist checkout -b prose-v<version>-copy origin/mainUse git -C <path> rather than cd && git — compound chains get flagged for manual approval and block unattended agents.
2. Read every release since the last copy update
Not just the newest one. Find where the copy actually left off:
git -C ~/Code/solo.ist log -1 --format=%cI -- prose/index.html # last time the page moved
gh release view <tag> --repo solo-ist/prose --json body -q .body # for each tag sincePoint releases are where the good material hides — a .5 can carry far more user-facing change than the .0 before it.
3. Walk the version-sensitive surfaces
Check all of these in prose/index.html. Each has gone stale at least once:
| # | Surface | Check against |
| 1 | Nav version chip (.nav-ver) | Latest published release tag |
| 2 | "What's new" section label | The current release era |
| 3 | "What's new" cells (.news-tag / .news-title / .news-desc) | Everything shipped since the last copy update |
| 4 | "What's next" preview cell | docs/roadmap.md — reconcile, don't guess |
| 5 | MCP tool list (.mcp-tools) | mcpToolNames in src/shared/tools/registry.ts |
| 6 | Feature cards (.feat-desc) | A release may have widened a feature's scope |
| 7 | Hero sub-paragraph | Its twin in COPY.md — update both or neither |
| 8 | Download / App Store links | MAS link is live only once that version clears review |
4. Write it as marketing, not as a changelog
- Lead with what the reader can now do, not what was implemented.
- One idea per cell. If a cell needs a semicolon, it's two cells.
- Tag each cell with the version that actually introduced the feature (
v1.6.5 — Comments), not the version being shipped — readers returning after a gap need to place it. - Fold dependency bumps and internal refactors out entirely. If a release is the security story, give it one plainly-stated cell.
- Never invent a feature. Every claim traces back to a release note.
5. Verify locally
python3 -m http.server 8899 --directory ~/Code/solo.istOpen http://localhost:8899/prose/. Pick an unused port — other agents may hold the common ones. Confirm the nav chip, the "What's new" grid at both desktop and narrow widths, and that no cell overflows its box.
6. Open the PR
git -C ~/Code/solo.ist add prose/index.html COPY.md
git -C ~/Code/solo.ist commit -m "feat(prose): refresh marketing copy for v<version>"
git -C ~/Code/solo.ist push -u origin prose-v<version>-copy
gh pr create --repo solo-ist/solo-ist --title "Prose v<version> marketing copy" --body "<summary>"⚠️ Never auto-merge and never push straight to main. Marketing voice is a human call — the PR stops for review even when every fact in it is right.
7. Report
## Marketing Copy — v<version>
- **PR:** <url>
- **Updated:** <surfaces changed>
- **Checked, no change needed:** <surfaces>
- **Left stale, with reason:** <surfaces, or "none">Workflow: Quick Smoke Test (/release smoke)
Fast (~5 min) verification before tagging a GitHub release. Exercises the signed/notarized artifact users will actually receive — not dev mode. Use this for routine releases. Escalate to /release checklist if the release touches:
- Main-process IPC handlers or new IPC channels
- Entitlements (
build/entitlements.*.plist) - Sandbox /
contextIsolation/nodeIntegrationsettings - First build after an Electron major upgrade
1. Build (skip if fresh)
rm -rf dist/mac-arm64
npm run build:mac2. Verify artifact
VERSION=$(node -p "require('./package.json').version")
ls -la "dist/Prose-${VERSION}-arm64.dmg" "dist/Prose-${VERSION}-arm64-mac.zip"
codesign --verify --deep --strict dist/mac-arm64/Prose.app
codesign -d --entitlements - dist/mac-arm64/Prose.app 2>&1 | grep network.server # expect a match (MCP)3. Launch the built app
open dist/mac-arm64/Prose.appDo NOT use npm run dev — the smoke test must exercise the signed bundle.
4. Walk the 7 critical paths
| # | Path | Pass criteria |
| 1 | App launches | Window renders, no crash dialog, no console error storm |
| 2 | Editor round-trip | New file → type a paragraph → Cmd+S → close → reopen, content intact |
| 3 | Settings dialog | Opens cleanly, no outline/focus artifacts, closes cleanly |
| 4 | API key test | Settings → LLM → "Test API Key" returns success with current key |
| 5 | Chat streaming | Send a message in chat panel, response streams in fully |
| 6 | Skill download | Help → Download Prose Skill (or Settings → Integrations) downloads the .zip |
| 7 | prose:// scheme | Trigger a prose:// URL (Claude artifact → Open in Prose) and confirm the app handles it |
5. Clean up
rm -f electron-screenshot-*.jpeg6. Report
## Smoke Test Results — v<version>
- [x] App launches
- [x] Editor round-trip
- [x] Settings dialog
- [x] API key test
- [x] Chat streaming
- [x] Skill download
- [x] prose:// scheme
Ready to tag.If any path fails, fix before tagging. Do not ship on red smoke.
Workflow: Bump Build Number (/release bump-build)
Used when you need to re-upload to App Store Connect (Transporter rejects duplicate version + build combos).
1. Read current
grep buildVersion electron-builder.yml2. Increment
Edit electron-builder.yml: increment buildVersion (e.g., "2" → "3").
3. Rebuild and verify
rm -rf dist/mas-arm64
npm run build:mas
plutil -p dist/mas-arm64/Prose.app/Contents/Info.plist | grep CFBundleVersion4. Commit
git add electron-builder.yml
git commit -m "chore(build): bump build number to <N>"
git push origin <branch>5. Upload
xcrun altool --upload-app \
--type macos \
--file dist/mas-arm64/Prose-1.0.0-arm64.pkg \
--apiKey 73DLM4525G \
--apiIssuer f46c81a3-3264-4e9d-9b2f-93de6a302175Report the delivery UUID and wait for App Store Connect processing.
Workflow: Bump Marketing Version (/release bump-version <version>)
1. Update package.json
npm version <version> --no-git-tag-version2. Leave buildVersion alone
Do not reset buildVersion. This project uses a global monotonic build counter across marketing versions (e.g., 1.0.0 ended at build 20; first 1.0.1 MAS upload will be build 21). App Store Connect treats version+build as unique either way, and continuous numbering matches the established pattern.
3. Commit
git add package.json package-lock.json
git commit -m "chore: bump version to <version>"Workflow: Pre-release Checklist (/release checklist)
Run through this before any release:
## Pre-release Checklist
### Build
- [ ] `npm run build` succeeds with no errors
- [ ] `npm run build:mac` produces signed DMG
- [ ] `npm run build:mas` produces signed .pkg
- [ ] `codesign --verify --deep --strict` passes on both builds
### App Verification (DMG build)
- [ ] App launches from dist/mac-arm64/Prose.app
- [ ] Editor: create file, type, save, reopen
- [ ] Settings dialog opens and closes without outline
- [ ] API key test passes (Settings > LLM > Test)
- [ ] Chat works with valid API key
- [ ] Feature flags: Google Docs and reMarkable hidden
- [ ] File explorer: no Google/reMarkable tabs
- [ ] Body does not scroll off screen
### MAS-specific
- [ ] HTTP MCP server disabled (check console for log message)
- [ ] MCP install returns error in MAS build
- [ ] Auto-updater disabled in MAS build
### Security
- [ ] No plaintext secrets in ~/.prose/settings.json
- [ ] DMG entitlements: allow-jit (not allow-unsigned-executable-memory)
- [ ] MAS entitlements: app-sandbox, no network.server
- [ ] Fuses flipped (RunAsNode, NodeOptions, CliInspect all false)
### CI
- [ ] E2E tests pass on PR
- [ ] Code review clean (no blocking issues)Troubleshooting
Transporter rejects upload
- "Duplicate version": Bump
buildVersioninelectron-builder.ymland rebuild - "Invalid signature": Check that
Apple Distributioncert is in keychain and not expired - "Missing provisioning profile": Verify
build/Prose_Distribution.provisionprofileexists and bundle ID matchesist.solo.prose
MAS build fails at signing
- "Cannot find valid 3rd Party Mac Developer Installer": Use team ID (
8PT2Y7QQ2F) as identity inmas:block, not cert name - afterPack error "Unsupported platform: mas": Ensure
build/afterPack.cjshandles themascase
DMG build hangs
- Notarization hanging locally: Don't set
notarize: truein config. Notarization happens in CI via env vars (APPLE_ID,APPLE_APP_SPECIFIC_PASSWORD). Local builds skip it.
GitHub Release workflow fails
- Missing secrets: Verify
CSC_LINK,CSC_KEY_PASSWORD,APPLE_ID,APPLE_APP_SPECIFIC_PASSWORD,APPLE_TEAM_ID,SENTRY_AUTH_TOKENare set in repo secrets - Signing fails in CI:
CSC_LINKmust be the base64-encoded.p12containing the Developer ID Application cert
TestFlight build won't install
- "App can't be opened": Distribution-signed MAS builds cannot run locally. Only TestFlight or App Store installs work.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

