create-changeset

name	create-changeset
description	Create a changeset for changes to @dreki-gg/* packages in this monorepo. Use when the user says "create a changeset", "add a changeset", "changeset for this", or after making package changes that need a version bump before publishing.

Create a Changeset

This monorepo uses Changesets to version and release the @dreki-gg/* extension packages. Every shippable change needs a changeset — no changeset = no version bump = publish skipped.

A changeset is a small markdown file in .changeset/ with frontmatter declaring which package(s) bump and by how much, followed by a human-readable summary that becomes the CHANGELOG entry.

Preferred: create the file directly

Agents usually don't have an interactive TTY, so write the file directly instead of running changeset (the interactive prompt). Use a short kebab-case name describing the change:

cat > .changeset/<short-kebab-name>.md << 'EOF'
---
"@dreki-gg/pi-<package>": minor
---

One concise paragraph describing the user-facing change and why it matters.
EOF

Example (.changeset/plan-mode-plan-references.md):

---
"@dreki-gg/pi-plan-mode": minor
---

Add `@plan:<slug>` plan references with autocomplete. Type `@plan:` in any
message to fuzzy-search and tag a plan, and on send the plan's tasks + handoff
are attached as context.

The interactive equivalent — only when a TTY is available — is bun run changeset.

Choosing the bump level (semver)

Level	When
patch	Bug fix, internal refactor, docs/tests, no behavior change for users
minor	New backward-compatible feature, new tool/command/flag, additive option
major	Breaking change: removed/renamed tool or command, changed defaults, incompatible config

When unsure between two levels, pick the higher one. Pre-1.0 packages still follow this convention here.

Rules

• One changeset per logical change. A single PR touching several packages can list multiple packages in one changeset's frontmatter (one "pkg": level line each), or use separate files — prefer one file per coherent change.
• Write for the CHANGELOG reader, not the diff. Describe the behavior change and its value, not the implementation. No "refactored X to Y" unless that's the user-facing point.
• Use the exact published package name from packages/<dir>/package.json (@dreki-gg/pi-...). Private packages ("private": true) are not versioned — don't list them.
• Don't run changeset version or publish unless the user explicitly asks. Creating the changeset file is the deliverable; versioning/publishing is a separate step (see the deploy-local skill).

Published packages

pi-ask-mode, pi-browser-tools, pi-code-reviewer, pi-command-sandbox, pi-context-folders, pi-context7, pi-datadog, pi-firestore, pi-lsp, pi-miro, pi-modes, pi-past-chats, pi-plan-mode, pi-pr-canvas, pi-questionnaire, pi-slack, pi-subagent (all under the @dreki-gg/ scope).

After creating the changeset

• Leave the file uncommitted for the user to review, or commit it alongside the change — match the user's workflow.
• Versioning happens later via bun run version (changeset version), which consumes all pending .changeset/*.md files, bumps versions, and updates each package's CHANGELOG.md.
• To actually release, publish to npm with bun run publish (or bun run deploy:public).