From 5889f3fa0693d8b773c06d055431fc60c4c17430 Mon Sep 17 00:00:00 2001
From: Patrick Wozniak <email@patwoz.de>
Date: Tue, 16 Jun 2026 16:29:17 +0200
Subject: [PATCH] docs(release): document deployment process

---
 .../skills/pi-commandcode-release/SKILL.md    | 102 ++++++++++++++++++
 CHANGELOG.md                                  |   6 ++
 2 files changed, 108 insertions(+)
 create mode 100644 .agents/skills/pi-commandcode-release/SKILL.md

diff --git a/.agents/skills/pi-commandcode-release/SKILL.md b/.agents/skills/pi-commandcode-release/SKILL.md
new file mode 100644
index 0000000..397814c
--- /dev/null
+++ b/.agents/skills/pi-commandcode-release/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: pi-commandcode-release
+description: Use when preparing, validating, publishing, or documenting a pi-commandcode-provider release/deployment, including version bumps, changelog entries, npm publish, GitHub releases, tags, and release follow-up comments.
+---
+
+# pi-commandcode-provider Release Skill
+
+Use this skill for every `pi-commandcode-provider` release.
+
+## Core rule
+
+Keep release work explicit and auditable. Do not publish, tag, push, or merge unless the user explicitly asks in the current conversation.
+
+## Required release order
+
+Preferred order for stable releases:
+
+1. Create a release branch with the version/changelog changes.
+2. Open a release PR.
+3. Wait for CI to pass.
+4. Create a local annotated git tag for the release commit while the PR is still open.
+5. Publish the npm package from the release branch/commit.
+6. Create the GitHub Release from the release tag.
+7. Verify npm and the GitHub Release.
+8. Merge the release PR into `main`.
+9. Move/recreate the git tag on the merge commit if the project requires tags to point at `main`, then force-update only after explicit user approval. Prefer documenting the tag target instead of force-updating.
+10. Comment on included PRs/issues after the package and GitHub Release are live.
+
+If branch protection or repository policy requires tags to point at `main`, ask before changing the order or force-updating a tag.
+
+## Version and changelog
+
+- Increase semver appropriately; for a patch release use `npm version patch --no-git-tag-version`.
+- Update `CHANGELOG.md` in the same PR.
+- Add a dated section for the new version.
+- Include user-facing changes and dependency/security fixes.
+- Include a `Contributors` subsection for every release that had external reports, PRs, testing, or issue validation.
+
+Example changelog structure:
+
+```md
+## 0.4.1 - 2026-06-16
+
+- Fix provider registration for newer pi versions.
+- Resolve npm audit findings.
+
+### Contributors
+
+- @user-a — fixed provider registration.
+- @user-b — reported/validated retry behavior.
+```
+
+## Validation
+
+Run the checks from `RELEASE.md`. For this repo, at minimum:
+
+```sh
+npm test
+npm run typecheck
+npm run format:check
+npm audit --audit-level=moderate
+npm pack --dry-run
+git diff --check
+```
+
+If local pi auth makes `test:pi-local` use the wrong provider state, rerun the suite with a harmless mock Command Code API key in the environment instead of real auth.
+
+If a live-auth test is needed and the user explicitly approves using local/server auth, use the repo helper if present. Never print API keys.
+
+## GitHub Release notes
+
+Always include:
+
+- Summary of changes.
+- Contributors section with GitHub handles.
+- Validation section.
+- Links to relevant PRs/issues.
+
+## npm publish
+
+Publish manually/local from the checked-out release commit:
+
+```sh
+npm publish --tag latest --access public
+```
+
+Verify:
+
+```sh
+npm view pi-commandcode-provider version dist-tags --json
+npm view pi-commandcode-provider@<version> version --json
+```
+
+If npm auth fails, stop and ask the user to log in; do not read token files.
+
+## Follow-up comments
+
+After npm and GitHub Release are live, comment only on PRs/issues actually included in the release:
+
+```txt
+Shipped in `pi-commandcode-provider@<version>` / GitHub release `v<version>`.
+```
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27828dd..6ca1a66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@
 - Use the explicit `$COMMANDCODE_API_KEY` provider registration syntax expected by newer pi versions, removing the startup deprecation warning while keeping legacy placeholder compatibility.
 - Refresh development dependency lockfile entries to resolve npm audit findings for `tsx`/`esbuild` and `protobufjs`.
 
+### Contributors
+
+- @plumj-am — fixed the pi provider `apiKey` deprecation warning.
+- @cad0p — reported retry/deprecation-related issues that helped validate the current behavior.
+- @bl4zee1g — reported provider availability concerns that prompted additional local/live validation.
+
 ## 0.4.0 - 2026-06-02
 
 - Add retry mechanism for transient HTTP errors (429, 5xx) and stream-level errors, configurable via pi `settings.json` `retry.provider` fields (`timeoutMs`, `maxRetries`, `maxRetryDelayMs`). Supports exponential backoff with jitter and `Retry-After` header.