---
name: pstack-setup-release-please
preamble-tier: 3
version: 0.1.0
description: |
  Scaffold release-please into a pstack-managed project for opinionated,
  bot-driven release automation. Copies the three pstack release-please
  templates (workflow, config, manifest), substitutes package name and
  initial version, and prints the manual GitHub-side setup steps (tag
  ruleset bypass for the bot). Opt-in — invoke explicitly when a project
  wants automated releases. Use when asked to "set up release-please",
  "/pstack-setup-release-please", "add release automation", or "automate
  releases for this project".
triggers:
  - /pstack-setup-release-please
  - set up release-please
  - add release automation
  - automate releases
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
---

# pstack-setup-release-please

Scaffolds [release-please](https://github.com/googleapis/release-please)
into the current project using pstack's opinionated configuration.
**Release-please is the standardized release tool for pstack-managed
projects.** This skill applies that standard to the current project on
demand.

## Why opt-in (not bundled into `/pstack-init`)

- Some pstack projects don't need releases (internal services, libraries
  not consumed externally, ongoing-development repos)
- Some projects join pstack mid-life with an existing release strategy
- Release tooling is a conscious choice; auto-deploying it on every
  `/pstack-init` would be over-opinionated

The standardization is in **which tool** (release-please), not in
**whether to apply it** (per-project decision).

## Args

```
/pstack-setup-release-please                          # interactive
/pstack-setup-release-please --package-name <name>    # explicit name
/pstack-setup-release-please --initial-version 0.1.0  # explicit version
```

If args are omitted, the skill asks.

## Pre-conditions

- Current directory is a project root with `.pstack-version` (i.e.,
  `/pstack-init` has been run). The skill is for pstack-managed projects.
- The project uses conventional commits (`/pstack-pr` enforces this).
  Release-please reads commits to compute version bumps.
- The project is a git repo with a GitHub remote.

If any check fails, surface a clear error and stop.

## Steps

### 1. Detect package name and initial version

**Package name** (used in CHANGELOG header + Release titles):
- If `--package-name` arg provided, use it.
- Else read `name` from `package.json` if present.
- Else use the directory name.
- Confirm with the user.

**Initial version**:
- If `--initial-version` arg provided, use it.
- Else look for the latest existing git tag matching `v*.*.*`. Use that.
- Else default to `0.0.0`.
- Confirm with the user. (Release-please will compute the next bump from
  conventional commits since this version.)

### 2. Check for existing release-please files

```bash
test -f .github/workflows/release-please.yml && echo "EXISTS_WORKFLOW"
test -f .release-please-config.json && echo "EXISTS_CONFIG"
test -f .release-please-manifest.json && echo "EXISTS_MANIFEST"
```

If any exist, ask the user before overwriting. Default: skip if any exists
and tell the user to remove the conflicting files first.

### 3. Copy templates and substitute placeholders

```bash
mkdir -p .github/workflows

cp "${CLAUDE_SKILL_DIR}/../../templates/release-please-workflow.yml" \
   .github/workflows/release-please.yml

sed "s/{{PACKAGE_NAME}}/$PACKAGE_NAME/g" \
   "${CLAUDE_SKILL_DIR}/../../templates/release-please-config.json" \
   > .release-please-config.json

sed "s/{{INITIAL_VERSION}}/$INITIAL_VERSION/g" \
   "${CLAUDE_SKILL_DIR}/../../templates/release-please-manifest.json" \
   > .release-please-manifest.json
```

### 4. Print the manual GitHub-side setup

The pstack workflow template uses a Personal Access Token stored at
`secrets.MY_RELEASE_PLEASE_TOKEN`. The PAT identity (not the default
`github-actions[bot]`) is what creates tags, so the PAT's owner is the
account that must be in the tag-ruleset bypass list.

Why PAT instead of the default `GITHUB_TOKEN`: GitHub's ruleset bypass
picker doesn't expose `github-actions[bot]` as a selectable actor on most
repos. A PAT owned by a real account that IS in the bypass list works
around this without the complexity of creating a dedicated GitHub App.
(Teams who prefer a non-human identity can switch to a GitHub App later;
the workflow file just needs to swap the token source.)

Show the user:

> ## Manual setup required
>
> 1. **Create a fine-grained PAT.** Recommended: under a dedicated bot/admin
>    account (e.g., `<org>-admin`) rather than your personal account, so
>    rotation and audit trails are clean.
>    - Visit https://github.com/settings/personal-access-tokens/new
>    - Repository access: this repo
>    - Permissions:
>      - Contents: **Read and write**
>      - Pull requests: **Read and write**
>    - Expiration: 12 months
>    - Generate token. Copy the value — it's only shown once.
>
> 2. **Store as a repo secret.**
>    - Settings → Secrets and variables → Actions → New repository secret
>    - Name: `MY_RELEASE_PLEASE_TOKEN` (exact, case-sensitive)
>    - Value: the PAT
>
> 3. **Tag ruleset bypass.** If your repo restricts tag creation (the
>    recommended pstack pattern — see `pstack-init`'s rulesets):
>    - Settings → Rules → Rulesets → edit your `v*` tag ruleset
>    - Add the PAT owner's account (e.g., `<org>-admin`) to the bypass
>      list with mode **Always**
>    - Save
>
>    Without this, the release workflow will fail at tag creation with
>    `Cannot create ref due to creations being restricted`.
>
> 4. **First Release PR.** After committing these files and pushing to
>    main, the release-please workflow runs and opens a "Release v<next>"
>    PR. Review the auto-generated CHANGELOG, then merge to tag the
>    release.
>
> 5. **PR review model.** The release PR is bot-authored. Approving and
>    merging it counts as your release decision. Conventional commit
>    prefixes in your branch history are the source of truth for what's
>    in the release.

### 5. Suggest the commit

Print:

> "Three files written:
>   .github/workflows/release-please.yml
>   .release-please-config.json
>   .release-please-manifest.json
>
> Suggested commit:
>   git add .github/workflows/release-please.yml .release-please-config.json .release-please-manifest.json
>   git commit -m 'ci: set up release-please for automated releases'
>
> Don't push until you've added the tag ruleset bypass (step 1 above) —
> otherwise the first workflow run will fail."

Do not auto-commit. The dev reviews and commits.

## Customization (rare)

The pstack templates are opinionated:
- `release-type: simple` (no language-specific package management)
- `v`-prefix in tags
- `changelog-sections` filter `chore`/`style`/`test`/`build`/`ci` out
  of the user-visible CHANGELOG

If a project needs different config (e.g., a Node.js package that should
auto-publish to npm), edit `.release-please-config.json` after this skill
runs. The skill doesn't try to handle every variant — it scaffolds the
common case.

## Do not

- Do not auto-commit. The dev reviews the three files and commits
  alongside whatever else they're working on.
- Do not push the commit on the dev's behalf — they need to add the tag
  ruleset bypass first.
- Do not modify the templates in `templates/release-please-*` — those
  are the pstack standard. Customizations happen in the rendered config
  in the project, post-scaffold.
- Do not call this skill from `/pstack-init`. Setting up releases is a
  conscious per-project decision.