kandev/docs/specs/integrations/system-design/bitbucket-plugin-02.md

status, system, requirements, created, owners

status	system	requirements	created	owners
draft	integrations	REQ-INTEGRATIONS-BITBUCKET-PLUGIN-001	2026-07-31	kandev

Bitbucket Connector Plugin System Design Part 2

Purpose and boundaries

This design preserves the technical source detail for REQ-INTEGRATIONS-BITBUCKET-PLUGIN-001 during migration.

Requirement mapping

Requirement	Design section
REQ-INTEGRATIONS-BITBUCKET-PLUGIN-001	Migrated source detail

Migrated source detail

Scenarios

• GIVEN the independently released Bitbucket UI bundle, WHEN it compiles or launches native task creation, THEN it consumes @kandev/plugin-sdk and typed host.context reads without copied host interfaces or private Zustand slice parsing.

• GIVEN Bitbucket is active and a user pastes a URL owned by GitHub, GitLab, or another self-hosted provider, WHEN Kandev probes registered repository providers, THEN Bitbucket's workspace-scoped structured inspector returns no match and does not steal the URL by hostname/path heuristics or registration order.

• GIVEN a connected Cloud or Data Center workspace, WHEN a user selects a Bitbucket repository in native task creation, THEN Kandev persists the complete plugin-inspected descriptor and exact credential-free clone URL without host-side Bitbucket URL parsing.

• GIVEN two Data Center connections share one authority but use different context roots, WHEN either imports the same project/repository slug, THEN Kandev keeps distinct rows and managed clones using the plugin's connection scope and immutable repository ID; it never adopts the other root or a legacy unscoped row.

• GIVEN a persisted Bitbucket repository is materialized for a task session, WHEN Kandev requests the initial HTTPS clone credential, THEN the plugin receives the host-derived workspace, task, session, repository, exact-host, and exact-path scope, and missing or mismatched scope fails before Git runs.

• GIVEN that managed checkout already exists and pull-before-worktree is enabled, WHEN a task session launches, THEN Kandev refreshes origin through the same exact plugin credential scope and performs no unauthenticated follow-up fetch or pull.

• GIVEN an eligible task, WHEN a user opens a desktop task context/dropdown or visible mobile task action menu, THEN Link → Bitbucket Pull Request is represented by a Bitbucket Pull Request child item and invokes the plugin with verified current context.

• GIVEN that item is selected, WHEN the user enters an invalid or valid Bitbucket pull-request reference, THEN the host renders GitHub-parity dialog geometry and footer behavior, keeps validation errors inline, and on success closes the dialog and shows a success toast after the authenticated task-scoped link completes.

• GIVEN a Bitbucket pull request linked to a task, WHEN the user opens review on desktop or mobile, THEN the native review surface selects a normalized Bitbucket item and mounts the host-owned change-request detail anatomy used by GitHub, with Bitbucket data and only the actions its adapter declares.

• GIVEN the plugin is disabled after a review panel, task action, or repository provider was registered, WHEN Kandev refreshes the plugin registry, THEN those registrations disappear, in-flight work is aborted, review selections close safely, and no host Bitbucket fallback remains.

• GIVEN the plugin is active, WHEN a user opens the native integrations index or a workspace settings tree, THEN Bitbucket appears with its plugin-owned brand icon and native settings page, receives the selected workspace ID, and disappears from both surfaces when the plugin unloads.

• GIVEN a connected Bitbucket workspace, WHEN the user opens /bitbucket, THEN the page uses the same list-first hierarchy, density, toolbar geometry, row anatomy, and restrained loading/error/empty treatment as /github and /gitlab; the host renders shared primitives rather than plugin-cloned markup.

• GIVEN more than one provider page of repositories or pull requests, WHEN the user searches the repository filter or changes result pages, THEN the dashboard consumes opaque cursors, exposes every repository, and keeps a deterministic provider-neutral queue order without truncating before pagination.

• GIVEN a pull request in that list, WHEN the user opens its Task menu, THEN the same compact preset menu as GitHub/GitLab appears and the chosen preset opens Kandev's native task dialog directly with repository, source branch, title, and prompt prefilled; the three preset rows use the exact native eye, message, and tool glyphs.

• GIVEN a Bitbucket task is created or already linked, WHEN the user returns to the dashboard or opens task Review, THEN the row exposes the native linked-task indicator and review opens through the registered task review provider; there is no dashboard Review button or intermediate launch dialog on desktop or mobile.

• GIVEN a linked Bitbucket pull request has normalized task status, WHEN its task-list indicator renders or its lazy desktop refresh completes, THEN the glyph uses the same failure, pending, review-wait, passing, merged, and muted color hierarchy as first-party code hosts without accepting provider CSS or Bitbucket-specific tones.

• GIVEN a committed custom query or repository filter differs from a built-in preset, WHEN the user saves and names it, THEN it appears in the shared saved menu, survives reload for that user/workspace, restores the displayed query and repository filter when selected, and can be deleted.

• GIVEN a pull request repository is not yet persisted in the workspace, WHEN the native task dialog submits or retries, THEN the authenticated plugin action creates from the server-resolved source repository exactly once for that dialog launch; opening the Task menu again may create another linked task.

• GIVEN that Bitbucket repository is persisted, WHEN the native task dialog loads its branch picker, THEN Kandev invokes the active Bitbucket plugin with the stored provider descriptor and renders its branches without a GitHub request, a 500, or a local-clone fallback.

• GIVEN a # Bitbucket pull-request result was selected, WHEN the message is submitted after the plugin was disabled, moved workspaces, or access changed, THEN submission reauthorization rejects it and no unapproved reference metadata reaches the queued message.

• GIVEN a watch finds the same pull request concurrently or restarts during task creation, WHEN recovery runs, THEN the durable reservation and plugin-owned task metadata result in at most one created task; reset/delete previews and removes only that owned tree, and the recovered task remains associated with the pull request in dashboard, Review, and status queries.

• GIVEN a task creates a Bitbucket pull request successfully, WHEN the result is returned or the task is reopened, THEN the new pull request is already associated with that task; a later association-state failure is reported without inviting a retry that could create a duplicate remote pull request.

• GIVEN an eligible Bitbucket task has commits and no linked pull request, WHEN the user submits native Create PR, THEN Kandev pushes the selected checkout branch, verifies the selected session/repository worktree and passes its server-derived head branch to the active provider, associates the created pull request, and reports a post-push create failure as retryable without trusting a browser source branch or adding Bitbucket logic to agentctl.

• GIVEN one or more Bitbucket pull requests are linked to a task, WHEN association data loads or one link is removed, THEN the native task-row/card glyph count and shared unlink controls update reactively on desktop and mobile while other links remain intact.

• GIVEN an agent or user creates an open Bitbucket pull request externally from a task's checkout branch, WHEN that task refreshes, THEN the plugin discovers the exact source-branch match from host-verified repository data and links it without a manual URL paste.

• GIVEN a linked pull request has source-commit pipeline/build statuses, WHEN the task topbar control or composer CI chip is opened on desktop or mobile, THEN the exact shared GitHub-grade status surface shows those checks, refreshes on open, and can open the registered Bitbucket Review panel without a provider-specific route.

Out of scope

• Bitbucket Issues, Cloud app passwords, and a generic host Bitbucket API client.
• Bitbucket-specific changes in agentctl pull-request automation or a new provider-specific WebSocket contract.
• External Bitbucket webhooks for watches; authenticated polling is v1 behavior.
• Pretending Cloud Pipelines and Data Center build statuses have identical APIs.
• A Bitbucket-specific signing verifier or trust-root policy. The initial release uses the current checksum-verified, explicitly unsigned plugin contract.
• Marketplace publication before required host contracts are released, package, desktop/mobile, and container credential-flow acceptance passes.

Implementation plan

Bitbucket plugin implementation plan