Handoff Progress PR

Contract

Prereqs:

• •Run inside the target git repo.
• •git and gh available on PATH, and gh auth status succeeds.
• •Planning PR body contains a ## Progress section with a docs/progress/... link (preferred), or you pass --progress-file explicitly.

Inputs:

• •Planning PR number (or current-branch PR).
• •Optional: progress file path (when PR body is missing/ambiguous).
• •Optional: merge/cleanup flags (keep branch, skip checks, patch-only).

Outputs:

• •Planning PR merged and closed; remote head branch deleted by default (best-effort via git push origin --delete, unless --keep-branch).
• •Planning PR body ## Progress link patched to point to the base branch (survives branch deletion).
• •Implementation guidance: create one or more feature PRs that link back to the planning PR and the progress file.

Exit codes:

• •0: success
• •non-zero: missing progress link/file, merge blocked, or git/gh command failures

Failure modes:

• •Planning PR is draft (must mark ready first).
• •Required checks failing or PR not mergeable.
• •Multiple docs/progress/... links in the PR body (must choose one via --progress-file).
• •Progress link breaks after merge because it still points to the deleted head branch (this skill prevents that).

Setup

• •Ensure gh auth status succeeds.
• •Ensure the working tree is clean if you plan to merge (stash/commit unrelated work first).

Key rules

Progress links must survive branch deletion

If the planning PR is merged and the head branch is deleted, any link like:

• •https://github.com/<owner>/<repo>/blob/<head-branch>/docs/progress/...

will break.

After merge, patch the planning PR body ## Progress link to point to the base branch:

• •https://github.com/<owner>/<repo>/blob/<base-branch>/docs/progress/...

Implementation PRs must reference the planning PR

When creating feature PRs for implementation:

• •Add a clear link back to the planning PR (for traceability).
• •Keep linking consistent across multiple implementation PRs (same planning PR + same progress file).

Recommended pattern for feature PR bodies:

• •Keep ## Progress as-is (link to the progress file).
• •Add ## Planning PR:
  • •- #<number>

Workflow

1. •Identify the planning PR number
   • •Prefer current branch PR: gh pr view --json number -q .number
2. •Resolve the progress file path
   • •Prefer parsing the planning PR body ## Progress link for a docs/progress/... path
   • •If missing/ambiguous: pass --progress-file docs/progress/<file>.md
3. •Merge the planning PR (docs-only)
   • •Ensure checks pass: gh pr checks <pr> (optional but recommended)
   • •If draft, mark ready: gh pr ready <pr>
   • •Merge (merge commit):
     • •gh pr merge <pr> --merge (add --yes when available)
   • •Best-effort delete the remote head branch (unless --keep-branch):
     • •git push origin --delete <headRefName>
4. •Patch the planning PR body Progress link to base branch
   • •Ensure the ## Progress link points to blob/<base-branch>/docs/progress/...
5. •Kick off implementation PR(s)
   • •Use create-feature-pr to implement and open one or more feature PRs.
   • •In each implementation PR body:
     • •Link the progress file (full GitHub blob URL).
     • •Add a ## Planning PR link back to this planning PR.
   • •In the first implementation PR, update the progress file Links block to include the planning PR for long-term traceability:
     • •Add: - Planning PR: <planning PR url> (if missing)

Optional helper script

• •Use $CODEX_HOME/skills/workflows/pr/progress/handoff-progress-pr/scripts/handoff_progress_pr.sh to merge and patch deterministically (best-effort remote delete; local cleanup is warning-only):
  • •bash $CODEX_HOME/skills/workflows/pr/progress/handoff-progress-pr/scripts/handoff_progress_pr.sh --pr <number>
  • •If already merged but links are broken: --patch-only