Issue PR Loop

Issue/PR Loop

Read the root agent instructions and repository guidance. Keep this workflow identical across repositories; local requirements belong in that reference or their maintained source. Reviewing or editing the skill does not start the loop. Stay within the user's authorized scope.

Loop and completion

Run unattended. At each iteration, run pwsh scripts/Remove-MergedWorktrees.ps1 from the shared checkout, survey the queue, then complete one unit in priority order:

1. Merge an eligible PR.
2. Fix conflicts, failed CI, or review findings on an open PR and push.
3. Recover valuable changes from a preserved merged-PR worktree, following recovery guidance.
4. Claim an available issue, implement its full scope, and open a PR.

After pushing or deferring, survey again. Pending CI/review means work another item; do not watch, sleep, poll one item, or schedule monitors while work is queueable. When only CI/review remains, periodically survey the whole queue and stay responsive.

Stop on the user's stop/pause, or when a fresh survey finds no queueable issue, recovery candidate, or actionable PR and remaining work requires an external decision/dependency. Pending CI alone is not completion. Defer unsafe/blocked items, record the blocker once when authorized, release ownership, and continue without blocking questions. Revisit only when evidence changes.

Use commentary while active. Preserve item IDs, worktree, lock identity/script, owned services, and unresolved validation across compaction.

Delegate only when the user explicitly authorizes subagents: one item/iteration, this skill, shared checkout, and canonical lock script. Require a confirmed merged #N, pushed fixes to #N, opened #N closing #M, or failed #N: reason; then continue surveying.

Isolation and ownership

Use the shared checkout for surveys/setup. All implementation, validation, checkouts, commits, and pushes run in an isolated worktree. Capture from the shared checkout:

$repo = git rev-parse --show-toplevel
$repoSlug = gh repo view --json nameWithOwner --jq .nameWithOwner
$repoName = ($repoSlug -split '/')[-1]
$agentLocks = Join-Path $repo 'scripts/AgentLocks.ps1'
$worktreeRoot = Join-Path (Split-Path $repo -Parent) ($repoName + '-worktrees')

Verify the repository and intended base; examples use origin/main. Use a writable temporary <repoName>-worktrees root if needed. Choose a unique worktree path when one already exists.

Acquire the Redis lock before acting on an item: pr-<N> for PR work or recovery, issue-<N> for new implementation. Always invoke the absolute shared-checkout $agentLocks path for every verb; older branch copies can have incompatible token caches.

Redis is authoritative: never steal locks based on PIDs/files/inactivity or add another backend. Do not print/manage cached tokens. Codex supplies CODEX_THREAD_ID; other automation needs the same stable unique -OwnerId on every verb. Renew when needed, without periodic heartbeats. Optional renew -Worktree $worktree records metadata; keep explicit lock names. The issue's in-progress label persists independently.

After claiming an issue, create branch/worktree issue-<N>-<short-desc> from freshly fetched origin/main. For PR fixes, create a detached worktree from origin/main, then run gh pr checkout <N> with that worktree as workdir. PR directories use pr-<N>-<description>; never rename or reuse them for another PR. A separate local review/rebase branch must retain the same pr-<N> identity.

Set every mutating tool call's workdir explicitly; shell directory changes do not persist. Before the first edit and after checkout changes, compare git rev-parse --show-toplevel with the intended worktree's resolved absolute path and inspect git status --short --branch. Abort on a mismatch.

Use repository scripts for merged-worktree cleanup; [gone] or ancestry alone is insufficient. Preserve dirty, locked, open-PR, harness-managed, and locally divergent worktrees. Inspect untracked source before cleanup: scripts may clear build artifacts. Manually remove abandoned worktrees only after verifying repository/path, ownership, and absence of valuable unpublished work. Do not enable stale/scratch cleanup during surveys.

Stop only services/processes/containers started for this worktree. Never blanket-delete containers/volumes or stop shared lock Redis. Follow local lifecycle guidance; use Aspire only where an AppHost exists.

Maintain PRs

Survey with gh pr list --author @me --state open --json number,title,headRefName,headRefOid,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,isDraft. Include other authors only when the user's queue scope includes them. Paginate or increase limits so an incomplete first page cannot make the queue appear empty.

Inspect all review surfaces, including pagination and replies: REST pulls/<N>/reviews, pulls/<N>/comments, issues/<N>/comments under repos/{owner}/{repo}, and GraphQL reviewThreads with IDs, resolution state, bodies, authors, and timestamps.

A COMMENTED review body can block with zero unresolved threads. Address outstanding concerns, CHANGES_REQUESTED, current inline findings, and unresolved threads. Empty acknowledgments are non-blocking. Assess older findings against the current head and later discussion; uncertain concerns block merging.

Resolve a bot-opened thread under the PR lock only after replying with a fix commit or concrete disposition, confirming any promised fix is in the current head, and a subsequent bot review/CI cycle completes without rebuttal. A current-head REVIEW_VERDICT: CLEAR is strongest evidence. Do not resolve newer rebuttals, unaddressed findings, or human threads awaiting response. Use GraphQL resolveReviewThread, then re-fetch reviews, threads, checks, and head SHA.