handoff-progress-pr

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