@nvice-r/pr-commands 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# @nvice-r/pr-commands
+
+Provider-agnostic pull-request helper for [Claude Code](https://claude.com/claude-code).
+One `/pr` command that drafts a PR title + body in your team's convention, infers the base
+branch, warns on oversized diffs, attaches reviewers, and creates the PR — with the provider
+(Bitbucket / GitHub / GitLab) auto-detected from your git remote.
+
+> **Status:** macOS + Bitbucket today. GitHub / GitLab and Linux are stubbed and land without
+> new command files — see [Architecture](#architecture).
+
+## Install
+
+```bash
+npx @nvice-r/pr-commands
+```
+
+The interactive wizard:
+
+1. **Environment** — detects OS → token source (macOS keychain).
+2. **Work directory** — the repo to configure. Prompted with the current dir pre-filled and
+   editable (or pass `--dir`). Must be a git repo.
+3. **Provider** — detected from `git remote get-url origin`.
+4. **Identity + token** — reads your API token from the keychain (or tells you how to add one).
+5. **Reviewers** — fetches the repo's default reviewers into an interactive checklist
+   (`↑/↓` move · `space` toggle · `a` all · `n` none · `b` back · `enter` confirm; all pre-selected).
+6. **Convention** — pick a preset, then review/edit its title-pattern, ticket-regex, and
+   template-sections (each pre-filled from the preset, editable). A placeholder legend
+   (`<ver>`, `<desc>`, `<ticket>`, …) is shown. Concrete values are written to config — `/pr`
+   reads those, not a hard-coded table.
+7. **Install** — writes config + roster, drops the binaries and the `/pr` skill.
+
+Every prompt is reversible: in a list press `b` to step back; in a text field, append `:b` to
+the value and press enter (the field is pre-filled, so `:b` at the end triggers back). Back
+navigation is field-level (you can revisit any single convention field).
+
+Flags:
+
+| flag | effect |
+|------|--------|
+| `--dir <path>` | repo to configure (default: cwd) |
+| `--provider <p>` | force `bitbucket`\|`github`\|`gitlab` instead of detecting |
+| `--all` | install every ready provider binary, not just the detected one |
+| `--yes` | non-interactive: reviewers = all, convention = `trueid` |
+| `--dry-run` | print planned actions, write nothing |
+| `--help` | usage |
+
+**Dry-run first** to see exactly what will be written:
+
+```bash
+npx @nvice-r/pr-commands --dry-run --dir /path/to/repo
+```
+
+### Prerequisites
+
+- **Node ≥ 16** (for the installer only; the installed tools are bash).
+- **`~/.local/bin` on your `PATH`.** The installer warns if it isn't:
+  ```bash
+  export PATH="$HOME/.local/bin:$PATH"
+  ```
+- **A Bitbucket API token in the keychain** (the installer can't mint secrets):
+  ```bash
+  security add-generic-password -s bitbucket-api-token -a you@example.com -w '<api-token>'
+  ```
+  Without it, install still completes but reviewers aren't auto-fetched.
+
+## What gets installed
+
+Everything is **global** — nothing lands in a repo's `.claude/`, so it works identically from
+every clone and every git worktree, no symlinks.
+
+| Artifact | Path |
+|----------|------|
+| Shared library | `~/.local/bin/pr-common.sh` |
+| Provider binary | `~/.local/bin/bbpr` (`ghpr`/`glpr` later) |
+| Config | `~/.config/pr/config` |
+| Reviewer roster | `<main-repo-root>/.pr-reviewers.txt` (shared across worktrees) |
+| `/pr` skill | `~/.claude/commands/pr.md` |
+
+## Usage
+
+In Claude Code, from any configured repo:
+
+```
+/pr                 # infer base, draft PR, confirm, create
+/pr feature/2.3.0/center   # explicit base branch
+/pr draft           # create as draft
+/pr help            # help
+```
+
+`/pr` gathers git context, proposes a title + body in your convention, shows it for
+confirmation, then calls the detected binary. It never creates a PR silently.
+
+## Configuration
+
+`~/.config/pr/config` (written by the installer):
+
+```ini
+os=macos             # macos | linux
+token_src=keychain   # keychain | secret-tool | env
+email=you@example.com
+convention=trueid    # see presets
+```
+
+Edit by hand any time. **A missing config is a hard error** — `/pr` and the binaries refuse to
+guess. Re-run the installer to regenerate.
+
+### Convention presets
+
+| preset | title pattern | ticket regex | template sections |
+|--------|---------------|--------------|-------------------|
+| `trueid` | `[<ver>] Feature/<ver>/SC-XXXX <desc>` | `SC-\d+` | What Happened / Insight / Proof of Work |
+| `conventional` | `<type>(<scope>): <desc>` | `[A-Z]+-\d+` | Summary / Changes / Testing |
+| `github-default` | `<desc> (#<issue>)` | `#\d+` | Summary / Test plan |
+| `custom` | your `title_pattern=` | your `ticket_regex=` | your `template_sections=` (pipe-separated) |
+
+`custom` example:
+
+```ini
+convention=custom
+title_pattern=<ticket>: <desc>
+ticket_regex=JIRA-\d+
+template_sections=Context|Changes|Risk
+```
+
+### Reviewers
+
+Roster lives **in the work dir** at the main repo root, so it's editable next to the code.
+Resolved via `git --git-common-dir/..`, so all worktrees of a repo share one roster:
+
+```
+<main-repo-root>/.pr-reviewers.txt
+```
+
+You (the author) are excluded on install — bbpr also drops self at PR time. One entry per line,
+trailing `# Name` comment optional:
+
+```
+{01234567-89ab-cdef-0123-456789abcdef}  # Alice
+{fedcba98-7654-3210-fedc-ba9876543210}  # Bob
+```
+
+It's plain data — edit freely, no reinstall. Consider gitignoring it unless the team wants the
+roster committed. Load order: `$BBPR_REVIEWERS` → work-dir file → global
+`~/.config/pr/reviewers/<ws>-<slug>.txt` → legacy. Run-time overrides: `--no-reviewers` skips
+all, `--reviewer <uuid>` appends.
+
+### Auth precedence (email)
+
+`--email` flag → `$BB_EMAIL` → `git config bbpr.email` → config `email` → keychain account.
+The token is always read from the keychain (or `$PR_TOKEN` when `token_src=env`).
+
+## Provider support
+
+| provider | binary | status |
+|----------|--------|--------|
+| Bitbucket Cloud | `bbpr` | ✅ ready |
+| GitHub | `ghpr` | 🚧 stub — errors `not-yet-supported` |
+| GitLab | `glpr` | 🚧 stub |
+
+| OS | token source | status |
+|----|--------------|--------|
+| macOS | keychain | ✅ ready |
+| Linux | `secret-tool` / `$PR_TOKEN` | 🚧 present, untested |
+
+## Architecture
+
+- **Split by provider, not by OS.** Each provider gets its own small binary (`bbpr`/`ghpr`/`glpr`)
+  because the REST APIs genuinely differ. OS differences (token retrieval) are a single
+  `get_token()` function switched by `uname`, not a separate binary. Ceiling: 3 binaries, never
+  3 × OS.
+- **Shared logic in `pr-common.sh`** — git scan, base save, reviewer load, arg parse, token —
+  sourced by every binary. A provider binary is ~40 lines: payload shape + endpoint + parse.
+- **One generic `/pr` skill.** Convention lives in config, not the skill, so the skill is
+  provider- and team-neutral and installs globally. Adding a provider = one binary + one dispatch
+  line, zero new skill files.
+
+Full rationale in [`DECISIONS.md`](./DECISIONS.md).
+
+## Troubleshooting
+
+| symptom | fix |
+|---------|-----|
+| `no ~/.config/pr/config` | run `npx @nvice-r/pr-commands` |
+| reviewers not fetched | add the keychain token (see Prerequisites), re-run |
+| `WARN ~/.local/bin not on PATH` | add the export line above to your shell rc |
+| `not-yet-supported: <provider>` | GitHub/GitLab aren't implemented yet |
+| worktree runs old behavior | nothing is repo-local here; ensure `pr.md` is at `~/.claude/commands/pr.md`, not a stale repo copy |
+
+## Uninstall
+
+```bash
+rm ~/.local/bin/bbpr ~/.local/bin/pr-common.sh
+rm -rf ~/.config/pr
+rm ~/.claude/commands/pr.md
+# roster lives in each repo — remove per repo if wanted:
+rm <main-repo-root>/.pr-reviewers.txt
+```
+
+## Development
+
+```
+install.js          npx entry (wizard)
+assets/bin/*        provider binaries + shared lib (source of truth; copied on install)
+assets/skill/pr.md  generic /pr skill (source of truth; copied on install)
+```
+
+`assets/` is the single source of truth — both the installer (`install.js`)
+and the published package (`files` in `package.json`) read from it. No duplicate
+tree to keep in sync.
+
+Publish (owner only):
+
+```bash
+npm login
+npm publish --access public
+```
+
+## License
+
+MIT © nvice.r

package/assets/bin/bbpr

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# bbpr-version: 8
+# bbpr — create a Bitbucket Cloud pull request (REST API v2.0).
+# Provider-specific layer; all git/config/creds/reviewer logic lives in pr-common.sh.
+# Usage: bbpr --title "..." [--body|--body-file] [--source b] [--dest b] [--repo w/s]
+#             [--draft] [--reviewer uuid]... [--no-reviewers] [--email a] [--close-source]
+
+set -euo pipefail
+
+PR_CMD="bbpr"
+KEYCHAIN_SERVICE="bitbucket-api-token"
+
+# locate + source the shared lib (same dir as this binary)
+_here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=pr-common.sh
+. "$_here/pr-common.sh"
+
+pr_common_init "$@"
+
+# --- Bitbucket: drop the PR author's own UUID (BB rejects author-as-reviewer) ---
+if [ "${#FINAL_REVIEWERS[@]}" -gt 0 ]; then
+  SELF_UUID="$(curl -sS -u "${EMAIL}:${TOKEN}" "https://api.bitbucket.org/2.0/user" 2>/dev/null \
+    | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("uuid",""))
+except Exception: print("")' 2>/dev/null || true)"
+  if [ -n "$SELF_UUID" ]; then
+    FILTERED=()
+    for r in "${FINAL_REVIEWERS[@]}"; do
+      [ "$r" = "$SELF_UUID" ] || FILTERED+=("$r")
+    done
+    FINAL_REVIEWERS=("${FILTERED[@]:-}")
+    [ -z "${FINAL_REVIEWERS[0]:-}" ] && FINAL_REVIEWERS=()
+  fi
+fi
+
+# --- Bitbucket payload (source/destination keys, draft, reviewers[]) ---
+PAYLOAD="$(
+  TITLE="$TITLE" BODY="$BODY" SOURCE="$SOURCE" DEST="$DEST" \
+  DRAFT="$DRAFT" CLOSE_SOURCE="$CLOSE_SOURCE" \
+  REVIEWERS_JSON="$(printf '%s\n' "${FINAL_REVIEWERS[@]:-}" | python3 -c 'import json,sys; print(json.dumps([{"uuid": l.strip()} for l in sys.stdin if l.strip()]))')" \
+  python3 -c '
+import json, os
+p = {
+  "title": os.environ["TITLE"],
+  "description": os.environ["BODY"],
+  "source": {"branch": {"name": os.environ["SOURCE"]}},
+  "destination": {"branch": {"name": os.environ["DEST"]}},
+  "draft": os.environ["DRAFT"] == "true",
+  "close_source_branch": os.environ["CLOSE_SOURCE"] == "true",
+}
+revs = json.loads(os.environ["REVIEWERS_JSON"])
+if revs: p["reviewers"] = revs
+print(json.dumps(p))
+'
+)"
+
+URL="https://api.bitbucket.org/2.0/repositories/${REPO}/pullrequests"
+echo "POST $URL"
+echo "source=$SOURCE  dest=$DEST  draft=$DRAFT  reviewers=${#FINAL_REVIEWERS[@]}"
+
+RESP="$(curl -sS -X POST "$URL" -u "${EMAIL}:${TOKEN}" \
+  -H 'Content-Type: application/json' -d "$PAYLOAD")"
+
+PR_INFO="$(echo "$RESP" | python3 -c '
+import json, sys
+try: d = json.loads(sys.stdin.read())
+except Exception as e: print("non-JSON response", e); sys.exit(2)
+if "error" in d: print("ERROR:", json.dumps(d["error"], indent=2)); sys.exit(1)
+print(str(d.get("id")) + "\t" + str(d.get("links", {}).get("html", {}).get("href")))
+')"
+
+NEW_PR_ID="$(echo "$PR_INFO" | cut -f1)"
+NEW_PR_URL="$(echo "$PR_INFO" | cut -f2)"
+ATTACHED="$(echo "$RESP" | python3 -c 'import json,sys; print(len(json.load(sys.stdin).get("reviewers", [])))')"
+echo "created PR #${NEW_PR_ID} with ${ATTACHED} reviewers"
+echo "$NEW_PR_URL"
+
+[ -n "$NEW_PR_ID" ] && pr_save_base

package/assets/bin/pr-common.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# pr-common-version: 1
+# pr-common.sh — shared library for provider PR binaries (bbpr/ghpr/glpr).
+# NOT executable on its own — sourced by a provider binary, which then builds the
+# provider-specific payload + POST. Everything here is provider-AGNOSTIC.
+#
+# Provides (after `pr_common_init "$@"`): global vars
+#   TITLE BODY SOURCE DEST REPO EMAIL TOKEN DRAFT CLOSE_SOURCE
+#   FINAL_REVIEWERS[]   (uuids, self already NOT dropped — provider does that)
+# Provides functions:
+#   die, get_token, pr_load_config, pr_parse_args, pr_git_defaults,
+#   pr_resolve_creds, pr_load_reviewers, pr_save_base, pr_common_init
+#
+# Config: ~/.config/pr/config (KEY=value). HARD FAIL if missing (D8).
+
+set -euo pipefail
+
+CONFIG_FILE="${PR_CONFIG:-$HOME/.config/pr/config}"
+
+die() { echo "${PR_CMD:-pr}: $*" >&2; exit 1; }
+
+# --- config load (safe parse, no `source` of untrusted file) ---
+# Sets: CFG_OS CFG_TOKEN_SRC CFG_EMAIL CFG_CONVENTION (+ optional custom_* keys)
+pr_load_config() {
+  [ -f "$CONFIG_FILE" ] || die "no $CONFIG_FILE — run: npx @nvice-r/pr-commands"
+  local k v
+  CFG_OS=""; CFG_TOKEN_SRC=""; CFG_EMAIL=""; CFG_CONVENTION=""
+  while IFS='=' read -r k v; do
+    k="${k%%#*}"; k="${k//[[:space:]]/}"      # strip comment + whitespace from key
+    [ -z "$k" ] && continue
+    v="${v%%#*}"; v="${v#"${v%%[![:space:]]*}"}"; v="${v%"${v##*[![:space:]]}"}"  # trim v
+    case "$k" in
+      os)         CFG_OS="$v" ;;
+      token_src)  CFG_TOKEN_SRC="$v" ;;
+      email)      CFG_EMAIL="$v" ;;
+      convention) CFG_CONVENTION="$v" ;;
+    esac
+  done < "$CONFIG_FILE"
+  : "${CFG_TOKEN_SRC:=keychain}"
+}
+
+# --- token retrieval, OS-switched (D1: OS is a function, not a binary axis) ---
+# arg1 = email. Echoes token or dies.
+get_token() {
+  local email="$1"
+  case "$CFG_TOKEN_SRC" in
+    keychain)
+      security find-generic-password -s "$KEYCHAIN_SERVICE" -a "$email" -w 2>/dev/null \
+        || die "no keychain entry for service=$KEYCHAIN_SERVICE account=$email" ;;
+    secret-tool)   # Linux (libsecret)
+      secret-tool lookup service "$KEYCHAIN_SERVICE" account "$email" 2>/dev/null \
+        || die "no secret-tool entry for service=$KEYCHAIN_SERVICE account=$email" ;;
+    env)
+      [ -n "${PR_TOKEN:-}" ] || die "token_src=env but \$PR_TOKEN is empty"
+      printf '%s' "$PR_TOKEN" ;;
+    *) die "not-yet-supported: token_src=$CFG_TOKEN_SRC" ;;
+  esac
+}
+
+# --- arg parse (common flags across all providers) ---
+pr_parse_args() {
+  TITLE=""; BODY=""; BODY_FILE=""; SOURCE=""; DEST=""; REPO=""
+  DRAFT="false"; CLOSE_SOURCE="false"; NO_REVIEWERS="false"; EMAIL_ARG=""
+  EXTRA_REVIEWERS=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --title)         TITLE="$2"; shift 2 ;;
+      --body)          BODY="$2"; shift 2 ;;
+      --body-file)     BODY_FILE="$2"; shift 2 ;;
+      --source)        SOURCE="$2"; shift 2 ;;
+      --dest|--target) DEST="$2"; shift 2 ;;
+      --repo)          REPO="$2"; shift 2 ;;
+      --draft)         DRAFT="true"; shift ;;
+      --close-source)  CLOSE_SOURCE="true"; shift ;;
+      --reviewer)      EXTRA_REVIEWERS+=("$2"); shift 2 ;;
+      --no-reviewers)  NO_REVIEWERS="true"; shift ;;
+      --email)         EMAIL_ARG="$2"; shift 2 ;;
+      -h|--help)       sed -n '2,20p' "$0"; exit 0 ;;
+      *) die "unknown flag: $1" ;;
+    esac
+  done
+  [ -n "$TITLE" ] || die "--title required"
+  if [ -n "$BODY_FILE" ]; then
+    [ -f "$BODY_FILE" ] || die "body file not found: $BODY_FILE"
+    BODY="$(cat "$BODY_FILE")"
+  fi
+}
+
+# --- git-derived defaults: SOURCE, DEST, REPO ---
+# REPO slug parse is generic (strip host + .git) — works for all providers.
+pr_git_defaults() {
+  if [ -z "$SOURCE" ]; then
+    SOURCE="$(git rev-parse --abbrev-ref HEAD)"
+    [ "$SOURCE" = "HEAD" ] && die "detached HEAD — pass --source"
+  fi
+  if [ -z "$DEST" ]; then
+    DEST="$(git config --get "branch.${SOURCE}.bbprBase" 2>/dev/null || true)"
+    [ -n "$DEST" ] && echo "${PR_CMD:-pr}: using saved base (branch.${SOURCE}.bbprBase = ${DEST})" >&2
+  fi
+  [ -n "$DEST" ] || die "--dest required (no saved branch.${SOURCE}.bbprBase)"
+  if [ -z "$REPO" ]; then
+    local url
+    url="$(git remote get-url origin 2>/dev/null)" || die "no origin remote"
+    # generic: drop scp-style git@HOST: or https://HOST/ prefix and trailing .git
+    REPO="$(echo "$url" | sed -E 's#^git@[^:]+:##; s#^https?://[^/]+/##; s#\.git$##')"
+    [[ "$REPO" == */* ]] || die "could not parse repo from $url"
+  fi
+}
+
+# --- creds: email precedence + token via OS ---
+pr_resolve_creds() {
+  # --email > $BB_EMAIL > git config bbpr.email > config email > keychain acct
+  EMAIL="$EMAIL_ARG"
+  [ -n "$EMAIL" ] || EMAIL="${BB_EMAIL:-}"
+  [ -n "$EMAIL" ] || EMAIL="$(git config bbpr.email 2>/dev/null || true)"
+  [ -n "$EMAIL" ] || EMAIL="${CFG_EMAIL:-}"
+  [ -n "$EMAIL" ] || die "no email resolved (set config email or pass --email)"
+  TOKEN="$(get_token "$EMAIL")"
+}
+
+# --- reviewer roster: work-dir file (shared across worktrees) then global fallbacks ---
+pr_load_reviewers() {
+  DEFAULT_REVIEWERS=()
+  local file="${BBPR_REVIEWERS:-}"
+  if [ -z "$file" ]; then
+    local slug; slug="$(echo "$REPO" | tr '/' '-')"      # workspace/slug -> workspace-slug
+    # main repo root, shared across worktrees: git-common-dir/.. (empty if git call fails)
+    local mainroot; mainroot="$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." 2>/dev/null && pwd)"
+    for cand in \
+      ${mainroot:+"$mainroot/.pr-reviewers.txt"} \
+      "$HOME/.config/pr/reviewers/${slug}.txt" \
+      "$HOME/.config/bbpr/bbpr-reviewers.txt"; do          # legacy fallback
+      [ -f "$cand" ] && { file="$cand"; break; }
+    done
+  fi
+  if [ -n "$file" ] && [ -f "$file" ]; then
+    local line uuid
+    while IFS= read -r line; do
+      uuid="${line%%#*}"; uuid="${uuid//[[:space:]]/}"
+      [ -n "$uuid" ] && DEFAULT_REVIEWERS+=("$uuid")
+    done < "$file"
+  else
+    echo "${PR_CMD:-pr}: WARN no reviewer roster for $REPO — none attached" >&2
+  fi
+  # merge defaults + --reviewer extras unless --no-reviewers
+  FINAL_REVIEWERS=()
+  if [ "$NO_REVIEWERS" != "true" ]; then
+    [ "${#DEFAULT_REVIEWERS[@]}" -gt 0 ] && FINAL_REVIEWERS+=("${DEFAULT_REVIEWERS[@]}")
+    [ "${#EXTRA_REVIEWERS[@]}" -gt 0 ] && FINAL_REVIEWERS+=("${EXTRA_REVIEWERS[@]}")
+  fi
+  return 0   # never let a false &&-guard above abort the caller under `set -e`
+}
+
+# --- persist resolved base for next run ---
+pr_save_base() {
+  git config "branch.${SOURCE}.bbprBase" "$DEST" 2>/dev/null \
+    && echo "${PR_CMD:-pr}: saved branch.${SOURCE}.bbprBase = ${DEST}" >&2
+  return 0   # base-save is best-effort; never abort the binary on failure
+}
+
+# --- orchestrate everything a provider needs before its POST ---
+pr_common_init() {
+  pr_load_config
+  pr_parse_args "$@"
+  pr_git_defaults
+  pr_resolve_creds
+  pr_load_reviewers
+}

package/assets/skill/pr.md

@@ -0,0 +1,157 @@
+---
+description: Create a pull request for the current branch (provider auto-detected)
+argument-hint: [base-branch] [draft]
+model: sonnet
+---
+
+Create a pull request for the current branch. Provider (Bitbucket / GitHub / GitLab) is
+auto-detected from the git remote; the matching binary (`bbpr` / `ghpr` / `glpr`) is invoked.
+Convention (title pattern, ticket regex, PR template) comes from `~/.config/pr/config`.
+
+Installed by `npx @nvice-r/pr-commands`. If setup is missing, this command STOPS and tells the
+user to run the installer — it never guesses config (D8: hard fail, no hardcoded fallback).
+
+If `$ARGUMENTS` starts with `help`/`-help`/`--help` (case-insensitive), print the **Help** block and stop.
+
+## Help (`/pr help`)
+
+```
+/pr — provider-agnostic PR helper (@nvice-r/pr-commands)
+
+USAGE
+  /pr [base-branch] [draft]   Create a PR for the current branch (default).
+  /pr help                    Show this help.
+
+CREATE
+  base-branch   Any arg containing "/". If omitted, inferred from closest ancestor
+                remote branch (saved per-branch after first run).
+  draft         Create as draft. Otherwise opens ready (asks to confirm).
+
+CONFIG        ~/.config/pr/config  (os, token_src, email, convention)
+PROVIDER      auto from `git remote get-url origin` -> bbpr | ghpr | glpr
+REVIEWERS     ~/.config/pr/reviewers/<workspace>-<slug>.txt (per-repo, global location)
+SETUP         npx @nvice-r/pr-commands
+```
+
+## Step 0 — verify install (HARD FAIL, no fallback)
+
+Run the checks; if any fails, STOP and tell the user to run `npx @nvice-r/pr-commands` (name the
+missing piece). Do NOT improvise config or reviewers.
+
+```bash
+# a. config present?
+CFG="${PR_CONFIG:-$HOME/.config/pr/config}"
+[ -f "$CFG" ] || { echo "MISSING config: $CFG"; }
+
+# b. detect provider from remote
+URL="$(git remote get-url origin 2>/dev/null)" || echo "no origin remote"
+case "$URL" in
+  *bitbucket.org*) PROVIDER=bitbucket; BIN=bbpr ;;
+  *github.com*)    PROVIDER=github;    BIN=ghpr ;;
+  *gitlab.com*)    PROVIDER=gitlab;    BIN=glpr ;;
+  *) echo "unknown provider for remote: $URL" ;;
+esac
+
+# c. matching binary installed?
+command -v "$BIN" >/dev/null 2>&1 || echo "MISSING binary: $BIN (run installer, or provider not yet supported)"
+```
+
+- config missing → STOP: "run `npx @nvice-r/pr-commands`".
+- provider unknown → STOP: only bitbucket/github/gitlab supported.
+- `$BIN` = `ghpr`/`glpr` and not installed → STOP: "provider not yet supported (macOS+Bitbucket only for now)". (D6 stub.)
+- all pass → continue.
+
+## Step 1 — gather context (parallel)
+- `git rev-parse --abbrev-ref HEAD` — source branch (CURR)
+- `git config --get branch.<CURR>.bbprBase` — saved base, if any
+- `git log --oneline -20`
+- read `convention=` from `$CFG` (default `trueid` if unset — but config presence already enforced in Step 0)
+
+## Step 2 — determine base branch (priority)
+a. `$1` (any arg containing `/`) → use it.
+b. else `branch.<CURR>.bbprBase` from git config → use silently.
+c. else infer — smallest non-zero `<ref>..HEAD` distance where `<ref>` is an ancestor of HEAD:
+   ```bash
+   for ref in $(git for-each-ref --format='%(refname:short)' refs/remotes/origin | grep -v "^origin/<CURR>$"); do
+     if git merge-base --is-ancestor "$ref" HEAD 2>/dev/null; then
+       ahead=$(git rev-list --count "$ref"..HEAD)
+       [ "$ahead" -gt 0 ] && echo "$ahead $ref"
+     fi
+   done | sort -n | head -5
+   ```
+   Propose smallest-`ahead` candidate; confirm. Do NOT auto-pick a naming-pattern match — a
+   stacked PR on another in-flight ticket branch is common. Ties or all >20 ahead → ask.
+d. still ambiguous → ask.
+
+The binary auto-saves the resolved base to `branch.<CURR>.bbprBase` on success.
+
+## Step 3 — build diff context
+`git log <base>..HEAD --oneline` · `git diff --stat <base>..HEAD`. Multiple commits → summarize each.
+
+## Step 3.5 — split advisory (size gate, advisory, never blocks)
+Compute from `git diff --numstat <base>..HEAD`: file count, churn Σ(add+del), distinct modules.
+Flag if `>25 files` OR `>600 churn` OR `>4 modules`. Under → silent, continue. Over → cluster the
+diff into seams, detect coupling (shared file/symbol → stacked; disjoint → independent; interleaved
+→ one atomic PR), present metrics + seam table, then `AskUserQuestion`: proceed-as-one /
+split (`guard_cmd pr-split`, degrade if absent) / adjust-threshold. Never auto-split.
+
+## Step 4 — draft title (from config, authoritative)
+
+Read `title_pattern=` and `ticket_regex=` directly from `$CFG` — the installer wrote concrete,
+possibly user-edited values, so DO NOT reconstruct them from a preset table. Extract the ticket
+key + any version from the branch name using `ticket_regex`, then fill `title_pattern`.
+
+`convention=` is only a behavior label (drives the trueid body rules in Step 5). Example
+(trueid): branch `feature/<ver>/SC-XXXX-...`, pattern `[<ver>] Feature/<ver>/SC-XXXX <desc>` →
+kebab suffix becomes spaced lowercase `<desc>`.
+
+## Step 5 — draft body (from config)
+
+Read `template_sections=` from `$CFG` (pipe-separated) and render each as an `## <section>`
+heading. These are authoritative — the installer wrote them (preset seed, possibly edited).
+
+**trueid template rules** (only when `convention=trueid`):
+- `What Happened` = summary prose only — no file bullets, no commit-subject line.
+- Changed-file detail lives under `Insight`.
+- 3+ files sharing a parent dir → state common root once ("Under `<root>`:") + flat list of joined
+  relative paths (no nested bullets). Android module root → Gradle path `:features:<x>:<y>`, leaf
+  bullets = basenames only. Skip boilerplate (`settings.gradle.kts` include, empty manifest, lockfiles).
+- Unrelated areas → full paths per bullet, no common-root statement.
+- `Proof of Work` empty unless user gives screenshots/links.
+
+For non-trueid presets, fill sections with a plain summary + changed-file list; no Gradle shorthand.
+
+## Step 6 — write body to `/tmp/pr-body.md` (Write tool).
+
+## Step 7 — confirm. Show proposed title + base + body + resolved provider/binary. WAIT. PR creation is user-visible; never silent.
+
+## Step 8 — create. Run the detected binary (append `--draft` only if draft chosen):
+```bash
+<BIN> --title "<title>" --body-file /tmp/pr-body.md --dest "<base>" [--draft]
+```
+Always ask open-vs-draft before creating unless `draft` was passed. The binary attaches the
+per-repo reviewer roster automatically; `--no-reviewers` skips, `--reviewer <id>` appends.
+
+## Step 9 — print final PR URL + reviewer count from binary output. On error, surface raw response.
+
+## Step 10 — offer Jira sync (guarded, optional).
+Reuse ticket key from Step 4. If none, skip. `guard_cmd jira-update`; if absent, just print URL + stop.
+If present, `AskUserQuestion`: sync now → `/jira-update <KEY>`, or skip (print reminder).
+
+## Cross-command guard
+Sibling commands (`/pr-split`, `/jira-update`) are optional — a teammate may not have them. Before
+invoking any, confirm it exists; if absent, degrade gracefully (one-line note). Reusable check:
+```bash
+guard_cmd() {  # usage: guard_cmd pr-split → prints path or "no-<cmd>"
+  ls "$PWD/.claude/commands/$1.md" "$HOME/.claude/commands/$1.md" \
+     "$PWD/.claude/skills/$1/SKILL.md" "$HOME/.claude/skills/$1/SKILL.md" 2>/dev/null | head -1 \
+    || echo "no-$1"
+}
+```
+
+## Notes
+- Does NOT push — assumes branch pushed. Unpushed commits ahead of upstream → warn + ask.
+- Provider/token/convention all from config + remote — NO hardcoded team values here (D3/D4).
+- Verify worktree before any split branch work (`git symbolic-ref --short HEAD` + `git worktree list`);
+  background restacks can move branches mid-turn.
+- Caveman mode applies to replies — but PR title/body must be normal English.

package/install.js

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+// @nvice-r/pr-commands installer. Zero external deps (Node >=16 builtins only).
+// Wizard: detect OS + provider, pick reviewers + convention, write config/roster,
+// install binaries -> ~/.local/bin, copy /pr skill -> ~/.claude/commands.
+//
+// Flags: --dir <path>  --provider <p>  --all  --yes  --dry-run  --help
+
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+const readline = require('readline');
+const { execFileSync } = require('child_process');
+
+const HOME = os.homedir();
+const PKG = __dirname;
+const ASSETS = path.join(PKG, 'assets');
+const BACK = Symbol('back');   // returned by a prompt when the user wants the previous step
+
+const PROVIDERS = {
+  bitbucket: { bin: 'bbpr', host: 'bitbucket.org', keychainSvc: 'bitbucket-api-token', ready: true },
+  github:    { bin: 'ghpr', host: 'github.com',    keychainSvc: 'github-api-token',    ready: false },
+  gitlab:    { bin: 'glpr', host: 'gitlab.com',     keychainSvc: 'gitlab-api-token',    ready: false },
+};
+const CONVENTIONS = ['trueid', 'conventional', 'github-default', 'custom'];
+// Concrete, editable defaults per preset. Whatever the user confirms is written to config,
+// so `custom` is just "a preset with blank seeds" — same edit flow for every choice.
+const PRESET_DEFS = {
+  trueid:           { title_pattern: '[<ver>] Feature/<ver>/SC-XXXX <desc>', ticket_regex: 'SC-\\d+',    template_sections: 'What Happened|Insight|Proof of Work' },
+  conventional:     { title_pattern: '<type>(<scope>): <desc>',              ticket_regex: '[A-Z]+-\\d+', template_sections: 'Summary|Changes|Testing' },
+  'github-default': { title_pattern: '<desc> (#<issue>)',                    ticket_regex: '#\\d+',       template_sections: 'Summary|Test plan' },
+  custom:           { title_pattern: '',                                     ticket_regex: '',            template_sections: '' },
+};
+
+// ---- arg parse ----
+const argv = process.argv.slice(2);
+const flags = { dir: null, provider: null, all: false, yes: false, dryRun: false };
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--help' || a === '-h') { printHelp(); process.exit(0); }
+  else if (a === '--dir') flags.dir = argv[++i];
+  else if (a === '--provider') flags.provider = argv[++i];
+  else if (a === '--all') flags.all = true;
+  else if (a === '--yes' || a === '-y') flags.yes = true;
+  else if (a === '--dry-run') flags.dryRun = true;
+  else { console.error(`unknown flag: ${a}`); process.exit(1); }
+}
+
+function printHelp() {
+  console.log(`@nvice-r/pr-commands installer
+
+  npx @nvice-r/pr-commands [flags]
+
+  --dir <path>       Repo to configure (default: cwd)
+  --provider <p>     Force bitbucket|github|gitlab (default: detect from remote)
+  --all              Install all provider binaries (default: only the detected one)
+  --yes              Accept defaults, no prompts (reviewers=all, convention=trueid)
+  --dry-run          Print planned actions, write nothing
+  --help             This help`);
+}
+
+// ---- helpers ----
+// Each text prompt gets its OWN terminal-mode readline, closed right after. Never share one
+// readline across prompts + raw-mode selectors — the terminal modes corrupt each other
+// (arrows leak into the line as literal ^[[A escape codes after a selector runs).
+const ask = (q) => new Promise((res) => {
+  const r = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  r.question(q, (a) => { r.close(); res(a.trim()); });
+});
+// Editable pre-filled default: edit the shown value or hit enter to keep it.
+// `:b` (or `:back`) returns BACK; empty keeps the default.
+const askPrefill = (q, def, allowBack = true) => new Promise((res) => {
+  const r = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  r.question(q, (a) => {
+    r.close();
+    const t = a.trim();
+    // value is pre-filled, so `:b` typed at the end appends → match as a suffix, not just equality
+    if (allowBack && (t.endsWith(':b') || t.endsWith(':back'))) return res(BACK);
+    res((t || def || '').trim());
+  });
+  if (def && process.stdin.isTTY) r.write(def);   // inject editable text
+});
+
+// Interactive checklist (↑/↓ move · space toggle · a all · n none · enter confirm).
+// Zero-dep raw-mode TTY. Returns array of selected indices. items: [{label}].
+// allDefault=true pre-selects everything. Falls back to select-all on a non-TTY.
+function multiSelect(title, items, allDefault = true, preIdx = null) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY || items.length === 0) {
+      resolve(preIdx || (allDefault ? items.map((_, i) => i) : []));
+      return;
+    }
+    const sel = items.map((_, i) => (preIdx ? preIdx.includes(i) : allDefault));
+    let cur = 0, top = 0;
+    const VIEW = Math.min(items.length, 20); // visible rows; longer lists scroll/page through this window (tune this)
+    const LINES = VIEW + 3;                 // title + VIEW rows + counter + hint (fixed → cursor-up math stays correct)
+    const out = process.stdout;
+    const render = (first) => {
+      if (cur < top) top = cur;                          // scrolled above window → page up
+      else if (cur >= top + VIEW) top = cur - VIEW + 1;  // scrolled below → page down
+      if (!first) out.write(`\x1b[${LINES}F`); // up LINES, to col 0
+      out.write(`\x1b[J`); // clear from cursor down
+      out.write(`\r\x1b[K  ${title}\n`);
+      for (let r = 0; r < VIEW; r++) {
+        const i = top + r;
+        const it = items[i];
+        const box = sel[i] ? '[x]' : '[ ]';
+        const arrow = i === cur ? '\x1b[36m>\x1b[0m' : ' ';
+        const lbl = i === cur ? `\x1b[36m${it.label}\x1b[0m` : it.label;
+        out.write(`\r\x1b[K  ${arrow} ${box} ${lbl}\n`);
+      }
+      const nsel = sel.filter(Boolean).length;
+      const range = items.length > VIEW ? `${top + 1}-${Math.min(top + VIEW, items.length)}/${items.length}` : `${items.length}`;
+      out.write(`\r\x1b[K  \x1b[2m${range} shown · ${nsel} selected\x1b[0m\n`);
+      out.write(`\r\x1b[K  \x1b[2m↑/↓ move · space toggle · a all · n none · b back · enter confirm\x1b[0m\n`);
+    };
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    render(true);
+    const onData = (buf) => {
+      const k = buf.toString();
+      if (k === '\x03') { cleanup(); process.exit(130); }       // ctrl-c
+      else if (k === 'b') { cleanup(); resolve(BACK); return; } // b = back (NOT esc — esc is the arrow-key prefix)
+      else if (k === '\x1b[A' || k === 'k') cur = (cur - 1 + items.length) % items.length;
+      else if (k === '\x1b[B' || k === 'j') cur = (cur + 1) % items.length;
+      else if (k === ' ') sel[cur] = !sel[cur];
+      else if (k === 'a') sel.fill(true);
+      else if (k === 'n') sel.fill(false);
+      else if (k === '\r' || k === '\n') {
+        cleanup();
+        resolve(items.map((_, i) => i).filter((i) => sel[i]));
+        return;
+      }
+      render(false);
+    };
+    function cleanup() {
+      process.stdin.removeListener('data', onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+    process.stdin.on('data', onData);
+  });
+}
+
+// Single-select list (↑/↓ move · enter pick). Returns chosen index. Non-TTY → def.
+function multiSelectOne(title, labels, def = 0) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY || labels.length === 0) { resolve(def); return; }
+    let cur = def;
+    const out = process.stdout;
+    const render = (first) => {
+      if (!first) out.write(`\x1b[${labels.length + 2}F`);
+      out.write(`\x1b[J`);
+      out.write(`\r\x1b[K  ${title}\n`);
+      labels.forEach((l, i) => {
+        const arrow = i === cur ? '\x1b[36m>\x1b[0m' : ' ';
+        out.write(`\r\x1b[K  ${arrow} ${i === cur ? `\x1b[36m${l}\x1b[0m` : l}\n`);
+      });
+      out.write(`\r\x1b[K  \x1b[2m↑/↓ move · b back · enter select\x1b[0m\n`);
+    };
+    process.stdin.setRawMode(true); process.stdin.resume(); render(true);
+    const onData = (buf) => {
+      const k = buf.toString();
+      if (k === '\x03') { cleanup(); process.exit(130); }
+      else if (k === 'b') { cleanup(); resolve(BACK); return; } // b = back (NOT esc — esc is the arrow-key prefix)
+      else if (k === '\x1b[A' || k === 'k') cur = (cur - 1 + labels.length) % labels.length;
+      else if (k === '\x1b[B' || k === 'j') cur = (cur + 1) % labels.length;
+      else if (k === '\r' || k === '\n') { cleanup(); resolve(cur); return; }
+      render(false);
+    };
+    function cleanup() {
+      process.stdin.removeListener('data', onData);
+      process.stdin.setRawMode(false); process.stdin.pause();
+    }
+    process.stdin.on('data', onData);
+  });
+}
+
+function log(...a) { console.log(...a); }
+function printLegend() {
+  console.log('  Placeholders (used in title_pattern; filled by /pr from the branch):');
+  console.log('    \x1b[2m<ver>     branch version    e.g. 2.3.0\x1b[0m');
+  console.log('    \x1b[2m<desc>    description       from branch suffix / commits\x1b[0m');
+  console.log('    \x1b[2m<ticket>  ticket key        matched by ticket_regex, e.g. SC-5424\x1b[0m');
+  console.log('    \x1b[2m<type>    conventional type feat | fix | chore | ...\x1b[0m');
+  console.log('    \x1b[2m<scope>   conventional scope e.g. auth\x1b[0m');
+  console.log('    \x1b[2m<issue>   issue number      e.g. 42\x1b[0m');
+  console.log('  \x1b[2menter keeps shown value · append :b then enter to go back\x1b[0m\n');
+}
+function sh(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { encoding: 'utf8', ...opts }).trim();
+}
+function shSafe(cmd, args, opts = {}) {
+  // probe variant: swallow the child's stderr (e.g. git's "fatal: not a git repository")
+  try { return sh(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'], ...opts }); } catch { return null; }
+}
+function writeFile(p, content, mode) {
+  if (flags.dryRun) { log(`  [dry-run] write ${p}`); return; }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+  if (mode) fs.chmodSync(p, mode);
+  log(`  wrote ${p}`);
+}
+// Main repo root, shared across worktrees: git-common-dir points at the main .git
+// even from a linked worktree; its parent is the main checkout root. gitCommonDir
+// may be relative ('.git') or absolute ('/main/.git') — path.resolve handles both.
+function mainRepoRoot(wd) {
+  const gcd = shSafe('git', ['-C', wd, 'rev-parse', '--git-common-dir']);
+  return gcd ? path.resolve(wd, gcd, '..') : null;
+}
+// Depth-limited scan for git repos beneath a non-repo dir. Stops descending once a
+// repo is found (no nested-repo noise); skips dotdirs + node_modules; caps results.
+function scanGitRepos(root, maxDepth = 3, cap = 50) {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || found.length >= cap) return;
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (ents.some((e) => e.name === '.git')) { found.push(dir); return; }  // this IS a repo
+    for (const e of ents) {
+      if (!e.isDirectory() || e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      walk(path.join(dir, e.name), depth + 1);
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+
+// ---- provider detection ----
+function detectProvider(remoteUrl) {
+  if (flags.provider) return flags.provider;
+  for (const [name, cfg] of Object.entries(PROVIDERS)) {
+    if (remoteUrl && remoteUrl.includes(cfg.host)) return name;
+  }
+  return null;
+}
+function parseSlug(remoteUrl) {
+  return remoteUrl
+    .replace(/^git@[^:]+:/, '')
+    .replace(/^https?:\/\/[^/]+\//, '')
+    .replace(/\.git$/, '');
+}
+
+// ---- keychain (macOS) ----
+function keychainAccounts(svc) {
+  if (os.platform() !== 'darwin') return [];
+  // dump-keychain is noisy + may prompt; instead try find-generic-password for the service
+  const out = shSafe('security', ['find-generic-password', '-s', svc]);
+  if (!out) return [];
+  const m = out.match(/"acct"<blob>="([^"]*)"/);
+  return m ? [m[1]] : [];
+}
+function keychainToken(svc, acct) {
+  return shSafe('security', ['find-generic-password', '-s', svc, '-a', acct, '-w']);
+}
+
+// ---- reviewer fetch (Bitbucket default-reviewers) ----
+function httpsGetJson(url, auth) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const opts = { method: 'GET', headers: { 'User-Agent': 'pr-commands' } };
+    if (auth) opts.headers.Authorization = 'Basic ' + Buffer.from(auth).toString('base64');
+    https.get(u, opts, (res) => {
+      let data = '';
+      res.on('data', (c) => (data += c));
+      res.on('end', () => {
+        try { resolve({ status: res.statusCode, json: JSON.parse(data) }); }
+        catch { resolve({ status: res.statusCode, json: null }); }
+      });
+    }).on('error', reject);
+  });
+}
+async function fetchSelfUuid(email, token) {
+  const { status, json } = await httpsGetJson('https://api.bitbucket.org/2.0/user', `${email}:${token}`);
+  if (status !== 200 || !json) return null;
+  return json.uuid || null;
+}
+async function fetchBitbucketReviewers(slug, email, token, selfUuid) {
+  const PAGELEN = 100; // max Bitbucket page; loop follows `next` if a repo ever exceeds it
+  let url = `https://api.bitbucket.org/2.0/repositories/${slug}/default-reviewers?pagelen=${PAGELEN}`;
+  const out = [];
+  let page = 0;
+  while (url) {
+    const { status, json } = await httpsGetJson(url, `${email}:${token}`);
+    if (status !== 200 || !json || !json.values) return page ? out : null;   // page>0 → return what we got
+    page++;
+    for (const v of json.values) out.push({ uuid: v.uuid, name: v.display_name || v.nickname || v.uuid });
+    url = json.next || null;   // Bitbucket gives a full next-page URL when more remain
+  }
+  const filtered = selfUuid ? out.filter((r) => r.uuid !== selfUuid) : out;
+  log(`  fetched ${out.length} default-reviewer(s) across ${page} page(s)` +
+      (selfUuid && out.length !== filtered.length ? ` — excluded yourself` : ''));
+  return filtered;
+}
+
+// ---- main ----
+(async () => {
+  // --- environment (computed once, not a back-able step; shown in every screen header) ---
+  const platform = os.platform();
+  const cfgOs = platform === 'darwin' ? 'macos' : platform === 'linux' ? 'linux' : platform;
+  const tokenSrc = cfgOs === 'macos' ? 'keychain' : 'env';
+
+  const st = { conv: {} };   // accumulates across steps; survives back/forward
+
+  // Breadcrumb of decisions committed BEFORE `stage` (so re-entering a step never shows its own value).
+  const crumb = (stage) => {
+    const L = [];
+    if (stage > 0 && st.workDir) {
+      L.push(`  \x1b[32m✓\x1b[0m work dir    ${st.workDir}`);
+      L.push(`  \x1b[32m✓\x1b[0m provider    ${st.provider} (${st.slug}) → ${st.pcfg.bin}`);
+      L.push(`  \x1b[32m✓\x1b[0m auth        ${st.email || '(none)'}${st.token ? ' · token ok' : ' · no token'}`);
+    }
+    if (stage > 1 && st.chosen) L.push(`  \x1b[32m✓\x1b[0m reviewers   ${st.chosen.length} selected`);
+    if (stage > 2 && st.convention) L.push(`  \x1b[32m✓\x1b[0m convention  ${st.convention}`);
+    return L;
+  };
+  // Full-screen redraw: wipe, reprint header + breadcrumb + active-step marker. No accumulation on back.
+  const screen = (stage, active) => {
+    if (process.stdout.isTTY) process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+    console.log('@nvice-r/pr-commands installer' + (flags.dryRun ? '  (dry-run)' : ''));
+    console.log(`  os=${cfgOs}  token_src=${tokenSrc}` + (cfgOs !== 'macos' ? '  \x1b[33m(only macOS fully supported)\x1b[0m' : ''));
+    const c = crumb(stage);
+    if (c.length) { console.log(''); c.forEach((l) => console.log(l)); }
+    console.log(`\n▶ ${active}`);
+  };
+
+  // --- back-able steps: each returns BACK to revisit the previous step, else falls through ---
+
+  // Work dir + everything derived from it (provider/slug/identity/token).
+  const sWorkDir = async () => {
+    screen(0, 'Work directory');
+    let wd;
+    if (flags.dir || flags.yes) wd = path.resolve(flags.dir || process.cwd());
+    else {
+      const a = await askPrefill('  repo path: ', st.workDir || process.cwd());
+      if (a === BACK) return BACK;   // first step — driver just stays here
+      wd = path.resolve(a);
+    }
+    log(`  ${wd}`);
+    if (!shSafe('git', ['-C', wd, 'rev-parse', '--git-dir'])) {
+      log('  not a git repo here — scanning up to 3 levels below for repos…');
+      const repos = scanGitRepos(wd);
+      if (repos.length === 0) {
+        console.error(`  ERROR: no git repo at ${wd}, and none found within 3 levels.`);
+        console.error('  Point --dir at a git repo, or cd into one and re-run.');
+        process.exit(1);
+      }
+      if (flags.yes) { wd = repos[0]; log(`  picked ${wd}`); }
+      else {
+        const labels = repos.map((r) => path.relative(wd, r) || '.');
+        const idx = await multiSelectOne(`Found ${repos.length} repo(s) under ${wd} — pick one:`, labels, 0);
+        if (idx === BACK) return BACK;
+        wd = repos[idx];
+        screen(0, 'Work directory');   // repaint (selector left its own frame)
+        log(`  ${wd}`);
+      }
+    }
+    const remoteUrl = shSafe('git', ['-C', wd, 'remote', 'get-url', 'origin']);
+    if (!remoteUrl) { console.error('  ERROR: no git origin remote'); process.exit(1); }
+    const provider = detectProvider(remoteUrl);
+    if (!provider) { console.error(`  ERROR: could not detect provider from ${remoteUrl}`); process.exit(1); }
+    const pcfg = PROVIDERS[provider];
+    const slug = parseSlug(remoteUrl);
+    log(`  remote: ${remoteUrl}\n  provider=${provider}  slug=${slug}  binary=${pcfg.bin}`);
+    if (!pcfg.ready) { console.error(`  ERROR: ${provider} not yet supported (macOS+Bitbucket only). Aborting.`); process.exit(1); }
+    // identity + token (derived from provider)
+    let email = '';
+    const accts = keychainAccounts(pcfg.keychainSvc);
+    if (accts.length === 1) { email = accts[0]; log(`  email (keychain): ${email}`); }
+    else if (!flags.yes) { const e = await ask('  Atlassian email: '); email = e || (accts[0] || ''); }
+    else if (accts.length) email = accts[0];
+    const token = email ? keychainToken(pcfg.keychainSvc, email) : null;
+    if (!token) {
+      log(`  WARN: no keychain token for ${pcfg.keychainSvc}/${email || '(none)'} — reviewers can't auto-fetch`);
+      log(`    security add-generic-password -s ${pcfg.keychainSvc} -a ${email || 'you@example.com'} -w '<api-token>'`);
+    } else log('  token: found');
+    if (st.slug !== slug) st.revs = undefined;   // invalidate reviewer cache if repo changed
+    const mroot = mainRepoRoot(wd) || wd;        // shared across worktrees; roster lives here
+    if (mroot !== wd) log(`  worktree detected → roster shared at main root: ${mroot}`);
+    Object.assign(st, { workDir: wd, mainRoot: mroot, remoteUrl, provider, pcfg, slug, email, token });
+  };
+
+  const sReviewers = async () => {
+    screen(1, 'Reviewers');
+    st.chosen = st.chosen || [];
+    if (!(st.token && st.email)) { log('  skipped (no token) — edit the roster later.'); st.chosen = []; return; }
+    if (st.selfUuid === undefined) st.selfUuid = await fetchSelfUuid(st.email, st.token);
+    if (st.revs === undefined) st.revs = await fetchBitbucketReviewers(st.slug, st.email, st.token, st.selfUuid);
+    const revs = st.revs;
+    if (!revs) { log('  WARN: could not fetch default-reviewers. Roster left empty.'); st.chosen = []; return; }
+    if (revs.length === 0) { log('  repo has no default reviewers. Roster left empty.'); st.chosen = []; return; }
+    if (flags.yes) { st.chosen = revs; st.chosenIdx = revs.map((_, i) => i); log(`  selected all ${revs.length}`); return; }
+    const picked = await multiSelect(
+      `Reviewers for ${st.slug} (default: all):`,
+      revs.map((r) => ({ label: r.name })), true, st.chosenIdx || null,
+    );
+    if (picked === BACK) return BACK;
+    st.chosenIdx = picked;
+    st.chosen = picked.map((i) => revs[i]);
+    log(`  chosen: ${st.chosen.length}`);
+  };
+
+  const sPreset = async () => {
+    screen(2, 'Convention — preset');
+    if (flags.yes) {
+      st.convention = st.convention || 'trueid';
+      st.conv = { ...PRESET_DEFS[st.convention] };
+      return;
+    }
+    const idx = Math.max(0, CONVENTIONS.indexOf(st.convention || 'trueid'));
+    const pick = await multiSelectOne('Convention preset:', CONVENTIONS, idx);
+    if (pick === BACK) return BACK;
+    const chosenConv = CONVENTIONS[pick];
+    if (chosenConv !== st.convention) {           // reseed fields only when preset actually changes
+      st.convention = chosenConv;
+      st.conv = { ...PRESET_DEFS[chosenConv] };
+    }
+  };
+
+  const editField = (label, key) => async () => {
+    screen(3, `Convention — ${key}`);
+    printLegend();
+    const v = await askPrefill(`  ${label} `, st.conv[key] ?? PRESET_DEFS[st.convention][key]);
+    if (v === BACK) return BACK;
+    st.conv[key] = v;
+  };
+
+  const steps = flags.yes
+    ? [sWorkDir, sReviewers, sPreset]
+    : [sWorkDir, sReviewers, sPreset,
+       editField('title_pattern:    ', 'title_pattern'),
+       editField('ticket_regex:     ', 'ticket_regex'),
+       editField('template_sections:', 'template_sections')];
+
+  let i = 0;
+  while (i < steps.length) {
+    const r = await steps[i]();
+    if (r === BACK) i = Math.max(0, i - 1);
+    else i++;
+  }
+
+  // --- install ---
+  screen(3, 'Install');
+  const { slug, pcfg, email, convention, conv, chosen } = st;
+  let cfg = `os=${cfgOs}\ntoken_src=${tokenSrc}\nemail=${email}\nconvention=${convention}\n`;
+  if (conv.title_pattern)     cfg += `title_pattern=${conv.title_pattern}\n`;
+  if (conv.ticket_regex)      cfg += `ticket_regex=${conv.ticket_regex}\n`;
+  if (conv.template_sections) cfg += `template_sections=${conv.template_sections}\n`;
+  writeFile(path.join(HOME, '.config/pr/config'), cfg, 0o600);
+  // Roster lives in the work dir (main repo root — shared across worktrees). Editable
+  // in place; pr-common.sh finds it first, falling back to the global path.
+  const roster = chosen.map((r) => `${r.uuid}  # ${r.name}`).join('\n') + (chosen.length ? '\n' : '');
+  const header = `# pr reviewers for ${slug} — {uuid}  # Name per line; blanks/# ignored. Edit freely.\n`;
+  writeFile(path.join(st.mainRoot, '.pr-reviewers.txt'), header + (roster || '# (none selected)\n'));
+  const binDir = path.join(HOME, '.local/bin');
+  const binsToInstall = flags.all
+    ? Object.values(PROVIDERS).filter((p) => p.ready).map((p) => p.bin)
+    : [pcfg.bin];
+  writeFile(path.join(binDir, 'pr-common.sh'), fs.readFileSync(path.join(ASSETS, 'bin/pr-common.sh')), 0o755);
+  for (const b of binsToInstall) {
+    const src = path.join(ASSETS, 'bin', b);
+    if (!fs.existsSync(src)) { log(`  skip ${b} (asset not present yet)`); continue; }
+    writeFile(path.join(binDir, b), fs.readFileSync(src), 0o755);
+  }
+  writeFile(path.join(HOME, '.claude/commands/pr.md'), fs.readFileSync(path.join(ASSETS, 'skill/pr.md')));
+  if (!(process.env.PATH || '').split(':').includes(binDir)) {
+    log(`\n  WARN: ${binDir} not on PATH. Add to your shell rc:`);
+    log(`    export PATH="$HOME/.local/bin:$PATH"`);
+  }
+  log('\nDone. Try:  /pr help   (in Claude Code, from ' + st.workDir + ')');
+})().catch((e) => { console.error(e); process.exit(1); });

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@nvice-r/pr-commands",
+  "version": "0.1.0",
+  "description": "Provider-agnostic PR helper for Claude Code — npx installer + bbpr/ghpr/glpr binaries + /pr skill",
+  "bin": {
+    "pr-commands": "install.js"
+  },
+  "files": [
+    "install.js",
+    "assets/"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["claude-code", "pull-request", "bitbucket", "github", "gitlab", "cli"],
+  "author": "nvice.r",
+  "license": "MIT"
+}