loop-bb-pr

# loop-bb-pr Compose a `/loop` that periodically polls a Bitbucket PR via the `bb-api` wrapper and surfaces changes (new comments, review state, merge, decline). The skill **never invokes `/loop` itself** at initial start — Claude Code's `/loop` is a UI command. It composes the prompt and presents for paste; once active, the autonomous run uses `ScheduleWakeup` directly per tick (that part is model-callable). > **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. ## Step 1: Resolve PR URL Parse `args` parameter for URL. If not provided, AskUserQuestion: ``` AskUserQuestion( questions=[{ question: "Bitbucket PR URL to watch?", header: "PR URL", options: [ { label: "I'll paste it", description: "Send the bitbucket.org/.../pull-requests/N URL in your next message" }, { label: "Cancel", description: "Abort composition" } ], multiSelect: false }] ) ``` If user picks "I'll paste it", wait for URL in their next message. **Normalize then validate** — real BB URLs often have query strings (`?at=branch&type=...`) or trailing slashes. Strip before regex match: ```bash URL="<from input>" URL="${URL%%\?*}" # strip query string (everything from ? onward) URL="${URL%#*}" # strip fragment (everything from # onward) URL="${URL%/}" # strip trailing slash ``` Then **strict validation** — normalized URL must match exactly: ``` ^https://bitbucket\.org/[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+/pull-requests/[0-9]+$ ``` If validation fails: surface error, exit. Do NOT proceed with malformed URL — the composed prompt may persist (if user switches to interval mode in v1.1) and we don't want arbitrary input in `.claude/scheduled_tasks.json`. Extract via regex or sed (from normalized URL): - `WORKSPACE` — first segment after `bitbucket.org/` - `REPO` — second segment - `PR_ID` — final numeric segment ## Step 2: Verify bb-api availability ```bash which bb-api 2>/dev/null ``` If `bb-api` not found in PATH: ``` ┌─ LETS ─────────────────────────────────┐ │ bb-api not available. │ │ Install bb-api wrapper first. │ │ (curl fallback planned for v1.1.) │ └────────────────────────────────────────┘ ``` Exit. v0 hard-requires bb-api. ## Step 3: Verify access (always run) Default-on pre-flight: confirm bb-api auth + URL points at a real PR before composing a 1200s loop. Cheaper to fail here than to ship a /loop the autonomous run immediately rejects. ```bash bb-api get "/repositories/$WORKSPACE/$REPO/pullrequests/$PR_ID" 2>&1 | head -20 ``` Always surface the result to the user as a short summary (title, state, comment count) — confirms what they're about to watch. If error: - **401/403 (auth)** → surface "Bitbucket auth failed — check bb-api credentials" and exit - **404** → surface "PR not found at <URL> — check URL" and exit - **other errors** → surface verbatim error and exit Never proceed to compose a /loop if Step 3 fails. ## Step 4: Compose /loop Substitute slots: - `<URL>` — validated URL from Step 1 - `<WS>` `<REPO>` `<ID>` — parsed components - `<STATE_FILE>` — `.lets/loop-state/bb-pr-<ID>.json` (relative to project root) Template (dynamic mode — model self-paces via ScheduleWakeup): ``` /loop check Bitbucket PR <URL> for activity since baseline. State file: .lets/loop-state/bb-pr-<ID>.json (workspace=<WS>, repo=<REPO>, id=<ID>) Use bb-api to fetch (READ-ONLY): - `bb-api get /repositories/<WS>/<REPO>/pullrequests/<ID>` → state, title, participants - `bb-api get /repositories/<WS>/<REPO>/pullrequests/<ID>/comments` → count, latest activity timestamp On FIRST tick (state file does not exist): - Create .lets/loop-state/ directory if missing - Write baseline to .lets/loop-state/bb-pr-<ID>.json as JSON: {state, comment_count, latest_activity, approver_count, title, captured_at} - Report "baseline established for PR #<ID> (<title>): state=<X>, comments=<N>, approvers=<M>" - Reschedule via ScheduleWakeup(delaySeconds=1200, prompt=<this entire /loop prompt verbatim>, reason="watching BB PR <ID> — baseline") On SUBSEQUENT ticks (state file exists): - Read baseline from .lets/loop-state/bb-pr-<ID>.json - Fetch current state via bb-api (both endpoints above) - Compare: - If state changed to DECLINED or MERGED → report final state and STOP (do NOT call ScheduleWakeup) - If comment_count increased → report "N new comments since last check, latest from <user> at <time>" and STOP - If approver_count increased → report "approver added: <username>" and STOP - If nothing changed → report "no change (T+<minutes>m since baseline)" and reschedule via ScheduleWakeup(1200, verbatim, "watching BB PR <ID> — no change") Hard constraints (READ-ONLY enforcement): - Loop must NOT call bb-api with POST/PUT/DELETE - Loop must NOT comment, approve, decline, merge, or change PR state - Loop must NOT push to the PR's branch - On bb-api auth error (401/403): report "Bitbucket auth failed" and STOP (do NOT retry blind — user must investigate) - On 404 (PR not found / deleted): report "PR not accessible" and STOP - On other transient errors (timeout, 5xx): log error and reschedule ONCE. If second consecutive error of same type, STOP and surface. - Never re-baseline silently — the baseline is captured ONCE on first tick Termination (each STOP surfaces a single-paragraph summary in assistant text): - state-change-final: PR closed/merged/declined - comment-detected: new comments since baseline - approver-change: approver count changed - auth-failure: bb-api 401/403 - not-found: PR 404 - transient-2x-failure: same transient error twice in a row ``` ## Step 5: Present paste block ``` ## Composed /loop for **Bitbucket PR #{PR_ID}** URL: {URL} Workspace/Repo: {WS}/{REPO} Tick cadence: ~1200s (20 min, dynamic mode, cache-cold) State file: {STATE_FILE} Copy and paste: ```text {COMPOSED_LOOP} ``` **Mode note:** Dynamic mode — the model running the loop calls `ScheduleWakeup` after each tick. Skip the call → loop ends silently. Avoid `delaySeconds=300` exactly (cache TTL trap; we use 1200). **Cancel:** re-issue the same /loop prompt to cancel this watcher, OR user-interrupt the session to cancel all pending loops. **Gotcha:** `/clear` may nuke pending wakeups silently. Dynamic mode does NOT persist across session close (unlike interval mode which writes to `.claude/scheduled_tasks.json`). For session-survival, would need v1.1 interval mode. ``` ## Rules - NEVER call /loop yourself — initial /loop is UI command, paste-only - NEVER recommend a /loop that mutates state (commit, push, bd close, BB comment/approve/merge) — read-only polling only - Strict URL validation BEFORE composition (normalize then regex `^https://bitbucket\.org/[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+/pull-requests/[0-9]+$`) - Strict reject on bb-api unavailability — never compose a /loop the autonomous run can't execute - Composed /loop body: always English (written artifact rule). Surrounding paste-block prose and headers follow user's language - This is a local test skill; promotion to plugin (as a /lets:loop subcommand or separate) is tracked separately