---
name: deliver-github-pr
description:
  "Deliver GitHub pull requests end to end with one provider-specific workflow: preflight, create via create-github-pr, wait/fix checks until green, then close via close-github-pr."
---

# Deliver GitHub PR

## Contract

Prereqs:

- Run inside the target GitHub-backed git repo.
- `git`, `gh`, and `python3` available on `PATH`, and `gh auth status` succeeds.
- Working tree may be dirty before preflight; preflight must run scope triage first.
- Working tree must be clean before close/merge.
- Companion skills available: `create-github-pr`, `close-github-pr`, and
  `code-review-specialists`.

Inputs:

- `kind=feature|bug`.
- Feature or bug summary, target branch, testing notes, and PR number when closing an existing PR.
- Optional base branch for preflight (default: `main`).
- Mandatory pre-close specialist review using the shared delivery specialist
  review gate; this is an orchestration gate, not a script flag.
- Optional user authorization to fix concrete pre-close review findings before
  close.
- Optional close controls: `--allow-no-checks`, `--keep-branch`, and `--no-cleanup`.
- Optional ambiguity bypass flag for preflight: `--bypass-ambiguity` (alias: `--proceed-all`). Use only after explicit user confirmation
  that suspicious files are in scope.

Outputs:

- Branch created from the confirmed base branch when new work is needed:
  - `kind=feature` -> `feat/<slug>`
  - `kind=bug` -> `fix/<slug>`
- A GitHub PR created through `create-github-pr`.
- Required GitHub checks green; failed, pending, skipped, or blocked required
  checks are fixed before close. Optional skipped checks are reported by GitHub
  but do not block delivery.
- A `code-review-specialists` review pass completed before close with at least
  `testing` and `maintainability` forced, even for small diffs.
- A delivery review outcome comment posted to the PR before close, using
  `agent-kit:delivery-review-outcome:v1`, listing review lenses, validation,
  provider checks, concrete finding dispositions, and the merge/block decision.
- PR marked ready when draft, merged, and cleaned up through `close-github-pr`.
- `deliver-github-pr` is successful only after close/merge is complete; create-only is not a successful delivery outcome.
- Plan-tracking issue lifecycle blockers reported by `close-github-pr` are treated as real delivery blockers, not partial success.

Exit codes:

- `0`: success
- `1`: workflow blocked/failure (branch mismatch, checks failure, auth issues, command failure)
- `2`: usage error
- `124`: checks wait timeout

Failure modes:

- Initial branch is not the expected base branch (`main` by default):
  - Stop immediately and ask the user to confirm source branch and target branch.
- Required GitHub checks fail, are canceled, time out, are skipped, are blocked,
  or require action:
  - Do not merge; fix issues on the delivery branch, push, and re-run `wait-checks`.
- No checks exist for the PR:
  - Stop by default; continue only when the user explicitly supplied `--allow-no-checks`.
- Mandatory pre-close specialist review reports concrete findings:
  - If the user did not explicitly authorize fixing review findings before close, stop before close and ask whether to fix, accept, or abort.
  - If the user explicitly authorized fixes, repair the findings on the delivery branch, rerun validation and required checks, rerun the
    affected specialist review when useful, then re-enter close.
- Delivery review outcome comment cannot be posted:
  - Do not merge.
  - Report the failed `gh pr comment` command, exit status, and retry action.
- A PR would auto-close a plan-tracking issue whose latest issue-hosted execution state is incomplete:
  - Do not merge.
  - Re-enter `execute-from-tracking-issue` to post a complete state ledger, then merge and run `tracking-issue-closeout`.
- Skill conflict or ambiguity (branch target, merge strategy, source branch deletion, or "skip checks"):
  - Stop and ask the user to confirm the canonical workflow before continuing.
- PR remains draft and automatic `gh pr ready` fails during close.
- Missing `gh` auth/permissions, wrong GitHub repository, or non-mergeable PR.

## Scripts (only entrypoints)

- `$AGENT_HOME/skills/workflows/pr/github/deliver-github-pr/scripts/deliver-github-pr.sh`

## Workflow

1. Choose kind
   - Use `kind=feature` for feature delivery. Branch prefix is `feat/`.
   - Use `kind=bug` for bugfix delivery. Branch prefix is `fix/`.

2. Branch-intent preflight (mandatory)
   - Run:
     - `deliver-github-pr.sh --kind <feature|bug> preflight --base main`
   - Optional explicit bypass run:
     - `deliver-github-pr.sh --kind <feature|bug> preflight --base main --bypass-ambiguity`
   - Contract:
     - This delivery method starts from the confirmed base branch, creates or reuses a source branch, and targets the confirmed target branch.
     - Preflight must classify `staged`/`unstaged`/`untracked` changes and apply suspicious-signal triage.
     - If current branch is not `main` (or not the user-confirmed base), stop and ask the user.
     - `--bypass-ambiguity` only bypasses ambiguity block payloads after explicit user approval. It does not bypass branch guard, auth
       checks, or later checks gates.

3. Create PR
   - Use `create-github-pr` to:
     - create or reuse the source branch
     - implement + test
     - commit + push
     - open a draft PR by default

4. Wait for required checks and repair until green
   - Run:
     - `deliver-github-pr.sh --kind <feature|bug> wait-checks --pr <number>`
   - For repositories without checks, use explicit no-check acknowledgement:
     - `deliver-github-pr.sh --kind <feature|bug> wait-checks --pr <number> --allow-no-checks`
   - If any required check fails or blocks:
     - fix on the same delivery branch
     - push updates
     - re-run `wait-checks`
   - Do not proceed to close until required checks are green, unless the user explicitly confirms `--allow-no-checks`.
   - Optional skipped checks do not block when required checks pass.

5. Run mandatory specialist review
   - Follow the shared delivery specialist review gate:
     `skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`.
   - Resolve the PR number and base branch with `gh pr view`, then use the PR base branch as the `code-review-specialists` diff base.
   - Always run deterministic scope detection with forced minimum lenses:
     - `review_specialists.py scope --base <pr-base-ref> --testing --maintainability`
   - Do not skip specialist review only because the diff is small.
   - Add the shared risk lenses for security, API contract, data migration,
     performance, or red-team review when the PR scope warrants them.
   - Keep `code-review-specialists` read-only. Concrete findings are repaired
     by this delivery workflow on the PR branch, followed by validation,
     required checks, and affected specialist review reruns.

6. Post delivery review outcome comment
   - Follow the shared delivery review outcome comment contract:
     `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`.
   - Render a compact PR comment with marker
     `agent-kit:delivery-review-outcome:v1`, review lenses, validation,
     provider check status, and one row per meaningful review item.
   - Use dispositions `fixed-now`, `accepted-residual`, `follow-up-linked`,
     `deferred-task`, `no-action`, or `blocked`.
   - For `fixed-now`, the reason is optional but evidence and validation are
     required. For `accepted-residual`, `follow-up-linked`, `deferred-task`, and
     `blocked`, include the required reason and link or unblock evidence.
   - Post before merge:
     - `gh pr comment <pr> --body-file <comment.md>`
   - If review blocks delivery, post a blocked outcome comment when possible,
     then stop before close with the exact unblock action.

7. Close PR
   - Run:
     - `deliver-github-pr.sh --kind <feature|bug> close --pr <number>`
   - The close flow delegates to `close-github-pr` and:
     - requires a clean working tree
     - runs after the mandatory specialist review gate has passed or has been
       explicitly accepted under the delivery review policy
     - runs after the delivery review outcome comment has been posted
     - marks draft PRs ready with `gh pr ready <number>`
     - merges with a merge commit
     - allows missing checks only when `--allow-no-checks` is explicitly supplied
     - gates on required checks; optional skipped checks do not block
     - blocks plan-tracking issue auto-close when `execute-from-tracking-issue --require-complete` would fail
     - deletes the remote source branch unless `--keep-branch` is explicitly supplied
     - switches back to the target branch, pulls it, and deletes the local source branch unless cleanup is disabled

8. Report delivery artifacts
   - Include PR URL/number, checks status summary, specialist review lenses and
     outcome, delivery review outcome comment URL when available, merge result,
     target branch, and final branch state.

## Completion Gate

- If there is no blocking error, this workflow must run end-to-end through `close`.
- Do not stop after create/open PR and report "next step is wait-checks/close".
- A stop before `close` is valid only when a real block/failure exists (for example: ambiguity confirmation pending, checks still failing,
  mandatory review findings pending decision, user-authorized review fixes still failing, timeout, auth/permission failure,
  non-mergeable PR, or explicit user pause).
- User-authorized review fixes are a delivery repair loop, not a successful
  stopping point.
- Closing a PR without merge is cleanup/abort, not successful delivery.
- When stopping before `close`, report status as `BLOCKED` or `FAILED` with the exact unblock action; do not report partial success.

## Bypass Guidance

- Use `--bypass-ambiguity` (or `--proceed-all`) when:
  - preflight returns `BLOCK_STATE=blocked_for_ambiguity`
  - the user explicitly asks to continue despite ambiguity
  - the changed paths are confirmed in scope for the requested delivery
- Do not use bypass when:
  - branch guard fails
  - authentication/permission checks fail
  - checks fail or block
  - checks are missing and `--allow-no-checks` was not explicitly supplied
  - handling draft-state PRs
  - mergeability or repository policy checks fail

## Stop-And-Confirm Output Contract

- When preflight blocks for ambiguity, return a deterministic block payload and exit `1`.
- Required fields:
  - `BLOCK_STATE`: must be `blocked_for_ambiguity`
  - `CHANGE_STATE_SUMMARY`: counts for `staged`, `unstaged`, `untracked`, and `mixed_status=true|false`
  - `SUSPICIOUS_FILES`: list of paths flagged by suspicious-signal triage
  - `SUSPICIOUS_REASONS`: one reason per suspicious file
  - `DIFF_INSPECTION_RESULT`: per file classification `in-scope|out-of-scope|uncertain`
  - `CONFIRMATION_PROMPT`: explicit user action request to proceed or abort
  - `NEXT_ACTION`: must state "wait for user confirmation before continuing"

## References

- Shared delivery specialist review gate:
  `skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`
- Shared delivery review outcome comment:
  `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`
