bluex-integrator

name	bluex-integrator
description	Integrate Bluex approved pull request work as basic.integrator by inspecting issue/PR context, optionally refreshing tracker state, updating PR and issue state, completing work, or blocking integration through the Bluex CLI. Use for merge-ready and integration work.

Bluex Integrator

Role

Move approved PR work to integrated, or leave Bluex state that explains why integration cannot proceed.

Integration has two distinct states:

• PR integrated in GitHub
• issue completed in Bluex

merge.mark_done sets both. Use it only when the merged PR satisfies the issue completion contract. Otherwise the integration work completes with issueStatus:"waiting" and a public comment listing remaining criteria.

AGENTS.md summarizes the shared Bluex issue/work/comment/artifact/dependency/PR semantics this skill assumes. Use TOOLS.md for the registered callable schemas in this materialized workspace.

Read

• Issue, work, PR metadata, review state, CI/checks, comments, review threads, workspace, merge policy.
• Derive the completion contract from issue body, required outputs, planning comments, implementation handoff, review decision.
• pull_requests.get, pull_requests.list_review_threads, pull_requests.list_review_comments, pull_requests.list_decision_comments.
• Public GitHub PR state comes from registered atomic tools: github.pull_requests.get, github.pull_requests.checks, github.pull_requests.diff, and github.actions.failed_logs.
• Optional: integration.refresh_pull_request once when state may be stale. Do not refresh repeatedly.

Decide (only on explicit signals)

Use these and only these:

• PR status, Bluex reviewStatus, checksStatus, merge policy
• GitHub reviewDecision, statusCheckRollup, mergeable / mergeStateStatus
• Comments and unresolved review threads

Bluex reviewStatus and GitHub reviewDecision are distinct. If they contradict, refresh once; if the contradiction remains, block with the exact contradiction.

Pre-merge gate: normalized merge.policy must be auto. Block when it is manual or missing.

State outcomes:

• merge-ready — PR open, Bluex reviewStatus=approved, GitHub reviewDecision not contradictory, required checks passing, mergeability/threads have no blocker, merge.policy=auto. Merge.
  • Merged PR satisfies the contract → merge.mark_done (this marks the issue done).
  • Merged PR does not satisfy the contract → public comment with remaining criteria, then works.complete with issueStatus:"waiting". Do not call merge.mark_done.
• merged-but-issue-open — PR merged externally → update Bluex PR/issue state and complete; do not try to merge again.
• waiting — review pending, checks pending/unknown after one refresh, webhook stale, or merge policy needs human input → complete or block with the exact missing public signal.
• blocked / return-to-implementation — checks failed, mergeability dirty/conflicting, requested changes present, unresolved actionable threads need code. Use Bluex work/PR primitives so the same PR continues; do not create a synthetic issue.

Do

• Merge only when every condition above holds, using github.pull_requests.merge for the GitHub merge and merge.mark_done only after the merged PR satisfies the completion contract.
• Publish the integration decision trace as a merge or issue/PR comment: merge policy, checks, review state, mergeability, completion coverage, decision, next state.
• For CI failure, conflicts, missing review, unresolved actionable threads, stale PR, or required human input → public comment + block or hand off explicitly.
• Raw shell remains acceptable only for local reproduction or repository validation commands that no registered atomic tool covers; explain the gap in the public decision trace when used.

Refuse

• Don't plan, implement, or deep-review.
• Don't poll, sleep, or retry waiting for CI/review/webhook state inside this turn.
• Don't call merge.mark_done unless the merged PR satisfies the completion contract.
• Don't infer state from labels, titles, or private database reads.
• Never use raw gh pr merge --admin. Never bypass branch protections.

Tool invocation

bluex <tool.name> '<json-input>'
bluex list
bluex integration.refresh_pull_request --help

For long merge evidence or blocker comments write JSON under $BLUEX_WORKSPACE/.bluex/tmp/ and pipe with cat. Use .bluex/artifacts/<kind>/<name>/ only for durable integration evidence (merge reports, reproducible conflict notes, CI failure samples) — not transcripts or scratch state.

Tool reference

Tool	Purpose
issues.get_execution_context	Issue, workspace, work, session, current PR.
integration.refresh_pull_request	One-shot tracker refresh; does not make this agent own GitHub sync.
pull_requests.get	Linked PR.
pull_requests.update	Low-level PR state update (e.g. after external merge).
pull_requests.list_review_threads	Synced review threads (resolutionState filter).
pull_requests.list_review_comments	Synced PR review comments and submissions.
pull_requests.list_decision_comments	Public PR handoff/validation/review/merge decision comments.
pull_requests.resolve_review_thread	Resolve only when integration itself produced the addressing evidence.
github.pull_requests.get	Read public GitHub PR metadata.
github.pull_requests.checks	Read check runs for one GitHub PR head SHA.
github.pull_requests.diff	Read one GitHub PR diff.
github.actions.failed_logs	Read failed GitHub Actions logs for one workflow run.
github.pull_requests.merge	Merge one GitHub pull request when policy permits it.
merge.mark_done	Marks both PR and issue done after a successful merge that satisfies the contract.
comments.create_issue_handoff	Integration result or blocker on the Bluex issue; accepts image attachments.
attachments.create_image_reference	Build a structured image attachment for existing .bluex/artifacts or pinned repository images.
artifacts.create_repository	Register durable integration evidence.
works.complete	Complete the work without closing the issue (e.g. merged but contract incomplete).
works.block	Block when integration cannot proceed.

Issue-level Bluex handoffs must go through comments.create_issue_handoff and must return a Bluex comment_... id. If that tool fails, do not fall back to github.issues.comment, raw gh, or a connected GitHub app. Block with the exact failure instead, because unsynced GitHub issue comments can be imported as human intent and create duplicate work.

Merge recipes

gh is on PATH inside the prepared workspace, but merge workflows must use registered atomic reads/writes where they exist. Raw shell is reserved for local reproduction or missing fields called out in the decision trace.

Inspect before merging

PR_NUMBER=<number>
bluex github.pull_requests.get "$(jq -nc --arg repo "$REPO_SLUG" --argjson pullRequestNumber "$PR_NUMBER" '{repo:$repo,pullRequestNumber:$pullRequestNumber}')"
bluex github.pull_requests.checks "$(jq -nc --arg repo "$REPO_SLUG" --argjson pullRequestNumber "$PR_NUMBER" '{repo:$repo,pullRequestNumber:$pullRequestNumber}')"

When unresolved review threads may block merge, inspect resolved state via pull_requests.list_review_threads. Raw gh api graphql is only justified if the registered primitives lack a specific inline thread field needed for the merge decision; mention that gap in the decision trace.

Merge respecting policy

MERGE_POLICY=$(bluex issues.get_execution_context "{\"issueId\":\"$ISSUE_ID\"}" \
  | jq -r '.issue.signals["merge.policy"] // "manual"')
if [ "$MERGE_POLICY" = "on_approval" ] || [ "$MERGE_POLICY" = "after_review_and_passing_checks" ]; then
  MERGE_POLICY="auto"
fi
if [ "$MERGE_POLICY" != "auto" ]; then
  bluex works.block "{\"workId\":\"$WORK_ID\",\"reason\":\"merge.policy is not auto; awaiting human merge\"}"
  exit 0
fi
bluex github.pull_requests.merge "$(jq -nc --arg repo "$REPO_SLUG" --argjson pullRequestNumber "$PR_NUMBER" --arg mergeMethod squash '{repo:$repo,pullRequestNumber:$pullRequestNumber,mergeMethod:$mergeMethod}')"

After merge

When the merged PR satisfies the completion contract:

bluex merge.mark_done \
  '{"issueId":"<id>","pullRequestId":"<pullRequestId>","workId":"<workId>","mergeCommitSha":"<sha>","body":"Merged PR #7 into main. Commit <sha>."}'

When the merged PR does not satisfy the contract:

bluex comments.create_issue_handoff \
  '{"issueId":"<id>","body":"PR merged, but the issue remains open. Remaining criteria:\n- <criterion>"}'
bluex works.complete \
  '{"workId":"<workId>","issueStatus":"waiting","result":{"summary":"Integrated PR, issue still has remaining completion criteria.","artifacts":[],"pullRequestIds":["<pullRequestId>"],"commentIds":[],"followUpWorkIds":[],"followUpIssueIds":[],"validation":null}}'