Context

Agency's /do workflow is hardcoded to GitHub via gh CLI. To support Bitbucket Server (self-hosted, e.g. v8.6.4), we need a gh-equivalent CLI. avivsinai/bitbucket-cli (bkt) fits.

Phase 1: bkt CLI tool ✅

Upstream bkt v0.19.0+ supports bearer auth via --auth-method bearer (required for older BB Server instances like v8.6.4 that reject Basic auth with PATs). Verified v0.23.0 against bitbucket.juspay.net. No fork needed — see avivsinai/bitbucket-cli#121.

Nix flake support for nix run / nix profile install is proposed upstream in avivsinai/bitbucket-cli#165.

Install

Once avivsinai/bitbucket-cli#165 lands:

nix run github:avivsinai/bitbucket-cli -- --version

Meanwhile, via go install:

nix shell nixpkgs#go nixpkgs#gcc -c go install github.com/avivsinai/bitbucket-cli/cmd/bkt@latest
# -> ~/go/bin/bkt

Setup

# SSH tunnel (if BB instance only reachable via jump host)
ssh -D 1080 -N [email protected] &

# Auth (bearer, via SOCKS proxy)
HTTPS_PROXY=socks5://localhost:1080 bkt auth login https://bitbucket.juspay.net \
  --auth-method bearer --allow-insecure-store

# Create a context for a repo
HTTPS_PROXY=socks5://localhost:1080 bkt context create \
  --project JBIZ --repo euler-api-customer --host bitbucket.juspay.net euler-api-customer

# Test
HTTPS_PROXY=socks5://localhost:1080 bkt pr list

Available PR commands

pr list, pr create, pr view, pr edit, pr comment, pr merge, pr approve, pr checks, pr decline

Notes

• Token stored in encrypted file at ~/.config/bkt/secrets (prompts for passphrase each use). Set BKT_TOKEN env var to skip.
• SOCKS proxy needed if BB instance is only reachable via SSH jump host.
• Upstream config schema uses auth_method: bearer in ~/.config/bkt/config.yml. If you previously used the now-retired srid/bitbucket-cli fork (which wrote bearer_token: true), re-run bkt auth login --auth-method bearer to rewrite the config — otherwise requests 401.

Phase 2: Add Bitbucket support to /do

Current state

The groundwork is already in place:

• .apm/skills/do/SKILL.md:94-100 detects forge from git remote get-url origin (github.com → github, bitbucket. → bitbucket, else unknown).
• Every gh-using step skips gracefully when forge != github with a non-<forge> forge reason.
• do-results already records forge as a first-class field.

What's left is filling in the Bitbucket branches.

Code changes

.apm/skills/do/SKILL.md — add forge == bitbucket branches to three steps:

.apm/skills/forge-pr/SKILL.md — document bkt commands alongside gh (heredoc escaping still applies; flag names differ — --title, --description for bkt pr create).

README.md / do/SKILL.md prerequisites — add: "For Bitbucket repos, install bkt, run bkt auth login --auth-method bearer, and bkt context create for the repo."

Estimated diff: ~80-120 lines across three files.

Gotchas

1. No drafts in BB Server. do/SKILL.md:261 specifically argues for draft-PR-before-CI so failing runs don't orphan a branch. For Bitbucket, the PR lands as open immediately — reviewers may get a ping for a red PR. Either (a) create the PR after CI succeeds for BB, or (b) accept the noise. Needs a design note.

2. SOCKS proxy / HTTPS_PROXY. Internal BB Server instances need HTTPS_PROXY=socks5://localhost:1080 on every bkt call. The skill shouldn't hardcode it — require user to export in shell before /do, or document a per-context env hook.

3. Auth prompt on every call. bkt prompts for a passphrase to unlock ~/.config/bkt/secrets unless BKT_TOKEN is set. Agency runs non-interactively, so users need BKT_TOKEN exported. Have /do check and fail fast with a clear message.

4. Context must be pre-created. bkt context create --project <KEY> --repo <slug> is a one-time manual step per repo. Can't be auto-derived reliably from git remote get-url origin because project keys aren't always in the URL. Document as a prerequisite.

5. Argument-hint. do/SKILL.md:4 says <issue-url | prompt>. For BB, there's no issue URL — only PR URL (for --from resume) or prompt text. Minor update to argument-hint and parsing.

6. CI status. The current ci step runs local commands, so it's forge-agnostic. No gh pr checks equivalent is wired up; if we later want BB Pipelines status, add bkt pr checks.

Suggested first move

Do a narrow MVP: wire only bkt pr create + bkt pr comment (skip edit and hickey-append for v1). That's enough to run /do end-to-end on a Bitbucket repo. Add the rest once the happy path works. Avoids a big SKILL.md diff that's hard to test.

Testing

Need a live BB Server repo (Juspay's euler-api-customer works), a working SOCKS tunnel, and a throwaway branch to exercise create-pr → edit → comment → done end-to-end.