Autopilot

Claude Code

1. Read references/pr-subagent-template.md (template is unchanged).

2. Read the spec just written (pr1-<short>.md).

3. Resolve dispatch-time template variables:

   • {BRANCH} = feature/<short-name>
   • {TITLE} = feat(scope): <summary>
   • {PR_ID} = pr1
   • {PLAN_DIR} = docs/loops/<YYYY-MM-DD>_<short-name>
   • {SPEC_FILE} = pr1-<short>.md
   • {SIZE} = the PR's size (s/m/l) when the descriptor set one — Step 5 of the suffix passes it to /greenlight as size={SIZE}. When unset, drop the size={SIZE} clause so no token is passed (greenlight then auto-classifies).
   • {SELECT} = the PR's select — the planned reviewer selection as a comma-separated recipe list. Step 5 passes it as select={SELECT}. When the descriptor set none, drop the select={SELECT} clause entirely.
   • {GATE} = the PR's gate — the recipe whose clean pass ends the review loop, passed as gate={GATE}. Drop the clause when unset, exactly as with {SIZE}.

   Fill {SELECT} / {GATE} only from a preference the user actually stated while planning. Autopilot does not resolve reviewers itself: greenlight owns that decision, degrades a stale id with a warning at run time, and falls back to the repo's fallback_order when neither token is passed.

   Leave {PR_NUMBER}, {REPO_ROOT}, {WORKTREE_PATH} as {...} literals — the subagent fills them in at runtime.

4. Assemble the final prompt by concatenating, in order: the inner contents of the Standard Prefix fenced code block, the spec content from step 2, and the inner contents of the Standard Suffix fenced code block (do not include the ## Standard Prefix / ## Standard Suffix markdown headers or the surrounding triple-backtick fences). Substitute the variables from step 3 into the result.

5. Dispatch — branch on Workflow tool availability (check whether a Workflow tool is present in this session's available tools):

   Workflow tool available: dispatch via the wave-workflow template (references/wave-workflow.md) as a single-PR batch:

   • args.prs = one entry: { id: "pr1", branch, title, subagent, prompt, files }, where prompt is the assembled prompt and files is this PR's create/modify list from the Step 2 descriptor. With one PR the overlap check trivially passes.
   • args.max_retries = 2.
   • Invoke the Workflow tool with the wave-workflow script and these args. The call is async (see orchestrator.md Step 2a): it returns a launcher response ({ status, taskId, error? }); if error is set the script failed its syntax check — fall back to the Agent path. Otherwise wait for the matching task_notification completion event and read the workflow result from its output_file.
   • results[0] from that payload is this PR's result: the schema-validated agent output plus an attempts count (in-script retries already handled).

   Workflow tool unavailable (fallback — unchanged): dispatch the Agent tool:

   • subagent_type = <subagent declared in Step 2>
   • isolation = "worktree"
   • prompt = the assembled prompt

6. Get the result JSON: results[0] from the workflow (Workflow branch), or the subagent's returned result JSON (Agent branch).

7. Print a completion report inline (see "Completion Report" below).

The full lifecycle still runs: Plan Mode → /plan-review internal → implement + test → commit + push + gh pr create → /greenlight → CI poll → /merge-pr → cleanup → result JSON. All defined by the unchanged pr-subagent-template.md.

Failure / interruption (run-now mode): there is no state.json to resume from. If the session crashes mid-execution, manual cleanup is required: run git worktree list and gh pr list to see what was left behind, then either finish or close it before re-running /autopilot for a fresh attempt. If the user wants crash recovery, they should pick "schedule" instead.

Codex V1

Codex owns the worktree in the parent thread; the child owns only the files and PR lifecycle inside it. Run these steps only after the user confirmed the single-PR plan and chose run-now.

1. Set BRANCH, TITLE, PR_ID=pr1, PLAN_DIR, and SPEC_FILE from the approved descriptor. Before writing the spec or spawning a child, execute this preflight as one Bash block. Any failure stops with no PR; the block removes only a worktree it created itself.

REPO_ROOT="$(git rev-parse --show-toplevel)" || exit 1
BASE_BRANCH="$(git branch --show-current)"
BASE_SHA="$(git rev-parse HEAD)" || exit 1

if [[ -z "$BASE_BRANCH" || -n "$(git status --porcelain)" ]]; then
  echo "Autopilot requires a clean, attached base branch; stopping before side effects."
  exit 1
fi
if [[ "$BASE_BRANCH" != main ]]; then
  echo "Codex Autopilot V1 requires main because Greenlight evaluates main...HEAD; stacked PRs are not supported."
  exit 1
fi
if [[ "$PLAN_DIR" != docs/loops/* || "$PLAN_DIR" == *..* \
   || "$SPEC_FILE" != pr1-*.md || "$SPEC_FILE" == */* ]]; then
  echo "Autopilot generated an unsafe spec path; stopping."
  exit 1
fi
git check-ref-format --branch "$BRANCH" >/dev/null || exit 1
REMOTE_BASE_LINE="$(git ls-remote --exit-code --heads origin "refs/heads/$BASE_BRANCH")" || exit 1
if [[ "$REMOTE_BASE_LINE" != "$BASE_SHA"$'\t'"refs/heads/$BASE_BRANCH" ]]; then
  echo "Local $BASE_BRANCH is not exactly origin/$BASE_BRANCH; sync it before Autopilot."
  exit 1
fi
if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
  echo "Local branch already exists: $BRANCH"
  exit 1
fi
PUSH_REMOTE_URL="$(git remote get-url --push --all origin)" || exit 1
if [[ -z "$PUSH_REMOTE_URL" || "$PUSH_REMOTE_URL" == *$'\n'* ]]; then
  echo "Codex Autopilot V1 requires exactly one origin push URL."
  exit 1
fi
if git ls-remote --exit-code --heads "$PUSH_REMOTE_URL" "refs/heads/$BRANCH" >/dev/null 2>&1; then
  echo "Remote branch already exists: $BRANCH"
  exit 1
else
  REMOTE_PROBE=$?
  if [[ "$REMOTE_PROBE" -ne 2 ]]; then
    echo "Could not verify that remote branch $BRANCH is absent."
    exit 1
  fi
fi

WORKTREE_PATH="$(dirname "$REPO_ROOT")/$(basename "$REPO_ROOT")-autopilot-$PR_ID"
if [[ -e "$WORKTREE_PATH" ]]; then
  echo "Worktree path already exists: $WORKTREE_PATH"
  exit 1
fi
WORKTREE_RESERVED=0
BRANCH_RESERVED=0
cleanup_new_worktree() {
  local path_clean=1
  if [[ "$WORKTREE_RESERVED" -eq 1 ]]; then
    if git -C "$WORKTREE_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
      git worktree remove --force "$WORKTREE_PATH" || path_clean=0
    else
      rmdir "$WORKTREE_PATH" 2>/dev/null || path_clean=0
    fi
    [[ "$path_clean" -eq 1 ]] || echo "Cleanup debt: inspect reserved path $WORKTREE_PATH"
  fi
  if [[ "$BRANCH_RESERVED" -eq 1 ]]; then
    if [[ "$path_clean" -eq 1 ]]; then
      git update-ref -d "refs/heads/$BRANCH" "$BASE_SHA" \
        || echo "Cleanup debt: inspect reserved branch $BRANCH"
    else
      echo "Cleanup debt: reserved branch retained: $BRANCH"
    fi
  fi
  return 0
}
if ! mkdir "$WORKTREE_PATH"; then
  echo "Could not reserve worktree path: $WORKTREE_PATH"
  exit 1
fi
WORKTREE_RESERVED=1
if ! git update-ref "refs/heads/$BRANCH" "$BASE_SHA" ""; then
  cleanup_new_worktree
  echo "Could not atomically reserve local branch: $BRANCH"
  exit 1
fi
BRANCH_RESERVED=1
if ! git worktree add "$WORKTREE_PATH" "$BRANCH"; then
  cleanup_new_worktree
  echo "Worktree creation failed; cleanup was limited to this invocation's reservations."
  exit 1
fi
ACTUAL_ROOT="$(git -C "$WORKTREE_PATH" rev-parse --show-toplevel)"
WORKTREE_REAL="$(cd "$WORKTREE_PATH" && pwd -P)"
if [[ "$(cd "$ACTUAL_ROOT" && pwd -P)" != "$WORKTREE_REAL" \
   || "$(git -C "$WORKTREE_PATH" branch --show-current)" != "$BRANCH" \
   || -n "$(git -C "$WORKTREE_PATH" status --porcelain)" ]]; then
  cleanup_new_worktree
  echo "Explicit worktree validation failed; stopping."
  exit 1
fi

# Reject tracked symlinks before mkdir/write can follow them outside the
# assigned worktree. The lexical PLAN_DIR gate above makes these components
# relative and traversal-free.
SPEC_PARENT="$WORKTREE_PATH/$PLAN_DIR"
PATH_CURSOR="$WORKTREE_PATH"
IFS='/' read -r -a PLAN_PARTS <<< "$PLAN_DIR"
for PLAN_PART in "${PLAN_PARTS[@]}"; do
  PATH_CURSOR="$PATH_CURSOR/$PLAN_PART"
  if [[ -L "$PATH_CURSOR" ]]; then
    cleanup_new_worktree
    echo "Spec path contains a symlink; stopping before writing outside the worktree."
    exit 1
  fi
done
if ! mkdir -p "$SPEC_PARENT"; then
  cleanup_new_worktree
  echo "Could not create the spec directory; stopping."
  exit 1
fi
SPEC_PARENT_REAL="$(cd "$SPEC_PARENT" && pwd -P)"
SPEC_PATH="$SPEC_PARENT/$SPEC_FILE"
if [[ "$SPEC_PARENT_REAL" != "$WORKTREE_REAL"/* || -e "$SPEC_PATH" || -L "$SPEC_PATH" ]]; then
  cleanup_new_worktree
  echo "Spec destination is outside the worktree or already exists; stopping."
  exit 1
fi

2. The preflight has resolved a new, non-symlinked destination as SPEC_PATH. Write the approved spec to exactly that path, then require git -C "$WORKTREE_PATH" status --porcelain --untracked-files=all to equal exactly ?? $PLAN_DIR/$SPEC_FILE. If the write or check fails, remove this newly created worktree and branch as in the preflight and stop. Do not create plan.yaml or state.json.
3. Read references/pr-subagent-template.md and assemble the prompt from its Standard Prefix, the full spec content, and Standard Suffix. Apply the same {SIZE}, {SELECT}, and {GATE} rules as the Claude path, and substitute {REPO_ROOT}, {WORKTREE_PATH}, {BASE_BRANCH}, {BASE_SHA}, {BRANCH}, {TITLE}, {PR_ID}, {PLAN_DIR}, and {SPEC_FILE} with their concrete values. Leave only {PR_NUMBER} for the child to resolve after PR creation.
4. Inspect the callable spawn_agent agent types. Use the descriptor's custom specialist only when that exact type is available; otherwise use the built-in worker. Spawn exactly one child with fork_turns="none", a unique task name, and the assembled self-contained prompt. Do not request automatic isolation: the absolute worktree already exists and the prompt assigns that directory as the child's only file ownership.
5. Wait for the child, giving the user a brief update at least once per minute. Its final answer must be one JSON object matching the template's result schema. Reject missing fields, extra fields, invalid types, or surrounding prose. A failed or blocked result, invalid output, interruption, or tool failure retains the worktree, local branch, and any PR for recovery and reports their exact paths/identifiers; never dispatch a replacement child.
6. A child-reported success is provisional. Capture WORKTREE_HEAD from git -C "$WORKTREE_PATH" rev-parse HEAD, then poll gh pr view for at most five 10-second attempts. Require all of: the reported PR is MERGED, its headRefName is BRANCH, its headRefOid is exactly WORKTREE_HEAD, its base is BASE_BRANCH, and mergeCommit.oid is non-null. Fetch the base and require the merge commit to be an ancestor of origin/$BASE_BRANCH. If any check fails, retain recovery state and report failure instead of cleaning up.
7. After verified merge, probe git ls-remote --heads "$PUSH_REMOTE_URL" "refs/heads/$BRANCH" and inspect both its exit status and output. Only a successful empty result confirms the child deleted the remote branch; a probe failure is cleanup debt. If the ref still equals WORKTREE_HEAD, try this conditional deletion once and re-probe: git push --force-with-lease="refs/heads/$BRANCH:$WORKTREE_HEAD" "$PUSH_REMOTE_URL" ":refs/heads/$BRANCH". A lease failure or surviving ref is cleanup debt without changing the verified merge to failure. If the remote ref moved to another OID, never delete it automatically; report the mismatch for manual inspection. Then remove the child worktree without --force, delete only the verified local child branch, and fast-forward the still-clean caller checkout to origin/$BASE_BRANCH. Any cleanup or fast-forward failure is likewise a warning attached to the verified success. Print the completion report below using the validated child result.

The Codex lifecycle is: inline implementation plan → /plan-review internal → implement + test → commit + push + PR → /greenlight unattended → exact-head CI → /merge-pr → parent-verified merge and cleanup → structured report. There are no Codex retries, waves, schedules, Workflow calls, or implicit worktrees in V1.

Single-PR + schedule and Multi-PR (CronCreate path)

1. Ask the user for the desired execution time
2. Read references/orchestrator.md for the CronCreate prompt template
3. Fill the plan path into the template
4. Create a one-time schedule with CronCreate

CronCreate(
  cron="<user-specified time>",
  recurring=False,
  prompt="<orchestrator.md template, with plan_dir path filled in>"
)

5. Remind the user:
   • The schedule is session-only — Claude Code must remain open
   • If the session is interrupted, the orchestrator prompt can be pasted manually to resume (state.json tracks progress)
   • No manual intervention needed during execution (unless blocked)

Completion Report (single-PR + run now)

On success:

Autopilot Single-PR done
═════════════════════════
✅ #91 feat(scope): <summary> — 2 rounds, fixed 1, pushed back 0
   merged into main
   spec: docs/loops/<YYYY-MM-DD>_<short-name>/pr1-<short>.md

On block:

❌ blocked: feat(scope): <summary>
   reason: <error from subagent>
   spec: docs/loops/<YYYY-MM-DD>_<short-name>/pr1-<short>.md
   recovery: fix manually and resume, or re-run /autopilot

Important Notes

• This skill is interactive — each step requires user confirmation before proceeding
• Todos have typically already been through eng-review; no need to re-evaluate architecture direction, only confirm the PR split is reasonable
• Spec file quality directly determines execution success rate — better to spend extra time writing clearly