Add bitbucket-jira-cli skill

bitbucket-jira-cli/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: bitbucket-jira-cli
+description: Manage Bitbucket pull requests, repos and pipelines and Jira issues from the terminal with the gh-style bj CLI, which self-installs if missing.
+author: Spenhouet
+version: "1.0"
+tags:
+  - bitbucket
+  - jira
+  - atlassian
+  - cli
+  - pull-request
+---
+
+# bitbucket-jira-cli (`bj`)
+
+`bj` is `gh` for Bitbucket and Jira. The command surface mirrors the GitHub CLI:
+if you know `gh`, you know `bj`. It manages Bitbucket pull requests, repositories,
+and pipelines, plus Jira issues, from one noun-first command tree.
+
+If a command or flag is not covered here, run `bj <command> --help`; the flags
+mirror `gh` and the help is authoritative.
+
+## Install `bj` if it is missing
+
+Before running any `bj` command, make sure the CLI is on `PATH`. If `command -v
+bj` finds nothing, install it with whatever Python packaging tool is available,
+preferring an isolated, self-updating install:
+
+```bash
+if ! command -v bj >/dev/null 2>&1; then
+  if command -v uv >/dev/null 2>&1; then
+    uv tool install bitbucket-jira-cli          # isolated, self-updating (preferred)
+  elif command -v pipx >/dev/null 2>&1; then
+    pipx install bitbucket-jira-cli
+  else
+    pip install --user bitbucket-jira-cli
+  fi
+fi
+```
+
+Then verify, and fix `PATH` if the install dir is not picked up yet:
+
+```bash
+command -v bj >/dev/null 2>&1 || export PATH="$HOME/.local/bin:$PATH"  # uv/pip user bin
+bj --help >/dev/null    # confirms bj is installed and runnable
+```
+
+If none of `uv`, `pipx` or `pip` is present, install `uv` first (see the
+[uv install guide](https://docs.astral.sh/uv/getting-started/installation/)) or
+follow the [bj installation docs](https://spenhouet.github.io/bitbucket-jira-cli/installation/).
+To run `bj` once without installing it, use `uvx bitbucket-jira-cli <args>` in
+place of `bj <args>`.
+
+## Setup
+
+Authenticate once, like `gh auth login`:
+
+```bash
+bj auth login          # interactive; logs in Bitbucket and/or Jira
+bj auth status         # show who you are logged in as
+```
+
+For CI or headless agents (no interactive prompt), pass tokens instead:
+
+```bash
+export BJ_BITBUCKET_TOKEN=...   # Bitbucket API token
+export BJ_JIRA_TOKEN=...        # Jira API token
+# or: bj auth login --bitbucket --with-token < token.txt
+```
+
+## Running non-interactively (agents, scripts, CI)
+
+- Set `BJ_PROMPT_DISABLED=1` so `bj` never waits on a prompt; pass required
+  values as flags or the command fails fast with a clear error. Piped output
+  (non-TTY) already skips prompts.
+- Set `NO_COLOR=1` to drop colors and the spinner (less noise in the transcript).
+- Add `--json` for the full, raw API payload; shape it with `--jq '<expr>'`
+  (requires the `jq` binary on `PATH`).
+- Pass `--yes`/`-y` to accept confirmations (merge, close, stop).
+- Exit codes: `0` success, `1` failure (includes "not logged in"), `2` usage
+  error. Branch on these instead of parsing text.
+
+## `gh` to `bj`
+
+| `gh` | `bj` |
+| --- | --- |
+| `gh auth login` / `gh auth status` | `bj auth login` / `bj auth status` |
+| `gh pr create` | `bj pr create` |
+| `gh pr list` / `gh pr view` | `bj pr list` / `bj pr view` |
+| `gh pr checkout` / `gh pr diff` | `bj pr checkout` / `bj pr diff` |
+| `gh pr review` / `gh pr comment` | `bj pr review` / `bj pr comment` |
+| `gh pr merge` / `gh pr close` | `bj pr merge` / `bj pr close` |
+| `gh issue …` | `bj issue …` (Jira issues) |
+| `gh repo clone` / `view` / `list` | `bj repo clone` / `view` / `list` |
+| `gh run list` / `gh run view` | `bj pipeline list` / `bj pipeline view` |
+| `gh api` | `bj api` |
+| `gh browse` | `bj browse` |
+| `gh release` | `bj release` (Jira versions) |
+| `gh secret` / `gh variable` | `bj variable` (`--secured` for secrets) |
+| `gh config` | `bj config` |
+| `gh search` | `bj search` |
+| `gh alias` | `bj alias` |
+| `gh ssh-key` | `bj ssh-key` |
+| `gh status` | `bj status` |
+| `gh project` | `bj board` (Jira boards/sprints) |
+
+## Differences from `gh`
+
+- Two products behind one CLI: Bitbucket owns `pr`, `repo`, `pipeline`; Jira owns
+  `issue`. Each backend has its own token (`BJ_BITBUCKET_TOKEN`, `BJ_JIRA_TOKEN`).
+- `bj issue` targets Jira. Issue keys look like `PROJ-42`, not numbers.
+- `bj pipeline` is Bitbucket Pipelines, the analog of `gh run`.
+- `--json` emits the whole raw Bitbucket/Jira response. There is no `gh`-style
+  field list; filter with `--jq` instead.
+- `bj api` calls the Bitbucket or Jira REST API (`--backend bitbucket|jira`),
+  not a GraphQL endpoint.
+- A failed auth check exits `1` (a normal failure), where `gh` uses `4`.
+
+## Branch-key automation
+
+`bj` reads a Jira key from the current git branch (e.g. `feature/PROJ-42-thing`
+gives `PROJ-42`) and uses it automatically:
+
+- `bj pr create` fills the PR title from the ticket, links the PR to the issue,
+  and transitions the ticket to In Progress.
+- `bj pr merge` transitions the linked ticket to Done after a successful merge.
+
+Preview the effect without writing anything using `--dry-run`; skip all Jira side
+effects with `--no-jira`. If no key is found, `bj` acts like a plain Bitbucket
+client.
+
+## Common commands
+
+```bash
+# Pull requests (Bitbucket)
+bj pr create --dry-run                 # preview title/link/transition
+bj pr create --title "..." --yes       # non-interactive create
+bj pr list --state open --json
+bj pr view --json | jq '.title'
+bj pr diff
+bj pr review --approve                 # or --request-changes --body "..."
+bj pr comment --body "..."             # add --file/--line for inline
+bj pr merge --squash --delete-branch --yes
+
+# Issues (Jira)
+bj issue list --assignee me --json
+bj issue view PROJ-42 --json
+bj issue create --project PROJ --type Bug --summary "..."
+bj issue edit PROJ-42 --field "Story Points=3"
+bj issue transition PROJ-42 "In Review"
+bj issue fields PROJ-42                 # list editable fields on the issue
+
+# Repos and pipelines (Bitbucket)
+bj repo clone WORKSPACE/REPO
+bj pipeline list --json
+bj pipeline run --branch main
+```
+
+## Safety
+
+- Run `bj pr create` / `bj pr merge` with `--dry-run` first when unsure.
+- `pr merge`, `pr close`, `issue close`, and `pipeline stop` change state. In an
+  interactive session `bj` asks first; with `--yes` or when non-interactive it
+  proceeds. Confirm intent with the user before passing `--yes` to these.