pi-release-scribe

Changelog and CI/CD release notes generator for Pi. This extension reads local Git history, classifies commits, suggests the next semver version, generates human-readable release notes, and optionally creates GitHub Releases — all without sending your code to external services.

The package is local-first, telemetry-free, and designed for both interactive Pi sessions and headless CI/CD workflows through GitHub Actions.

Table of Contents

• Overview
• Core Capabilities
• Command Surface
• LLM Tools
• Documentation Map
• Tech Stack
• Getting Started
• Configuration
• CI/CD
• Privacy And Security
• Development Workflow
• Testing And Verification
• Project Structure
• Publishing Notes

Overview

pi-release-scribe helps Pi generate release notes without manual copy-paste of Git history. It indexes commits since the latest tag, classifies them (features, fixes, breaking changes, maintenance), suggests the next semver version, and produces audience-aware release notes in multiple formats (markdown, GitHub, Keep a Changelog, Slack, JSON).

This repository is responsible for:

• Pi extension entrypoint and package manifest.
• Git repo discovery and identity detection (including GitHub remote parsing).
• Config schema, loading, validation, and local storage (.pi/release-scribe.json).
• Git tag detection, semantic version sorting, and fallback to initial release mode.
• Commit collection with bounded output, delimiter-safe parsing, PR/issue ref extraction.
• Conventional Commit parsing, fallback heuristic classification, and semver suggestion.
• Release notes rendering with audience modes (developer, client, internal, executive) and output formats.
• Prompt generation with structured JSON markers and no-invention instruction.
• Changelog insert/update with Keep a Changelog detection and dry-run preview.
• Annotated local tag creation with safety validation and optional push.
• GitHub Release creation and update via gh CLI or GITHUB_TOKEN API after explicit approval.
• Pi commands, LLM tools, status UI, release panel, and CI entrypoint script.
• Headless CI/CD support with release-scribe:ci bundled script and GitHub Actions documentation.

Core Capabilities

| Capability | Status | | --------------------------- | -------------------------------------------------------------------- | | Repo discovery | Implemented through git root, branch, remote detection | | Config management | Implemented through /release-scribe-config | | Status health | Implemented through /release-scribe-status | | Status UI widget | Implemented through status bar widget (ready/no-tag/drafting/etc) | | Commit collection | Bounded, delimiter-safe, PR/issue ref extraction | | Conventional Commit parsing | Deterministic with type, scope, breaking detection | | Fallback classifier | Heuristic keyword matching with confidence scoring | | Semver suggestion | Based on classified changes with configurable bump rules | | Release notes rendering | Audience modes + output formats + structured JSON markers | | Assistant prompt contract | No-invention instruction, markdown-first, JSON markers | | Changelog update | Dry-run preview, Keep a Changelog detection, safe insert | | Annotated tag creation | Semver validation, existence check, dirty-block, optional push | | GitHub Release | Draft-first via gh CLI or GITHUB_TOKEN, published with flag | | Monorepo release notes | Helper APIs available; command UX still limited | | PR enrichment | Optional helper, explicit network only | | Local templates | Helper support for repo-local templates | | Asset upload safety | Planning helpers only; upload requires explicit caller integration | | Release quality score | Warnings for missing migrations, dirty/shallow repos, low confidence | | CI/CD support | Headless script, GitHub Actions docs, --yes for CI approval | | Tool output bounding | All tools use bounded text results (50 KB default) |

Command Surface

/release-scribe-status [--json]
/release-scribe-config [--create]
/release-scribe-draft [--from <ref>] [--to <ref>] [--audience <mode>] [--format <format>] [--json]
/release-scribe-changelog [--dry-run] [--yes] [--from <ref>] [--to <ref>] [--output <path>]
/release-scribe-tag <version> [--push] [--allow-dirty] [--yes] [--message <text>]
/release-scribe-publish <tag> [--draft] [--publish] [--update] [--notes <text>] [--title <text>] [--yes]
/release-scribe-panel
/release-scribe-ci-help

Command details

/release-scribe-status — Show release-scribe health snapshot. Reports git root, current branch, latest tag, commit count since tag, working tree state, config health, GitHub remote detection, and gh CLI auth status. Supports --json for machine-readable output.

release-scribe: ready
repoRoot: /path/to/repo
branch: main
latestTag: v1.2.0
commitCount: 14
workingTree: clean
configPath: /path/to/repo/.pi/release-scribe.json
configEnabled: true
github: owner/repo
ghAuth: username (github.com)

/release-scribe-config — Show or create config. Add --create to write the default config file when it does not exist.

/release-scribe-draft — Generate release notes draft from commits since latest tag and queue it as an assistant prompt. Supports --from/--to for custom commit range, --audience (developer/client/internal/executive), --format (markdown/github/keep-a-changelog/slack/json), and --json for structured output without prompting the agent.

/release-scribe-draft
/release-scribe-draft --audience client --format slack
/release-scribe-draft --from v1.1.0 --to v1.2.0 --json

/release-scribe-changelog — Preview or update CHANGELOG.md. DRY-RUN by default (no file written). Use --yes to write without confirmation. Falls back to deterministic local release notes when no draft exists.

/release-scribe-changelog
/release-scribe-changelog --yes
/release-scribe-changelog --from v1.1.0 --to v1.2.0 --dry-run

/release-scribe-tag — Create an annotated local git tag. Validates semver, checks tag existence (local and remote), requires clean working tree by default. Supports --push, --allow-dirty, --yes, and --message.

/release-scribe-tag v1.3.0
/release-scribe-tag v1.3.0 --push
/release-scribe-tag v1.3.0 --allow-dirty --yes

/release-scribe-publish — Create or update a GitHub Release. SAFE DEFAULTS: dry-run, no network. Use --draft to create a draft (default safe mode), --update to update existing, --publish for final release. Never deletes releases or tags.

/release-scribe-publish v1.3.0 --draft
/release-scribe-publish v1.3.0 --publish --yes
/release-scribe-publish v1.3.0 --update --draft

/release-scribe-panel — Show the latest release notes draft in the editor or as text. Run /release-scribe-draft first to generate a draft.

/release-scribe-ci-help — Print CI/CD usage examples including GitHub Actions workflow templates and release-scribe:ci script usage.

LLM Tools

release_scribe_collect_commits
release_scribe_classify_commits
release_scribe_suggest_version
release_scribe_generate_notes_context
release_scribe_stats
release_scribe_update_changelog
release_scribe_github_release

Tool outputs are bounded and truncated to Pi-style limits before reaching the model. Mutating tools (update_changelog, github_release) default to dry-run and require explicit apply, publish, or update flags.

| Tool | Purpose | | --------------------------------------- | ------------------------------------------------------ | | release_scribe_collect_commits | Collect commits from a git range with bounded metadata | | release_scribe_classify_commits | Classify commits into release categories | | release_scribe_suggest_version | Recommend the next semver version | | release_scribe_generate_notes_context | Build structured release context for LLM | | release_scribe_stats | Show release-scribe health snapshot | | release_scribe_update_changelog | Preview or update CHANGELOG.md (dry-run default) | | release_scribe_github_release | Create or update GitHub Release (draft default) |

Documentation Map

Use this reading order for review or release handoff:

1. docs/PRIVACY_SECURITY.md for local-first behavior, secrets handling, and telemetry stance.
2. docs/CI_GITHUB_ACTIONS.md for headless CI/CD workflow setup and troubleshooting.
3. docs/RELEASE.md for package release checklist and maintainer gates.

Tech Stack

| Area | Choice | | ------------------- | ---------------------------------------------- | | Runtime target | Pi extension runtime through TypeScript loader | | Development runtime | Bun | | Language | TypeScript | | Formatter/linter | Biome | | Schema validation | TypeBox | | Test runner | bun test | | Publish target | npm package with Pi manifest |

Getting Started

Install published package:

pi install npm:pi-release-scribe
/reload
/release-scribe-status

Run first draft:

/release-scribe-draft
/release-scribe-panel
/release-scribe-changelog --dry-run

Local package smoke:

bun install
bun run build
pi install .
/reload
/release-scribe-status

Direct extension smoke (when testing built output without package install):

pi install ./dist/index.ts
/reload

Repo-local files created or used by the package:

.pi/release-scribe.json
.pi/release-scribe/latest-draft.md
.pi/release-scribe/latest-draft.json

Configuration

Default config path:

.pi/release-scribe.json

Create it with /release-scribe-config --create.

Key options:

| Option | Purpose | | --------------------------------------------------- | ---------------------------------------------- | | enabled | Enable or disable release features for repo | | tagPattern | Glob pattern for release tags (default: v*) | | versionPrefix | Tag prefix for new versions (default: v) | | defaultAudience | Default audience mode for draft | | defaultFormat | Default output format | | changelogPath | Path to CHANGELOG.md (relative to repo root) | | includeScopes / excludeScopes | Filter commits by conventional commit scope | | hideCategories | Categories to hide from public release notes | | collapseMaintenance | Collapse maintenance entries under one heading | | linkCommits / linkPullRequests | Generate links in release notes | | semver.allowZeroMajorBreakingAsMinor | Breaking changes at 0.x are minor | | semver.depsAsPatch / semver.securityAsPatch | Dependency/security bumps as patch | | git.requireCleanWorkingTreeForTag | Require clean tree for tag creation | | github.draftByDefault | Create drafts instead of published releases | | safety.requireConfirmBeforeFileWrite / Tag/Push | Require explicit approval for mutations | | output.maxCommits / maxCommitBodyChars | Bound commit collection and body text |

Post-MVP hardening

Post-MVP helper modules exist for monorepos, PR enrichment, local templates, additional providers, asset upload planning, and release quality scoring. These helpers are not full end-user workflows yet; public commands remain focused on single-repo draft/changelog/tag/GitHub release flows.

Optional GitHub enrichment can fetch PR title/body/labels/contributors only when caller explicitly opts into network and GITHUB_TOKEN or GH_TOKEN is available.

Repo-local templates live under:

.pi/release-scribe/templates/<name>.md

Allowed template variables: {{version}}, {{title}}, {{summary}}, {{compareUrl}}, {{markdown}}, {{contributors}}, {{generatedAt}}.

Asset upload helpers only plan allowed uploads and require an explicit filename allowlist such as *.tgz; no asset is uploaded by default.

Release quality scoring reports actionable warnings for breaking changes without migration notes, low-confidence classification, unclassified commits, missing tags, dirty tree, and shallow clone.

CI/CD

pi-release-scribe supports headless CI/CD via its bundled script release-scribe:ci:

bun run release-scribe:ci -- --tag v1.3.0 --draft --yes

The script requires no interactive input. It detects CI/GITHUB_ACTIONS environment variables and auto-adopts headless mode. GitHub Actions examples include draft-only, publish, audience/format overrides, and Pi print mode alternatives.

See docs/CI_GITHUB_ACTIONS.md for full workflow templates and troubleshooting.

See /release-scribe-ci-help for a quick CLI reference.

Privacy And Security

pi-release-scribe is local-first.

• No telemetry.
• No default network calls for draft, changelog, tag, or status operations.
• Network usage only for explicit GitHub Release operations or optional enrichment, and only with approval flags/confirmation.
• No token storage — GitHub authentication uses gh CLI or GITHUB_TOKEN/GH_TOKEN env at runtime.
• No raw large diffs sent to the prompt by default.
• /release-scribe-draft sends bounded Git metadata (subjects, authors, SHAs, classifications) to the model provider configured in Pi; this package itself sends no telemetry.
• All subprocess calls use fixed argv arrays (no shell interpolation).
• File writes, tag creation, tag push, and GitHub publish all require explicit flags and/or confirmation.

See docs/PRIVACY_SECURITY.md for full details.

Development Workflow

Install dependencies:

bun install

Run local checks:

bun run check

Build package output:

bun run build

Run npm package dry-run:

bun run pack:dry-run

Run audit before publish:

bun run prepublish:audit

Testing And Verification

Fast verification before handoff:

bun run typecheck
bun run lint
bun test ./test
bun run pack:dry-run

Release verification should also include:

bun run smoke:release-flow
pi install .
/reload
/release-scribe-status
/release-scribe-draft --json

Project Structure

.
|-- docs/
|   |-- CI_GITHUB_ACTIONS.md
|   |-- PRIVACY_SECURITY.md
|   `-- RELEASE.md
|-- scripts/
|   |-- build-package.ts
|   |-- audit-npm-package.ts
|   |-- release-scribe-ci.ts
|   `-- smoke-release-flow.ts
|-- src/
|   |-- commands/
|   |   |-- changelog.ts
|   |   |-- ciHelp.ts
|   |   |-- config.ts
|   |   |-- context.ts
|   |   |-- draft.ts
|   |   |-- publish.ts
|   |   |-- status.ts
|   |   `-- tag.ts
|   |-- config/
|   |   |-- schema.ts
|   |   `-- load.ts
|   |-- git/
|   |   |-- commits.ts
|   |   |-- diff.ts
|   |   |-- repo.ts
|   |   |-- tags.ts
|   |   `-- workingTree.ts
|   |-- github/
|   |   |-- api.ts
|   |   `-- ghCli.ts
|   |-- release/
|   |   |-- changelog.ts
|   |   |-- classifier.ts
|   |   |-- context.ts
|   |   |-- model.ts
|   |   |-- parser.ts
|   |   |-- prompt.ts
|   |   |-- renderer.ts
|   |   |-- safety.ts
|   |   |-- templates.ts
|   |   |-- types.ts
|   |   `-- version.ts
|   |-- store/
|   |   `-- draftStore.ts
|   |-- tools/
|   |   `-- register.ts
|   |-- ui/
|   |   |-- releasePanel.ts
|   |   `-- statusWidget.ts
|   |-- util/
|   |   |-- exec.ts
|   |   |-- ghAuth.ts
|   |   |-- json.ts
|   |   `-- truncate.ts
|   `-- extension.ts
|-- test/
|-- index.ts
|-- package.json
`-- README.md

Publishing Notes

Publish path:

1. Complete maintainer release checklist (see docs/RELEASE.md).
2. Run bun run check.
3. Run bun run pack:dry-run.
4. Run bun run prepublish:audit.
5. Run bun run smoke:release-flow.
6. Create and push release tag.
7. Let .github/workflows/publish.yml publish through npm trusted publishing/OIDC.

The Pi manifest is declared in package.json:

{
  "pi": {
    "extensions": ["./dist/index.ts"]
  }
}

The npm package file whitelist includes runtime dist, selected public docs, README, license, and package metadata.

Troubleshooting

| Condition | Behavior | | ------------------------- | ------------------------------------------------------- | | Not a git repo | Status reports disabled with instruction to enter repo | | No tags found | Initial release mode — collects all commits from root | | Shallow clone | Warns and fails in CI with fetch-depth: 0 instruction | | Dirty tree during tag | Blocks unless --allow-dirty is set | | Tag already exists | Blocks with instruction to inspect existing tag | | gh not authenticated | Falls back to GITHUB_TOKEN or reports clear error | | GitHub API rate/auth fail | Reports status, does not retry aggressively | | Too many commits | Truncates, warns, suggests manual range | | Assistant JSON invalid | Keeps markdown, warns structured parse failed |