AGENT SKILL

autoconverge

Drives one draft PR to convergence in one autonomous run with a host-selected pacer. On workflow: three parallel lenses (code-review, bug-audit, self-review) and one-commit fixes via converge.mjs. On portable: pr-converge continuous ticks via portable-driver.md. Bugbot, Copilot, and Codex as terminal confirmation gates before ready. Use when the user says '/autoconverge', 'autoconverge this PR', 'converge this PR in one run', 'run the converge workflow', or 'drive the PR to ready autonomously'.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 7
Forks
1

01 前言 Front Matter

name
autoconverge
description
Drives one draft PR to convergence in one autonomous run with a host-selected pacer. On workflow: three parallel lenses (code-review, bug-audit, self-review) and one-commit fixes via converge.mjs. On portable: pr-converge continuous ticks via portable-driver.md. Bugbot, Copilot, and Codex as terminal confirmation gates before ready. Use when the user says '/autoconverge', 'autoconverge this PR', 'converge this PR in one run', 'run the converge workflow', or 'drive the PR to ready autonomously'.

02 资源文件 50

03 SKILL.md 正文

Autoconverge

One launch drives the whole loop to convergence. The /autoconverge skill scans the tool list, selects a pacer (Workflow or portable), then resolves PR scope, enters a worktree, grants project permissions, and drives the shared converge product to ready (or a named blocker).

Pacer Host surface How the loop runs
workflow Tool list includes Workflow converge.mjs background pass; state in the workflow journal
portable Workflow absent Continuous in-session ticks per ../_shared/pr-loop/portable-driver.md; same helpers and check_convergence.py ready definition

pr-converge selects schedule_wakeup or portable the same way. Both entry skills share the helper scripts and the convergence gate.

Run scope: one PR or several

Decide the scope from how many PRs the user named, then follow that path:

  1. One PR → the single-PR run described below: one worktree, one pacer launch (converge.mjs on pacer=workflow, portable continuous ticks on pacer=portable), one teardown.
  2. Several PRs → the Multiple PRs run: on pacer=workflow, workflow/converge_multi.mjs drives every PR in parallel; on pacer=portable, run the portable driver once per PR (serial or host fan-out), then one teardown per PR.

The single-PR sections (Requirements, Pre-flight, Run the workflow or portable driver, Teardown) each describe one converge run. The multi-PR reference reuses them once per PR and adds only what fanning out needs: a per-PR worktree and a per-PR teardown loop.

Requirements

Scan the tool list for Workflow and ScheduleWakeup, then select the pacer:

python "$HOME/.claude/skills/_shared/pr-loop/scripts/select_converge_pacer.py" \
  --skill autoconverge \
  --has-workflow <0|1> \
  --has-schedule-wakeup <0|1>
  • pacer=workflow — continue with Pre-flight and Run the workflow below.
  • pacer=portable — continue with Pre-flight (portable worktree rules when EnterWorktree is absent), then the continuous driver in ../_shared/pr-loop/portable-driver.md. Do not abort because the Workflow tool is missing.

Set the GitHub transport directive before any GitHub step. Use transport: "cloud" in a Cloud session. Use transport: "local" in a local session. Cloud uses the connected GitHub MCP tools and never starts a local GitHub CLI authentication flow.

Review-lens boundary

The code-review lens boundary (workflow agent versus the built-in /code-review command) is defined on the Code-review lens bullet in reference/convergence.md.

Select the GitHub transport directive before any GitHub step

In a Cloud session, set transport: "cloud" and load the GitHub MCP schemas before the first GitHub tool call. Do not run any local GitHub CLI authentication, account-switch, or token command. Use the operation in cloud-pr-loop-compatibility.md for each GitHub read or write. Use the Cloud session's credentialed push path for local commits. If that path rejects a push, report the exact error instead of trying to log in through the local CLI.

In a local session, set transport: "local" and use the authenticated local GitHub CLI. The workflow defaults to this value when older callers omit the field.

Pre-flight (main session)

  1. Build the task list (step 1 of every run). After Copilot quota / down flags and Codex required/down are known, run only:

    python "$HOME/.claude/skills/_shared/pr-loop/scripts/build_converge_task_list.py" \
      --bugbot-down <0|1> --copilot-down <0|1> \
      --codex-down <0|1> --codex-required <0|1>
    

    Register every tasks[] entry on the session task list. Final task is always all_runnable_reviews_clean_same_head (done_when in the JSON). The run is complete only when that final task is completed — all runnable code reviews CLEAN on the same HEAD. Do not invent tasks in prose. On pacer=portable, open-run returns the same list; still register it as step 1 before driving reviews.

  2. Enter a worktree. When EnterWorktree is in the tool list, call it with no arguments before any gh, git, file read, or edit. gh/git Bash calls do not auto-isolate, so isolation is mandatory. If it fails, report and stop. A bare EnterWorktree branches from origin/main; step 2 positions the worktree on the PR's head ref. When EnterWorktree is absent, isolate with git worktree machinery per ../_shared/pr-loop/portable-driver.md § Isolation and worktree, then continue step 2.

  3. Resolve PR scope. When the user passed a PR URL or number, parse owner, repo, and number from it. Otherwise read the current branch's PR: gh pr view --json number,headRefName,url,isDraft,baseRefName. Capture owner, repo, prNumber. Confirm the PR is a draft; if it is already ready, mark it draft first (gh pr ready <n> --repo <o>/<r> --undo) so the loop owns the ready transition.

    Position the worktree on the PR branch. The run reviews git diff origin/main...HEAD against this worktree's local HEAD and pushes each fix to the PR branch, so the worktree sits on the PR's head ref at the PR HEAD before the loop starts. A worktree fresh off origin/main has HEAD == origin/main, shows an empty diff, and reports a false convergence with zero findings. When a local worktree already tracks the PR branch, enter that one (pass its path to EnterWorktree when that tool exists; otherwise cd into it). Otherwise put the checkout on the branch with gh pr checkout <number> --repo <owner>/<repo> (or git fetch origin <headRefName> then git switch <headRefName>). Confirm before launching: git rev-parse --abbrev-ref HEAD equals the PR's head ref and local HEAD equals the PR head SHA.

  4. Verify the worktree is the PR's repo (strict pre-flight). Run python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict. It confirms the working directory is a checkout of the PR's own repo and that git worktree machinery is healthy. A non-zero exit prints a PREFLIGHT_OUTCOME line and an ABORT line: report that line and stop. Autoconverge runs inside the PR's own repo, so a working directory rooted in a different repo (for example, claude-dev-env while the PR lives in llm-settings) or in no git checkout at all cannot continue.

  5. Grant project permissions. Apply the pr-loop-lifecycle skill's Open section (../pr-loop-lifecycle/SKILL.md) — the grant command (grant_project_claude_permissions.py) and the auto-mode AskUserQuestion escalation for a blocked grant both live there.

  6. Copilot quota pre-check. Before the pacer starts the loop, apply the reviewer-gates skill's Copilot quota gate (../reviewer-gates/SKILL.md) once. Exit 0 maps to copilotDisabled: false / copilot_down=false; any non-zero exit maps to copilotDisabled: true / copilot_down=true, and the run skips the Copilot gate with no agent spawned.

  7. Branch on pacer. When pacer=portable, follow ../_shared/pr-loop/portable-driver.md § Continuous tick loop and § Autoconverge entry on portable pacer, then skip Run the workflow (no Workflow tool). When pacer=workflow, continue with Run the workflow.

Run the workflow

(pacer=workflow only.) Call the Workflow tool against the colocated script:

Workflow({
  scriptPath: "<this skill dir>/workflow/converge.mjs",
  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false, copilotDisabled: false, homeDirectory: "<HOME>", transport: "<cloud|local>" }
})

scriptPath is the absolute path to workflow/converge.mjs inside this skill's own directory (on this install, <home>/.claude/skills/autoconverge/workflow/converge.mjs). homeDirectory is the absolute path to the directory that holds .claude (resolve it once from $HOME, or $env:USERPROFILE on Windows, with forward slashes). The workflow runs in a sandbox with no access to environment variables, so the run reads the home directory from this arg to build the path to the codex-review scripts the Codex gate calls; leave it out and the Codex gate cannot find those scripts. Set transport: "cloud" for Cloud and transport: "local" for local execution. Set bugbotDisabled: true only when the user has opted Cursor Bugbot out for the run; otherwise the workflow detects an opt-out or an unreachable Bugbot on its own. Set copilotDisabled: true when the step 5 quota pre-check exits non-zero, and false when it exits 0; on true the workflow skips the Copilot gate with no agent spawned. The workflow runs in the background and notifies this session on completion. Watch live progress with /workflows.

The moment the Workflow call returns its run id, write the durable handoff so a fresh session can resume the same run:

python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
  --pr-number <N> --head-ref <branch> --phase workflow \
  --resume-command "Workflow({scriptPath, resumeFromRunId: '<runId>'})" \
  --run-id <runId>

Write it again when the result lands, so the handoff carries the final run id and names the teardown phase the fresh session picks up from.

The workflow returns { converged, rounds, finalSha, blocker, standardsNote, copilotNote, codexNote, cleanAuditNote, reuseNote, deferredPrs }, plus a userReview field on a blocker: "user-review" return. cleanAuditNote is non-null when the environment refused the CLEAN bugteam review post and the run recorded the bypass — see reference/stop-conditions.md § Clean-audit post bypassed. deferredPrs is the list of draft environment-hardening PRs the standards-deferral path opened this run, each as { owner, repo, prNumber, copilotDisabled, bugbotDisabled }. The two flags carry this run's Copilot and Bugbot availability, so the next generation skips a reviewer that is down or out of quota without re-probing. This list is the seed the self-closing loop converges next.

Copilot findings — tier, verify, then route

The Copilot gate tiers each finding: a self-healing finding (style, type hints, imports, formatting, magic-value extraction, test-only or doc-vs-code fixes — nothing that changes observable runtime behavior) flows into the fix round with no user notification. A code-concern finding (logic, security, data handling, error-handling semantics, concurrency — the tier whenever in doubt) goes to a verification stage before any routing.

Each code-concern finding gets its own verifier agent, all in parallel, inside the workflow. A verdict is conclusive only when an actual check ran: the verifier executes a command against the flagged HEAD — running the code path with crafted inputs, forcing the claimed error condition, or running a purpose-built test — and captures its output. The verdict carries { verdict, checkCommand, checkOutput, evidence }; a conclusive verdict with an empty checkCommand or checkOutput downgrades to inconclusive.

  • confirmed — the check reproduces the defect. The finding becomes self-healing: it joins the fix round carrying its repro, and the fix re-runs that same check, adds a regression test where the suite covers the surface, lands in one commit, pushes, and replies on the thread with the fix SHA and the before/after output. No page.
  • refuted — the check shows the code already behaves correctly in the exact scenario the finding claims is broken. The workflow replies on the thread with the command and output, resolves it, and counts it clean. No page.
  • inconclusive — everything else, and the verifier's default: no runnable check exists, the check is infeasible here, the results are ambiguous, or the fix needs a product decision. Any doubt sorts here. Only inconclusive findings page the user.

A round whose code concerns all confirm or refute never returns blocker: "user-review". On one or more inconclusive findings, the workflow stops with converged: false, blocker: "user-review", and a userReview field carrying { reviewUrl, findings: [{ file, line, severity, tier, title, evidence }] } — evidence is the verifier's one-line note stating what check was attempted and why it was not decisive.

The wait for a human belongs to the orchestrating session. On a blocker: "user-review" return, run the copilot-finding-triage skill for the ntfy page only (the per-finding summary and evidence note plus the reviewUrl Copilot review link), then hold for the user's response by pacer. On pacer=portable, override triage's hold step — ntfy plus the portable hold below; do not follow triage's ScheduleWakeup / send_later path.

  • pacer=workflow — triage hold: 45-minute ScheduleWakeup (or send_later when that is the host arm).
  • pacer=portable — portable hold only: in-session poll or handoff per ../_shared/pr-loop/portable-driver.md; never ScheduleWakeup or send_later.

When the user answers within the window, follow their direction. When the window closes with no response, run normal teardown and report the inconclusive findings un-reviewed.

Budget stop

Branch the stop and resume path on the selected pacer. Full rule: reference/stop-conditions.md § Budget stop.

  • pacer=workflow — converge.mjs paces against the workflow budget API and stops at a round boundary when a full round does not fit. On a blocker: "budget" return, write the durable handoff with the run id and the Workflow({scriptPath, resumeFromRunId}) resume command before stopping, so a fresh session resumes the paced run without the stopped session's transcript.
  • pacer=portable — stop at a tick boundary when the session cannot cover a full clean tick; write the durable handoff and resume with /autoconverge <PR URL> (see ../_shared/pr-loop/portable-driver.md). Do not instruct a Workflow resume on the portable path.

Teardown

pacer=portable

Skip Workflow-only report steps that need a workflow run id (journal merge, HTML closing report, Artifact publish). Run pr-loop-lifecycle Close (description rewrite when converged, working-tree clean, permission revoke) and print the final report block using tick/check_convergence outcomes. User-review holds use the portable in-session poll (or handoff) from ../_shared/pr-loop/portable-driver.md — not ScheduleWakeup. Resume command: /autoconverge <PR URL>.

pacer=workflow (on workflow completion)

Teardown runs as an ordered checkpoint list. After each checkpoint finishes, re-write the durable handoff with --phase teardown, the run id, and the checkpoints done so far, so a fresh session that resumes reads handoff.json completed_steps and skips the checkpoints already done:

python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
  --pr-number <N> --head-ref <branch> --phase teardown \
  --resume-command "/autoconverge <PR URL>" \
  --run-id <runId> \
  --completed-steps "<checkpoints done so far>"

The checkpoints run in this order: report, close. Write the handoff after each one finishes.

On teardown entry, when ~/.claude/runtime/pr-loop/bugteam-pr-<N>/handoff.json exists, read its completed_steps and skip any checkpoint the list already names, so a resumed run performs only the checkpoints left.

On a blocker: "user-review" return under pacer=workflow, the workflow held one or more code-concern findings that stayed inconclusive after the executed-check verification stage. Run the copilot-finding-triage gate before teardown: send the ntfy alert with the per-finding summary and evidence note and the userReview.reviewUrl link, then hold with a 45-minute ScheduleWakeup (or send_later when that is the host arm). Act on the user's direction when it arrives inside the window; when the window closes with no response, fall through to normal teardown and report the userReview.findings un-reviewed. The PR stays a draft in this path — the workflow marked nothing ready. Under pacer=portable, use the portable teardown hold above (ntfy plus in-session poll or handoff; never ScheduleWakeup).

Before the checkpoints, when the workflow returned a non-null copilotNote (the Copilot gate was bypassed), query the PR's reviews once more for a copilot-pull-request-reviewer[bot] review on the final HEAD (fetch_copilot_reviews.py, or the GitHub MCP pull_request_read method get_reviews). Copilot typically posts within 10–15 minutes of a request, so a review can land between the bypass and teardown. When one exists and carries findings, mark the PR draft, route the findings through one fix round per the pr-fix-protocol skill, re-verify, push, and mark the PR ready again — then run the checkpoints.

  1. When converged is true — build and publish the closing report. Skip this entire step (report, artifact publish, comment, Chrome open) when the workflow returned a non-null blocker. Follow reference/closing-report.md § Building the report and § Publishing: resolve the seed journal from the run id, merge the PR's runs with aggregate_runs.py, spawn the convergence-summary agent (a general-purpose subagent) on the prompt it builds, draw the report with render_report.py, publish the HTML via the Artifact tool, post the one marker-keyed <!-- autoconverge-report --> PR comment, and open the artifact URL in Chrome. After the report is published, write the handoff with --completed-steps "report".

  2. Close the run. Apply the pr-loop-lifecycle skill's Close section (../pr-loop-lifecycle/SKILL.md): when converged is true, rewrite the PR description and clean the working tree — see pr-loop-lifecycle/reference/teardown-publish-permissions.md § Clean working tree and § Publish the final PR description; the workflow already marked the PR ready. The permission revoke always runs, including on a blocker exit. Write the handoff with --completed-steps "report,close".

  3. Print the final report:

    /autoconverge exit: <converged | blocked>
    Rounds: <N>
    Final commit: <finalSha>
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
    Copilot: <copilotNote>     # only when Copilot was down or out of quota
    Codex: <codexNote>         # only when the Codex gate was bypassed (codex_down or opt-out)
    Clean-audit: <cleanAuditNote> # only when the CLEAN bugteam post was bypassed
    Reuse: <reuseNote>         # only when the reuse pass identified an improvement
    

What the workflow does each round

reference/convergence.md defines the whole loop: the merge-conflict pre-flight, the reuse pass and its three landing criteria, the round shape (static sweep, the three parallel reading lenses, dedup, the one-commit fix flow, the standards-deferral path), the terminal Bugbot, Copilot, and Codex gates, the per-role model tiers, the full-diff rule, and the exact ready definition check_convergence.py enforces. reference/stop-conditions.md lists every way the run ends short of ready. Hard-won failure lessons live in reference/gotchas.md.

Every agent prompt the workflow authors carries a headless-safety preamble — read-only agents get a trimmed form, edit agents the full form with the rm auto-allow paths — specified in reference/headless-safety.md.

Multiple PRs

When the user names several PRs, run the multi-PR path in reference/multi-pr.md: one worktree per PR (git worktree add on each head ref, strict pre-flight per worktree, one permission grant per repository, one Copilot quota check for the whole run), then launch by pacer — pacer=workflow: one workflow/converge_multi.mjs call with one entry per PR; pacer=portable: portable driver once per PR (serial or host fan-out) — then single-PR teardown once per PR and a one-line-per-PR summary.

Self-closing loop: converge the deferred PRs

Every autoconverge run — single-PR and multi-PR alike — ends with the self-closing loop in reference/self-closing-loop.md: the orchestrating session converges the draft environment-hardening PRs the run deferred (deferredPrs on a single-PR run, allDeferredPrs on a multi-PR run), then the PRs those runs defer, generation by generation, until a generation opens none. An empty seed list ends the loop at once. The reference also carries the Conventional-Commit title rule each hardening PR must meet.

Folder map

  • SKILL.md — this hub.
  • ../_shared/pr-loop/portable-driver.md — portable pacer when Workflow is absent.
  • workflow/converge.mjs — the convergence workflow script.
  • workflow/converge_multi.mjs — the multi-PR fan-out driver: one converge.mjs child run per PR in parallel, each pinned to its PR worktree via repoPath.
  • workflow/aggregate_runs.py — merges every autoconverge journal for a PR into one journal and returns its deduped findings, fix summaries, round count, and final SHA.
  • workflow/convergence_summary.py — builds the convergence-summary agent prompt over a PR's merged findings.
  • workflow/render_report.py — builds the closing convergence insights HTML report, taking the summary from --summary-file.
  • workflow/autoconverge_report_constants/ — named constants for the report builder and the summary prompt.
  • reference/convergence.md — the whole loop: reuse pass, round shape, terminal gates, model tiers, ready definition.
  • reference/stop-conditions.md — every way the run ends short of ready, including the budget stop.
  • reference/gotchas.md — hard-won failure lessons.
  • reference/closing-report.md — the closing HTML report: data source, build steps, publishing.
  • reference/multi-pr.md — the several-PRs path: per-PR worktrees, the converge_multi.mjs launch, per-PR teardown.
  • reference/self-closing-loop.md — the deferred-PR generations and the Conventional-Commit title rule.
  • reference/headless-safety.md — the agent-prompt preamble and the rm auto-allow paths.

04 同仓库更多 Skills

jl-cmd-projects
jl-cmd-projects/claude-dev-env

update

Fast-forwards a local repository's main branch to a remote's main after confirming the repo path and source remote through AskUserQuestion. Use when the user says '/update', 'update main', 'fast-forward main', 'sync main from origin', 'pull latest main into <path>', or 'bring main up to date'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

source-command-sr-loop

Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

skill-builder

Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers, enforce deterministic scripts. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, skill composition, description trigger catalog, deterministic skill scripts.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

session-tidy

Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

session-log

Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'.

★ 7
jl-cmd-projects
jl-cmd-projects/claude-dev-env

run-claude-dev-env

Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.

★ 7