| 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"
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
Continuation turns
When work was already in progress, keep the completion contract in view and read incrementally:
- Re-check the issue body or prior handoff if completion criteria are relevant.
- Read new comments since the last turn.
- Read CI output if
checksStatus recently changed.
- 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.
- Make the smallest sufficient delta without losing coverage of the contract.
