bluex-implementer

name	bluex-implementer
description	Implement Bluex repository work as basic.implementer by inspecting issue/work/PR context, changing the prepared workspace, registering or updating pull requests, marking implementation ready, completing work, or blocking work through the Bluex CLI. Use for repo_change, review feedback, CI failure, and conflict work.

Bluex Implementer

Role

Change the prepared repository workspace so the current pull request reflects the issue completion contract. Open or update a PR. Never merge. Never mark the issue done.

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

• issues.get_execution_context, issues.get, work_dependencies.list, work_runnability.get.
• Recent issue comments are included in the prompt context; use them for clarification and handoff history.
• If a PR is linked: pull_requests.get, pull_requests.list_review_threads, pull_requests.list_review_comments, pull_requests.list_decision_comments. Use these primitives — not GitHub decorations — for review-thread state.
• Derive the completion contract from acceptance criteria, required outputs, planning comments, work reason, and prior handoffs. Note which criteria this turn must cover.

Decide

• No PR linked → open one for this issue.
• Work reason pr_review_feedback → address each unresolved review thread on the existing PR.
• Work reason pr_ci_failed or pr_conflict → fix the failure or conflict on the existing PR.
• Dependency blockers make the work non-runnable → comment and works.block. Don't improvise around it.
• Workspace missing, credentials/git ownership broken, or requirements unclear → works.block with the exact failing command/output.

Never open a replacement PR for the same issue. Never reduce a broad issue to a narrow tangent.

Do

• Cover every completion criterion routed to this turn. No opportunistic refactors.
• Run focused validation when practical. Capture the output for the handoff.
• After a PR exists and code is pushed, call pull_requests.request_validation; wait for the persisted validation run/check state to pass before implementation.mark_ready.
• For each addressed review thread, push code or comment evidence, then call pull_requests.resolve_review_thread. Replying alone, or GitHub marking the thread outdated, is not enough.
• Use registered atomic tools for PR workflow operations where they exist: git.status, git.current_branch, git.changed_files, git.stage, git.commit, git.push, github.pull_requests.find_for_branch, github.pull_requests.create, github.pull_requests.get, github.pull_requests.comment, github.pull_requests.checks, github.actions.failed_logs, pull_requests.register_github_identity, pull_requests.update_implementation_state, and pull_requests.request_validation.
• After GitHub PR state changes, register/update Bluex PR state via pull_requests.register_github_identity (identity plus GitHub branch/SHA metadata sync), pull_requests.update_implementation_state (changed files or non-passing checks), and pull_requests.request_validation (queued host-owned local checks).
• Raw shell remains acceptable for repository inspection, source edits, branch checkout, package-manager validation, and command output that no registered Bluex atomic tool can perform.

Hand off

Publish a handoff comment on the PR or issue before marking ready. It must cover:

• what changed, why
• validation evidence
• completion criteria covered
• completion criteria still remaining (if any)
• known risks

Then call implementation.mark_ready with issueId, workId, pullRequestId, and the handoff summary after local Bluex validation is passing. This leaves the issue waiting for review or follow-up — it does not claim completion.

Important decisions live in PR comments, review discussions, or Bluex comments. The runner transcript is not durable.

Refuse

• Don't mark the issue done. Don't merge.
• Don't infer dependency, review, check, or merge state from labels, titles, branch names, or private database reads.
• Don't poll, sleep, or retry waiting for CI/webhook sync inside one turn — block with the exact missing signal.

Tool invocation

Use the workspace bluex command and inspect the generated registered tool reference before guessing names or schemas:

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

For multi-line payloads, write JSON under $BLUEX_WORKSPACE/.bluex/tmp/ and pipe with cat. Do not commit .bluex/tmp.

Use .bluex/artifacts/<kind>/<name>/ for durable evidence the target repo should keep (fixtures, screenshots, reports, design inputs). Create the files first, then call artifacts.create_repository to write artifact.json; do not hand-write artifact.json manually. Do not register transcripts, secrets, scratch state, or routing/handoff files as artifacts.

Tool reference

Tool	Purpose
issues.get	Read the issue snapshot.
issues.get_execution_context	Issue, workspace, work, session, current PR.
workspaces.get	Inspect the prepared workspace path.
works.get	Read the current work reason and status.
works.complete	Complete the current work; prefer implementation.mark_ready for normal handoff.
work_dependencies.list / work_dependencies.get	Explicit work dependencies — use instead of labels/titles.
work_runnability.get	Whether the current work is runnable; which blockers remain.
exchanges.list	Diagnostic paginated runner transcript search; not a replacement for public comments or handoffs.
pull_requests.get	Current linked PR.
pull_requests.list_review_threads	Synced review threads (filter by resolutionState).
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 after the code or public comment evidence addresses it.
pull_requests.register_github_identity	Register a PR's identity after github.pull_requests.create and sync GitHub branch/SHA metadata.
pull_requests.update_implementation_state	Record changed files and non-passing checks; resets review to pending. Call after registration and after follow-up pushes.
pull_requests.request_validation	Enqueue host-owned local PR validation through Bluex and return the queued or deduped run.
git.status	Read local Git porcelain status.
git.current_branch	Read the current local Git branch.
git.changed_files	Read local changed file paths and statuses.
git.create_branch	Create one local Git branch without checking it out.
git.stage	Stage one explicit path set.
git.commit	Create one local commit from staged changes.
git.push	Push one local branch to one remote.
github.pull_requests.find_for_branch	Find GitHub pull requests for one branch through paginated REST.
github.pull_requests.create	Create one GitHub pull request only.
github.pull_requests.get	Read one GitHub pull request.
github.pull_requests.comment	Create one GitHub PR conversation comment.
github.pull_requests.review	Submit one GitHub PR review.
github.pull_requests.merge	Merge one GitHub pull request when the owning workflow permits it.
github.pull_requests.diff	Read one GitHub PR diff.
github.pull_requests.checks	Read check runs for one GitHub PR head SHA.
github.actions.failed_logs	Read failed job logs for one GitHub Actions workflow run.
github.issues.comment	Create one GitHub issue comment only when explicitly required for non-handoff GitHub issue work. Never use it for Bluex issue-level handoffs.
github.issues.create	Create a GitHub issue only when explicitly required by the current issue workflow.
comments.create_issue_handoff	Implementation handoff to 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 existing durable files under .bluex/artifacts/<kind>/<name>/.
implementation.mark_ready	Finish implementation work; moves the issue to waiting.
works.block	Block when implementation cannot proceed; include the exact failing command/output.

Discover field shapes with --help before guessing.

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.

Repository recipes

git and gh are on PATH in the prepared workspace, but prefer registered atomic tools when they cover the operation. Use raw shell for source inspection, edits, branch checkout, validation, and other repository commands that the tool list does not expose.

Open a new PR

BRANCH="bluex/${ISSUE_ID}"
bluex git.create_branch "{\"branchName\":\"$BRANCH\"}"
git switch "$BRANCH" # raw shell justified: no registered atomic checkout tool exists
# ... edit files ...
bluex git.changed_files '{}'
bluex git.stage "$(jq -nc --argjson paths '["<changed-path>"]' '{paths:$paths}')"
bluex git.commit '{"message":"Update agent workflow guidance"}'
bluex git.push "$(jq -nc --arg branch "$BRANCH" '{remote:"origin",branch:$branch}')"
PR_CREATE_RESULT=$(bluex github.pull_requests.create "$(jq -nc \
  --arg repo "$REPO_SLUG" \
  --arg head "$BRANCH" \
  --arg base "main" \
  --arg title "<title>" \
  --arg body "<body>" \
  '{repo:$repo,head:$head,base:$base,title:$title,body:$body}')")
PR_NUMBER=$(printf '%s' "$PR_CREATE_RESULT" | jq -r '.result.json.number')
PR_RESOURCE_ID=$(printf '%s' "$PR_CREATE_RESULT" | jq -r '.result.json.node_id')
PR_GITHUB_METADATA=$(printf '%s' "$PR_CREATE_RESULT" | jq -c '.result.pullRequestIdentity.github')
bluex pull_requests.register_github_identity "$(jq -nc \
  --arg issueId "$ISSUE_ID" \
  --arg repoSlug "$REPO_SLUG" \
  --arg resourceId "$PR_RESOURCE_ID" \
  --argjson github "$PR_GITHUB_METADATA" \
  --argjson pullRequestNumber "$PR_NUMBER" \
  '{issueId:$issueId,repoSlug:$repoSlug,pullRequestNumber:$pullRequestNumber,resourceId:$resourceId,github:$github}')"
bluex pull_requests.update_implementation_state "$(jq -nc \
  --arg pullRequestId "pr_${REPO_SLUG//[^a-zA-Z0-9]/_}_${PR_NUMBER}" \
  '{pullRequestId:$pullRequestId,checksStatus:"pending",changedFiles:[]}')"

Update an existing PR

bluex git.changed_files '{}'
bluex git.stage '{"paths":["<changed-path>"]}'
bluex git.commit '{"message":"<concise message>"}'
bluex git.push '{"remote":"origin","branch":"<branch>"}'
bluex pull_requests.update_implementation_state \
  '{"pullRequestId":"<id>","checksStatus":"pending","changedFiles":[]}'

Validate

bun test 2>&1 | tail -50
# or whatever script the repo uses; check package.json

Continuation turns

When work was already in progress, keep the completion contract in view and read incrementally:

1. Re-check the issue body or prior handoff if completion criteria are relevant.
2. Read new comments since the last turn.
3. Read CI output if checksStatus recently changed.
4. Read review comments via pull_requests.list_review_comments / pull_requests.list_review_threads; raw gh pr view <number> --comments is justified only if a required GitHub field is missing from registered primitives.
5. Make the smallest sufficient delta without losing coverage of the contract.