complete-issue

name	complete-issue
description	Take a GitHub issue from implementation to merged PR. Use for 'complete issue #N', 'finish this issue end-to-end', or fully autonomous issue-to-merge requests. SKIP issue startup without merge intent; use start-issue.
argument-hint	<issue-number> [--skip-coverage] [--coverage-threshold <n>] [--no-agents]
allowed-tools	["Bash","Read","Glob","Grep","Edit","Write","AskUserQuestion","Agent","EnterPlanMode","mcp__chrome-devtools-mcp__navigate_page","mcp__chrome-devtools-mcp__take_screenshot","mcp__chrome-devtools-mcp__list_console_messages","mcp__chrome-devtools-mcp__list_network_requests","mcp__chrome-devtools-mcp__fill","mcp__chrome-devtools-mcp__click","mcp__chrome-devtools-mcp__new_page","mcp__chrome-devtools-mcp__fill_form","mcp__chrome-devtools-mcp__wait_for","mcp__chrome-devtools-mcp__evaluate_script"]
disable-model-invocation	true

Complete Issue

Autonomous end-to-end pipeline: issue number in → merged PR out.

Chains the start-issue workflow, Codex review, and the e2e-verify fix-and-ship workflow.

The component workflow skills are user-only. Do not call them with the Skill tool. Load their SKILL.md files with Read and execute their instructions directly with the arguments specified below.

The $start-issue phase owns subagent model tiering through agent prompt frontmatter: Explore uses Haiku, Spec Review and Quality Review use Sonnet, and Implementer inherits the parent session model. To override all subagent models for a run, set CLAUDE_CODE_SUBAGENT_MODEL=<model> before invoking $complete-issue; pass --no-agents through to run the start phase without subagents.

Parse Arguments

ISSUE_NUM=""
FLAGS=""
SKIP_NEXT=false
for arg in $ARGUMENTS; do
  if [ "$SKIP_NEXT" = "true" ]; then
    FLAGS="$FLAGS $arg"
    SKIP_NEXT=false
  elif [ "$arg" = "--coverage-threshold" ]; then
    FLAGS="$FLAGS $arg"
    SKIP_NEXT=true
  elif echo "$arg" | grep -qE '^--'; then
    FLAGS="$FLAGS $arg"
  elif [ -z "$ISSUE_NUM" ] && echo "$arg" | grep -qE '^[0-9]+$'; then
    ISSUE_NUM="$arg"
  else
    FLAGS="$FLAGS $arg"
  fi
done

if [ -z "$ISSUE_NUM" ]; then
  echo "Error: Issue number is required."
  echo "Claude Code: /go-workflow:complete-issue <issue-number> [--skip-coverage] [--coverage-threshold <n>] [--no-agents]"
  echo "Codex: \$complete-issue <issue-number> [--skip-coverage] [--coverage-threshold <n>] [--no-agents]"
  exit 1
fi

echo "Issue: $ISSUE_NUM | Flags: $FLAGS"

Loop Initialization & Re-entry

Read loop-state.md and run the bootstrap block + re-entry check. If PHASE is set, recover state and skip to the corresponding phase below; otherwise continue to Phase 1.

Phase → step routing:

• implementing → Phase 1
• reviewing → Phase 3; the earlier in-session review is void and must not be restarted
• verifying → Phase 3

---

Phase 1: Implement ($start-issue)

set_loop_phase "$STATE_FILE" "implementing"

Read ${CLAUDE_PLUGIN_ROOT}/skills/start-issue/SKILL.md and execute its workflow directly, treating $ISSUE_NUM $FLAGS as its $ARGUMENTS. Do not call the Skill tool. Read phases.md for the full sub-step list (fetch issue, create worktree, detect type, explore, design, TDD, verify, coverage, security review, commit/push/PR, watch CI).

After $start-issue completes, detect the PR number and worktree context, reassign STATE_FILE to an absolute path (because CWD may have changed if a worktree was created), and persist:

PR_NUM=$(gh pr view --json number --jq '.number' 2>/dev/null)

GIT_DIR_ABS=$(cd "$(git rev-parse --git-dir 2>/dev/null)" && pwd)
GIT_COMMON_ABS=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)" && pwd)
if [ "$GIT_DIR_ABS" != "$GIT_COMMON_ABS" ]; then
  WORKTREE_PATH=$(pwd)
  echo "Running in worktree: $WORKTREE_PATH"
fi

STATE_FILE="$(pwd)/.local/state/complete-issue-${ISSUE_NUM}.loop.local.json"
mkdir -p "$(dirname "$STATE_FILE")"

TMP="$STATE_FILE.tmp"
jq --arg pr_number "$PR_NUM" --arg worktree_path "${WORKTREE_PATH:-}" \
   '.pr_number = $pr_number | .worktree_path = $worktree_path' \
   "$STATE_FILE" > "$TMP" && mv "$TMP" "$STATE_FILE"
echo "PR #$PR_NUM created"

Worktree-CWD invariant (decision-time, must stay in trunk): If a worktree was created, all subsequent phases MUST operate from $WORKTREE_PATH. Prefix every Bash command with cd "$WORKTREE_PATH" && and use $WORKTREE_PATH as the base for all Read/Edit/Write file paths. The pre-tool-use hook will block tool calls targeting the wrong directory. The STATE_FILE reassignment above ensures set_loop_phase calls resolve correctly regardless of CWD.

---

Phase 2: Self-Review (Codex)

set_loop_phase "$STATE_FILE" "reviewing"

Run an LLM review to catch issues before E2E verification. CRITICAL: Never silently fall back — always present the user with options if codex fails.

Agent-backed fallback reviews are session-local and must complete synchronously. Never dispatch them in the background or persist them for a successor session. If a successor re-enters with phase="reviewing", skip the expired review and continue to Phase 3; the PR already created in Phase 1 and its CI are the durable gate.

Detect codex availability:

CODEX_AVAILABLE=false
if command -v codex &>/dev/null; then
  CODEX_CMD="codex"
  CODEX_AVAILABLE=true
fi

• If codex is NOT available OR if codex exec fails at runtime → Read codex-fallback.md and follow the AskUserQuestion flow for the matching scenario. Do NOT silently fall back.
• If codex IS available → run codex review on the PR diff with an adaptive timeout, address findings, and commit fixes. See phases.md for the full bash (diff sizing, timeout calculation, large-diff warning).

Address findings: for each valid finding, make the fix. Skip false positives or cosmetic-only items. Commit fixes if any changes were made:

git add -A
git commit -m "fix: address codex review findings"
git push

---

Phase 3: E2E Verify and Ship

set_loop_phase "$STATE_FILE" "verifying"

Read ${CLAUDE_PLUGIN_ROOT}/skills/e2e-verify/SKILL.md and execute its workflow directly, treating $PR_NUM fix-and-ship as its $ARGUMENTS. Do not call the Skill tool. This runs the full workflow in fix-and-ship mode (rebase, build, address review, E2E browser tests, post results, add the run-full-ci label, watch CI, and execute the ship workflow).

---

Completion Criteria

Output <done>COMPLETE</done> when ALL of these are true:

1. Issue implemented with tests
2. PR created and pushed
3. Codex review completed and findings addressed
4. E2E verification completed
5. Results posted to PR
6. CI passes
7. PR merged (via the ship workflow)

When ALL criteria are met, output exactly: <done>COMPLETE</done>

Safety: If 15+ iterations without success, document blockers and ask user.

Further Reading

• phases.md — full sub-step lists for Phase 1 ($start-issue) and the codex run for Phase 2
• loop-state.md — bootstrap, re-entry, and persist blocks
• codex-fallback.md — AskUserQuestion flows for codex unavailable / runtime failure / timeout