EPIC: Complete BitBucket VCS abstraction — eliminate GitHub-specific assumptions

[acreeger]

Fixes #690

EPIC: Complete BitBucket VCS abstraction — eliminate GitHub-specific assumptions

Context

PR #609 introduces BitBucket VCS provider and Jira issue tracker support. Code review + deep analysis across 4 dimensions (VCS abstraction layer, command-level hardcoding, settings/config, MCP/issue management) revealed 11 medium+ issues where GitHub is assumed as the only VCS provider.

The PR introduces a two-track architecture: BitBucket uses the new VersionControlProvider abstraction, while GitHub uses the legacy PRManager + gh CLI. This is pragmatic for the initial integration but creates maintenance burden and functional gaps for Jira+BitBucket teams.

Goal: Make BitBucket a first-class VCS provider with full feature parity.

---

HIGH — Functional Bugs / Gaps

1. il start <pr-number> broken for Jira+BitBucket

Files: start.ts:413-433, 456-465, LoomManager.ts:607-614

When the issue tracker doesn't support PRs (Jira), start.ts falls back to hardcoded GitHubService for PR detection. For a Jira+BitBucket team, il start 42 queries GitHub for PR #42 instead of BitBucket. The same pattern exists in LoomManager.fetchIssueData() (3 instances of hardcoded GitHub fallback).

Fix: Replace GitHubService fallback with VCS-provider-aware routing (check VCSProviderFactory before falling back to GitHub).

2. MCP get_pr hardcodes GitHub provider

File: issue-management-server.ts:256-258

The get_pr tool creates new GitHubIssueManagementProvider() directly, ignoring all provider config. Agents running in BitBucket workspaces cannot read PR details.

Fix: Route get_pr through the VCS provider abstraction or add BitBucket MCP support.

3. MCP PR comments hardcode GitHub

File: issue-management-server.ts:362-363, 412-413

create_comment and update_comment with type: 'pr' are hardcoded to use the GitHub provider. Agent PR comments always go to GitHub even when using BitBucket.

Fix: Route PR comment operations through VCS provider when BitBucket is configured.

4. Init wizard has zero BitBucket awareness

File: templates/prompts/init-prompt.txt:514-784

• Merge mode options only list local, github-pr, github-draft-pr — missing bitbucket-pr
• No VCS provider configuration steps
• No BitBucket credential documentation
• JSON generation examples don't include versionControl config

Fix: Add bitbucket-pr merge mode, VCS provider selection, and BitBucket config steps to init wizard.

---

MEDIUM — Incomplete Paths / Limitations

5. summary.ts ignores bitbucket-pr mode

File: summary.ts:64-76

getPRNumberForPosting() handles github-draft-pr and github-pr but not bitbucket-pr. Falls through to undefined, so summaries always post to the issue. Currently documented as intentional in finish.ts:1259-1261, but should be revisited once MCP PR comments support BitBucket (#3).

6. Agent templates hardcode gh CLI commands

File: templates/prompts/issue-prompt.txt:968-987

STEP 5.5 (Auto-Commit and Push) uses gh run list, gh pr view, gh api for CI/CD checks. These fail in BitBucket-only environments.

Fix: Add conditional templating for BitBucket vs GitHub CI/CD check commands.

7. PRManager.generatePRBody() prompt says "GitHub" but serves BitBucket too

Files: PRManager.ts:135, finish.ts:1220-1222

The BitBucket PR workflow calls prManager.generatePRBody() which tells the AI it's writing a "GitHub pull request body". Functionally harmless (Markdown is universal) but misleading.

Fix: Make the prompt provider-agnostic, or have BitBucket use its own body generation.

8. plan.ts error messages assume GitHub or Linear only

File: plan.ts:297-340

Error messages only branch on provider === 'github' vs else (assumed Linear). Jira users get unhelpful error messages referencing LINEAR_API_TOKEN.

Fix: Add Jira-specific error messaging branch.

9. Metadata stores issueTracker but not vcsProvider

File: MetadataManager.ts:12-39

Loom metadata records which issue tracker was used but not the VCS provider. finish/cleanup must re-derive from settings, which is fragile if settings change between start and finish.

Fix: Add vcsProvider field to MetadataFile interface and populate during start.

10. Three near-duplicate PR workflow paths in finish.ts

File: finish.ts:735-864, 1041-1272

github-pr, github-draft-pr, and bitbucket-pr share significant logic (push branch, generate title, get base branch, check existing PR, create PR, transition issue, generate summary, archive metadata, handle cleanup). Adding a 4th VCS provider would require a 4th copy.

Fix: Extract shared PR workflow logic into a common method, with provider-specific operations delegated through the VersionControlProvider interface.

11. SessionSummaryService routes PR summaries via hardcoded GitHub

File: SessionSummaryService.ts:406-409

PR summary posting is hardcoded to use the 'github' provider.

Fix: Route through VCS provider abstraction.

---

Suggested Implementation Order

1. Initialize TypeScript Project and CLI Structure #1 (start.ts PR detection) — highest user impact, blocks basic il start for Jira+BitBucket
2. Core Git Worktree Management Module #2 + GitHub Integration Module #3 (MCP PR routing) — needed for agent workflows with BitBucket PRs
3. Environment Management Module #4 (init wizard) — needed for discoverability / onboarding
4. Implement 'start' Command #6 (agent templates) — needed for CI/CD in BitBucket environments
5. Implement 'cleanup' Command #8 (plan.ts errors) — quick fix, improves Jira UX
6. Implement 'list' Command #9 (metadata vcsProvider) — small change, improves robustness
7. Implement 'finish' Command #7, Implement 'switch' Command #10, Claude Context Generation #11 (cleanup / refactoring) — lower urgency but reduces maintenance burden
8. Database Branch Management (Neon) #5 (summary.ts) — depends on Core Git Worktree Management Module #2/GitHub Integration Module #3

Related

• PR feat: add BitBucket integration for pull request management #609 — feat: add BitBucket integration for pull request management

---

This PR was created automatically by iloom.

[acreeger]

iloom Session Summary

Key Themes:

• All 7 child issues (Fix il start PR detection for non-GitHub VCS providers #697–Refactor finish.ts PR workflows to reduce duplication #703) were implemented in parallel by a swarm and merged cleanly into the epic branch.
• The vcsProvider metadata field is intentionally typed as string | null (not a union type) to keep the scope minimal — populated from settings.versionControl?.provider ?? 'github' at loom creation time, with null as the backward-compatible fallback for legacy looms.
• update_comment with type: 'pr' on BitBucket intentionally throws a descriptive error — the BitBucket REST API does not support PR comment editing.

---

Session Details (click to expand)

Key Insights

• VCS provider routing pattern: All routing goes through VCSProviderFactory — when settings.versionControl.provider === 'bitbucket', operations use BitBucketVCSProvider; otherwise they fall back to GitHubService. This pattern is now consistent across start.ts, LoomManager.ts, issue-management-server.ts, SessionSummaryService.ts, and finish.ts.
• finish.ts unification: The three near-duplicate PR workflow paths (github-pr, github-draft-pr, bitbucket-pr) were consolidated into a single executeVCSPRWorkflow method. The method accepts VersionControlProvider | null — null = GitHub via PRManager, non-null = delegates to the VCS provider. Adding a future VCS provider (e.g. GitLab) requires only implementing the interface, not adding a new code path.
• Dry-run bug fixed as side effect: The BitBucket path in finish.ts was archiving metadata even in dry-run mode — this was corrected during the Refactor finish.ts PR workflows to reduce duplication #703 refactor.
• vcsProvider in metadata vs. settings: The field is stored at loom creation time so finish/cleanup don't re-derive from current settings. This prevents breakage if settings change between il start and il finish (e.g. team migrates VCS mid-loom).
• IS_BITBUCKET template variable: Added to TemplateVariables interface and wired in IgniteCommand.buildTemplateVariables() from settings.versionControl.provider. This is now the canonical way to conditionally render provider-specific content in agent templates.

Decisions Made

• vcsProvider as string | null, not a typed union: Keeping it as a plain optional string avoids introducing a type contract that could break with future providers. Legacy looms without the field return null and fall back to deriving from settings.
• update_comment for BitBucket throws, not silently ignores: Documents a real API limitation rather than silently doing nothing, which would be confusing to agents trying to update PR comments.
• BitBucket CI/CD guidance uses curl + Pipelines REST API: Rather than requiring a BitBucket CLI, the agent template gives curl-based fallback instructions so agents can check pipeline status without additional tooling.

Challenges Resolved

• Refactor finish.ts PR workflows to reduce duplication #703 dependency on Add vcsProvider field to loom metadata #702: The finish.ts refactor needed the vcsProvider metadata field to exist before it could use it for routing. Dependency was enforced by blocking Refactor finish.ts PR workflows to reduce duplication #703 until Add vcsProvider field to loom metadata #702 merged. Once Add vcsProvider field to loom metadata #702 landed on the epic branch, the Refactor finish.ts PR workflows to reduce duplication #703 agent rebased and consumed the new field cleanly.

Lessons Learned

• The VCSProviderFactory abstraction from PR feat: add BitBucket integration for pull request management #609 was designed correctly — all 7 child issues consumed it without needing to modify the interface itself.
• MCP server tools that hardcode a provider need careful attention: get_pr, create_comment, and update_comment all independently instantiated GitHubIssueManagementProvider directly, bypassing the factory. This pattern should be audited for any future tools added to the MCP server.
• Template variables for Handlebars conditionals (like IS_BITBUCKET) must be wired in IgniteCommand.buildTemplateVariables() AND declared in the TemplateVariables interface — both are required for the template to render correctly.

---

Generated with 🤖❤️ by iloom.ai