/meta-pr-creation

name: meta-pr-creation
description: How an agent authors branches, commits, and pull requests on cipherstash/stack — naming, signed commits, the changeset/skills/meta-file checklist, and PR body structure with dumbed-down wording. Use when committing work or opening/updating a PR.

Authoring PRs as an agent

Internal skill — lives in `.claude/skills/` on purpose. `skills/` ships to customers inside the `stash` tarball; this must not.

Branch and commits

• Branch names are type-prefixed slugs: `docs/skill-psl-functional-indexes`,

`fix/…`, `feat/…`, `chore/…`. Never commit to `main`.

• Commit subjects are conventional: `type(scope): imperative summary` —

`docs(skills): …`, `fix(stack-prisma): …`. The body explains **why** and the mechanism, not a list of what changed (the diff shows that). Reference the GitHub issue the commit serves.

• **Commits must be signed.** `commit.gpgsign` is on, but verify before

pushing:

  git log --format='%h %G? %s' main..HEAD   # G = signed, N = unsigned

An unsigned commit (`N`) in the stack: `git rebase --force-rebase main` re-commits everything signed, then `git push --force-with-lease`. Always `--force-with-lease`, never bare `--force`.

Before opening the PR

The authoritative checklist is `AGENTS.md` § "Adding Features Safely" — read it, don't work from memory. The three most-missed items:

1. **Changeset** — required when the change touches a published package's surface, *including* a `skills/`-only change (those ship in the `stash` tarball, so they need a `stash` patch changeset). A `.claude/`-only change is internal: no changeset. 2. **Skills check** — a change to a public API, CLI surface, or user-facing workflow must fix the affected `skills/*/SKILL.md` in the same PR (package→skill map in `AGENTS.md`). 3. **Meta files** — adding/removing/renaming a package, example, skill, or subpath export must update `AGENTS.md` Repository Layout and `SECURITY.md`.

Then run: `pnpm run code:fix`, `pnpm --filter <pkg> build`, `pnpm --filter <pkg> test`.

PR body

Same wording rule as [meta-issue-creation](../meta-issue-creation/SKILL.md): **dumbed down** — assume the reviewer is new to CipherStash, stack, and EQL. Define product terms at first use; say what breaks or improves in the user's world, not just the code's.

Sections, in order:

• **Summary** — what and why, two or three plain sentences. Lead with the

user-visible effect.

• **Changes** — grouped by area, one line each.
• **Verification** — exactly what was run and what it showed. Honest: a

failing or skipped check is stated, not omitted. "Verified against the 0.17 dist" beats "should work".

• **Related** — `Closes #N` / `Refs #N` for the GitHub issues this serves;

cross-repo refs in full `owner/repo#N` form.

• **Review notes** *(optional)* — where to look first, and anything

deliberately deferred with the reason.

Reference wording traps (same as issues):

• `#N` **only** as a real GitHub issue/PR reference — GitHub autolinks every

`#N`, so "option #2" mints a bogus link. Write "option 2".

• **Never** reference internal Linear issues (`CIP-…`) in PRs, commits, or

comments — GitHub is public.

Mechanics

• **Always open as a draft**: `gh pr create --draft --title '…' --body '…'`

(title follows the commit-subject convention). Mark it ready for review only when the user says so — either ask, or rely on an explicit "open it ready" / "mark it ready" from them. `gh pr ready <number>` flips it.

• Force-pushing a branch with an open PR is fine (rebases, re-signs) — but

say so in a PR comment when the rewrite changes more than commit hashes.

• Don't merge, close, or mark ready-for-review without being asked.