From b85055819971b712a9556f299f4a28f996417702 Mon Sep 17 00:00:00 2001
From: Patrick Wozniak <email@patwoz.de>
Date: Tue, 26 May 2026 23:26:52 +0200
Subject: [PATCH] docs(contributing): add contribution and release guides

---
 AGENTS.md       |   7 ++
 CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++++
 README.md       |  11 +--
 RELEASE.md      | 192 ++++++++++++++++++++++++++++++++++++++++++++++++
 package.json    |   2 +
 5 files changed, 343 insertions(+), 5 deletions(-)
 create mode 100644 AGENTS.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 RELEASE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..72b14b7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,7 @@
+# Agent Instructions
+
+- Follow [CONTRIBUTING.md](CONTRIBUTING.md) before changing code, tests, docs, or commit messages.
+- Use [RELEASE.md](RELEASE.md) for prerelease, npm smoke-test, stable release, tag, and GitHub follow-up work.
+- Keep changes focused and reviewable; avoid unrelated refactors.
+- Run the relevant checks before reporting work as done.
+- Do not commit, tag, push, or publish unless explicitly asked in the current conversation.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a643e9c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,136 @@
+# Contributing
+
+Thanks for helping improve `pi-commandcode-provider`.
+
+This is an unofficial Command Code provider for pi. Keep changes small, tested, and easy to review.
+
+## Development setup
+
+```sh
+npm install
+npm test
+```
+
+Useful commands:
+
+```sh
+npm run typecheck
+npm run format:check
+npm run test:unit
+npm run test:models
+npm run test:oauth
+npm run test:abort
+npm run test:stream
+npm run test:pi-local
+```
+
+Before opening a PR, run:
+
+```sh
+npm test
+npm run format:check
+git diff --check
+```
+
+For release and npm smoke-test steps, see [RELEASE.md](RELEASE.md).
+
+## Pull request guidelines
+
+- Keep PRs focused on one problem or feature.
+- Add or update tests for behavior changes.
+- Update `README.md`, `CHANGELOG.md`, or `RELEASE.md` when user-facing behavior changes.
+- Avoid broad refactors unless the PR is specifically about refactoring.
+- Do not include API keys, tokens, real auth files, `.env` files, or other secrets.
+- Prefer documented/public Command Code API behavior. If compatibility with CLI behavior is needed, document why.
+- Make sure npm package contents still make sense when `package.json` `files` changes.
+
+## Testing pi integration changes
+
+For provider, auth, request-shape, or stream changes, test both local code and the package form when possible.
+
+Local extension smoke:
+
+```sh
+pi --no-extensions -e ./index.ts --list-models commandcode
+```
+
+Npm package smoke and isolated `/login` testing are documented in [RELEASE.md](RELEASE.md#test-the-npm-package-in-pi).
+
+## Commit message rules
+
+Use Angular-style Conventional Commits.
+
+Format:
+
+```txt
+<type>(<scope>): <subject>
+```
+
+Examples:
+
+```txt
+feat(auth): support Command Code CLI auth files
+fix(core): cap max tokens by selected model
+docs(release): document npm smoke testing
+test(stream): cover reasoning start events
+chore(release): publish 0.1.1
+```
+
+### Types
+
+Use one of these types:
+
+- `feat`: a new user-facing feature
+- `fix`: a bug fix
+- `docs`: documentation-only changes
+- `style`: formatting-only changes, no behavior change
+- `refactor`: code restructuring without behavior change
+- `perf`: performance improvement
+- `test`: adding or changing tests
+- `build`: package, dependency, or build-system changes
+- `ci`: CI workflow changes
+- `chore`: maintenance that does not fit another type
+- `revert`: revert a previous commit
+
+### Scopes
+
+Use a short lowercase scope. Prefer existing project areas:
+
+- `auth`
+- `oauth`
+- `core`
+- `models`
+- `stream`
+- `tests`
+- `docs`
+- `release`
+- `deps`
+- `ci`
+
+A scope is strongly recommended. If no scope fits, choose the closest project area instead of omitting it.
+
+### Subject line
+
+- Use imperative mood: `fix(auth): read oauth credentials`, not `fixed` or `fixes`.
+- Keep it concise.
+- Start lowercase after the colon.
+- Do not end with a period.
+
+### Body and footers
+
+Use a body when the reason is not obvious:
+
+```txt
+fix(core): cap max tokens by selected model
+
+Command Code can return models with lower output limits than the provider-wide cap.
+Clamp defaults to the selected model so requests do not exceed upstream limits.
+```
+
+Breaking changes must be marked with `!` or a `BREAKING CHANGE:` footer:
+
+```txt
+feat(api)!: switch to provider api endpoints
+
+BREAKING CHANGE: removes support for the legacy internal generate endpoint.
+```
diff --git a/README.md b/README.md
index 3622c42..474a73a 100644
--- a/README.md
+++ b/README.md
@@ -115,12 +115,13 @@ https://api.commandcode.ai/provider/v1/models
 
 For tests or local mocks, override it with `COMMANDCODE_MODELS_URL`.
 
-## Publish
+## Contributing
 
-```sh
-npm login
-npm publish --access public
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR expectations, and commit message rules.
+
+## Release
+
+See [RELEASE.md](RELEASE.md) for the prerelease, npm smoke-test, stable publish, git tag, and GitHub follow-up checklist.
 
 ## License
 
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..f5f495b
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,192 @@
+# Release Process
+
+This project uses npm semver releases.
+
+Recommended flow:
+
+- publish prereleases with the `next` dist-tag
+- smoke-test the npm package directly in pi
+- publish stable releases with the `latest` dist-tag
+- commit and tag the stable release
+- comment on the related PR or issue after shipping
+
+## Prerelease flow
+
+Use `next` for beta/alpha/manual validation builds.
+
+```sh
+npm version prepatch --preid next --no-git-tag-version
+npm test
+npm run format:check
+npm pack --dry-run
+npm publish --tag next --access public
+```
+
+If npm asks for browser or OTP auth, run the publish command manually and complete the npm prompt.
+
+Verify the registry state:
+
+```sh
+npm view pi-commandcode-provider@next version dist-tags --json
+```
+
+Expected:
+
+- `next` points to the prerelease version
+- `latest` still points to the previous stable version
+
+## Test the npm package in pi
+
+Always test from npm, not the local checkout.
+
+### 1. Model discovery smoke test
+
+```sh
+PI_SKIP_VERSION_CHECK=1 \
+pi --no-extensions \
+  -e npm:pi-commandcode-provider@next \
+  --list-models commandcode
+```
+
+Expected:
+
+- provider `commandcode` appears
+- live Command Code models are listed
+
+### 2. Manual `/login` test with isolated pi config
+
+Use temporary pi config and session directories so the test does not touch your real pi auth.
+
+```sh
+export PI_CC_TEST_AGENT_DIR="$(mktemp -d)"
+export PI_CC_TEST_SESSION_DIR="$(mktemp -d)"
+
+export PI_CODING_AGENT_DIR="$PI_CC_TEST_AGENT_DIR"
+export PI_CODING_AGENT_SESSION_DIR="$PI_CC_TEST_SESSION_DIR"
+export PI_SKIP_VERSION_CHECK=1
+
+pi --no-extensions \
+  -e npm:pi-commandcode-provider@next \
+  --provider commandcode \
+  --model deepseek/deepseek-v4-flash
+```
+
+Inside pi:
+
+```txt
+/login
+```
+
+Then:
+
+1. choose **Use a subscription**
+2. choose **Command Code**
+3. complete the browser auth flow
+4. if automatic transfer fails, paste the copied Command Code API key into pi
+5. send this message:
+
+```txt
+Reply exactly: manual-npm-ok
+```
+
+Expected:
+
+- login succeeds
+- a Command Code credential is saved under the temporary `PI_CODING_AGENT_DIR`
+- the model replies exactly `manual-npm-ok`
+
+### 3. Post-login print-mode test
+
+Using the same exported temp variables from above:
+
+```sh
+pi --no-extensions \
+  -e npm:pi-commandcode-provider@next \
+  --no-session \
+  -p \
+  --provider commandcode \
+  --model deepseek/deepseek-v4-flash \
+  "Reply exactly: manual-npm-ok"
+```
+
+Expected:
+
+```txt
+manual-npm-ok
+```
+
+### 4. Cleanup isolated pi config
+
+Only run this if these variables were created by the test above:
+
+```sh
+rm -rf "$PI_CC_TEST_AGENT_DIR" "$PI_CC_TEST_SESSION_DIR"
+unset PI_CC_TEST_AGENT_DIR PI_CC_TEST_SESSION_DIR
+unset PI_CODING_AGENT_DIR PI_CODING_AGENT_SESSION_DIR PI_SKIP_VERSION_CHECK
+```
+
+## Stable release flow
+
+After the `next` package is verified, set the intended stable version:
+
+```sh
+npm version 0.1.1 --no-git-tag-version
+```
+
+Replace `0.1.1` with the intended stable version.
+
+Update `CHANGELOG.md`, then run checks:
+
+```sh
+npm test
+npm run format:check
+npm pack --dry-run
+git diff --check
+```
+
+Commit and tag:
+
+```sh
+git add .
+git commit -m "Release 0.1.1"
+git tag -a v0.1.1 -m "Release 0.1.1"
+```
+
+Publish stable:
+
+```sh
+npm publish --tag latest --access public
+```
+
+If npm asks for browser or OTP auth, run the publish command manually and complete the npm prompt.
+
+Verify npm:
+
+```sh
+npm view pi-commandcode-provider version dist-tags --json
+npm view pi-commandcode-provider@0.1.1 version --json
+```
+
+Expected:
+
+- `latest` points to the stable version
+- the stable version exists on npm
+
+Push commit and tag:
+
+```sh
+git push origin main
+git push origin v0.1.1
+```
+
+## GitHub follow-up
+
+Comment on the related PR and issue after publishing and pushing:
+
+```sh
+gh pr comment <number> --body "Shipped in \`pi-commandcode-provider@0.1.1\` / tag \`v0.1.1\`."
+
+gh issue comment <number> --body "Shipped in \`pi-commandcode-provider@0.1.1\` / tag \`v0.1.1\`."
+```
+
+Only comment on PRs or issues actually included in the release.
diff --git a/package.json b/package.json
index 93a3d6e..72a1cf4 100644
--- a/package.json
+++ b/package.json
@@ -23,6 +23,8 @@
     "src/",
     "README.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "RELEASE.md",
     "LICENSE"
   ],
   "scripts": {