Deploy

---
name: deploy
description: "Commit pending task changes, deliver them through the repository's configured PR, branch, or local workflow, and close out merged work."
argument-hint: "Optional: the base branch, a merged change request to close out, or a note for delivery"
disable-model-invocation: true
license: MIT
---

# Deploy

Take the branch from "I am happy with it" to delivered and closed out. The user's invocation authorizes the commit and delivery within the repository's configured policy. The default route pushes the branch, opens or updates its change request, merges it, closes out its linked work, and verifies production when `workflow.md` assigns that to the agent. A human approves every production release, through the deployment system's gate or invocation approval (step 5); deploy only triggers one, through a merge. Load each dependency named below through the available skill invocation mechanism or its installed `SKILL.md`; when one is not installed, follow the fallback given with it and report the missing skill as a gap.

Once the change request is registered with the harness, tell a pause from a stop. Step 4's wait for the watcher is a pause: keep the registration, end the turn, and resume when the watcher wakes you. A question to the user from step 5 is a pause too: stop watching before you ask, and resume on the answer. Every other stop ends the run, including the final report: stop watching the change request first so control returns to the user.

When any stop leaves an open change request unmerged, remove its `agent-merge` label, so it reads as awaiting a person; a later run adds it back when step 3's conditions hold.

Read `docs/agents/code-host.md` for delivery operations, `docs/agents/workflow.md` for the delivery mode, base branch, merge strategy, actors, closure events, and production verification, and, when the work links tickets, `docs/agents/issue-tracker.md` for their operations. `workflow.md` is authoritative for the base branch and merge strategy; take each from `code-host.md` only when `workflow.md` does not record it. Reuse their unchanged contents from context. Without them, use the repository's contribution rules, the host CLI, and the host's default merge method.

Choose the delivery route before any remote or change-request operation. Use the hosted change-request route unless the repository explicitly configures local delivery, branch-only delivery, or another review equivalent. For an alternative, record its operation, destination, actor, prerequisites, and completion evidence from the configuration; report missing decisions before delivery. A local destination makes delivery local-only: use local refs and operations throughout, with no fetch, push, or code-host calls. Both routes share steps 1 and 2; alternatives then use **Delivery without a change request** below instead of steps 3 through 5.

<!-- shared: delivery-base -->
Resolve the delivery base before changing branches: the user's branch argument, then the configured base branch, then the default branch. Record the intended changes: the user's request plus any cleanup or review record, else the batch step 1 finds. Keep cleanup's review base and checked content so its batch can be told from inherited branch history; when committing leaves that content unchanged, reuse its check record.
<!-- /shared: delivery-base -->

**After a merge.** On the hosted route, look up the current branch's change request before step 1. When it is merged, or the user names a merged change request, skip steps 1 through 4: run step 5's **Verify** and then step 6 for that change request. This route resumes close-out after a human merges on the host, and finishes production verification that was pending when an earlier run ended. When the current branch also holds pending task changes or commits after the merged head, deliver them afterward from step 1, unless the user named the change request; then report them instead. When the user names a change request that is not merged, report its state and stop.

<!-- shared: prepare-delivery -->
1. **Commit pending changes first.**
   - **Scope.** Inspect staged, unstaged, and untracked files, including edits left by `/clean-up`. Preserve unrelated work, such as local environment files and generated output.
   - **Batch.** The batch is the pending task changes plus committed changes the destination does not yet contain, compared by content so squash-merged work counts as delivered, and judged against the fetched remote base, or the local destination ref for local-only delivery. With an empty batch, say so and stop. Commits on the resolved base that the destination lacks belong to the batch unless the user calls them unrelated; commits the cleanup report lists as unreviewed are unchecked, not unrelated, and step 2 checks them.
   - **Branch.** On the resolved base or default branch, create a task branch named for the change at the current HEAD, or at the fetched base when the base's extra commits are unrelated, and carry the pending task changes onto it. For hosted delivery on a branch whose change request is merged or closed, create it from the resolved base and carry the batch onto it. Otherwise stay on the current branch. When the base holds batch commits, report that it needs realigning after delivery.
   - **Commit.** With no pending task changes, record the current HEAD and continue to step 2. Otherwise run the checks `workflow.md` requires before a commit, reusing a check record that covers the same content, then stage and commit only the task's changes in the repository's message convention, letting hooks run. If a hook rejects the commit, leave the changes staged on the current branch, report its output and the branch, and stop. Verify that the commit contains the intended changes.

   Done when the batch is committed and the commit to deliver is recorded.
2. **Check the scope and prepare delivery.**
   - **Sync.** For local-only delivery, record the current local base and destination refs and skip remote synchronization. For a remote route, refresh the configured remote base and tracking branch. When that tracking branch has commits the local branch lacks, compare them with the local commits (for example with `git range-diff`) to tell genuinely new commits from ones the local branch rewrote by an amend or a local rebase. Replay only the genuinely new remote commits onto the local branch (for example with `git cherry-pick`), keeping the local versions of rewritten ones. Resolve each conflict preserving both sides' intent, and stop to ask when intent is unclear. Record each conflict resolution this step makes, here or in a transplant, and each remote commit it replays.
   - **Match the scope.** Compare the full delivery patch and commit range against the intended changes. Existing divergence between the starting branch and delivery base stays outside the task unless step 1 put it in the batch or the user included it. If it adds unrelated changes, preserve the original branch, transplant only the intended batch onto a new branch from the resolved base, and, for hosted delivery, report any open change request on the original branch so the user can close or retarget it. If the batch cannot be isolated without a scope or behavior decision, report that decision and stop before delivery.
   - **Cover the delivery.** Load and apply `code-cleanup` and then `code-review` to any transplanted or rebased result and to any delivered change that no cleanup or review record covers, such as work that step 1 committed and `/clean-up` did not check, reusing only evidence whose inputs remain unchanged. With no cleanup or review record in the session, as when `/clean-up` ran in another session, that is the full delivery diff. Without `code-cleanup`, run the checks `workflow.md` requires (else the repository's formatter, linter, type check, and tests for the touched code) and inspect the diff for leftover debris; without `code-review`, review the full diff locally against the intended changes for correctness, requirements, and maintainability. Leave any cleanup edit uncommitted for the next `/clean-up` run. When no fresh check record covers the head, run the checks `workflow.md` requires before delivery. Checks that need the published branch run after the push.
   - **Ready.** Proceed only once the delivery diff matches the intended scope, required checks before delivery pass, cleanup made no edits, and review findings are resolved under repository policy. When only deferred checks prevent delivery, stop before delivery, report each check's resume condition and the way to resume it, and continue from step 2 with cleanup's record when this skill runs again after a resume condition is met. For other unresolved conditions, stop before delivery, report the decision each needs, and recommend settling those in the conversation, then running `/clean-up` and this skill again. Record the checked head and destination revision. For hosted delivery, push and set the upstream when there is none. Use a force push with a lease only when the branch was rebased or rewritten and belongs to this work.
   <!-- /shared: prepare-delivery -->

   Done when the delivery is checked and, for hosted delivery, the remote branch matches the checked local one. For an alternative route, continue at **Delivery without a change request**.
3. **Open or update the change request.** Find the open change request for this branch and use the resolved base. Load and apply `pr` to create one when none exists, or to refresh the title and description when the diff changed since it was written (without it, write the title per `docs/agents/code-host.md` and the description from the repository's pull request template). Mark a draft ready. Where the code host supports labels, label the change request `agent-merge` when step 5 can merge it without waiting for a person: `workflow.md` does not assign the merge to a human and records no approval before it beyond invocation approval; the code host requires no approving review; and the merge does not deploy to production without a recorded deployment-system approval gate or invocation approval. Create the label when the repository lacks it. When any of these conditions fails, remove the label instead, if the change request carries it. The label lets reviewers tell this change request from one awaiting their review; report a labeling failure and continue. When the harness tracks pull requests, register the change request with it so the harness can follow its checks and merge. Done when an open, non-draft change request targets the base, describes the current diff, carries the `agent-merge` label exactly when this step's conditions hold or the report says why labeling failed, and is registered with the harness when it supports that.
4. **Wait for checks.** With a harness pull-request watcher, hand the change request to it while checks run or an approval the user's account cannot give is outstanding: report what is pending, end the turn, and resume here when the watcher wakes you. Without one, poll for up to 15 minutes. Stop on a failing check, a conflict with the base, a review comment that asks for changes, or anything still pending when the poll ends: report what blocked it, and recommend fixing it in the conversation, then `/clean-up` and `/deploy` again. Done when every check has passed on the head, no review comment asks for changes, and the host reports the change request mergeable.
5. **Merge.**
   - **Restart.** Read the change request first: a merged one goes to **Verify**, reporting a merged head that differs from the checked one. If the head changed since the scope check, or the change request now targets a different base, return to step 2 and follow the remaining steps for the resulting branch and change request; on a second such change, report it and stop. A base branch that only moved ahead needs no restart, since the host refuses a merge that is no longer clean.
   - **Actor.** When `workflow.md` assigns the merge to a human, stop and report the change request ready for that merger, leaving step 6 pending on the merge. When it assigns invocation approval, read [INVOCATION-APPROVAL.md](INVOCATION-APPROVAL.md) and follow it: it checks the acting account, asks about drift, and merges or stops. When merging into the base deploys to production, such as through a CI workflow that deploys on push to that branch or a hosting configuration whose production branch is the base, and `workflow.md` records neither a deployment-system approval gate nor invocation approval, stop the same way: report the change request mergeable and that its merge would deploy, and recommend `/setup-snappedly-skills` to record the release policy. Otherwise merge with the configured operation and strategy, matched to the verified head commit.
   - **Verify.** Verify the host's completed merge record for the merged head and target base, then confirm that the resulting merge commit, squash commit, or final rebased commit is in the remote base's history. Squash and rebase merges can replace the original head's identity. If the host reports success but the resulting commit cannot be verified, report the merge as unverified and stop before branch deletion or ticket closure; do not retry the merge. After verification, a remote head branch is eligible for deletion only when the host has not already deleted it and it is a task branch this work created or one that exists only for this change request. Keep any other branch, such as the base or default branch, a protected branch, or a long-lived branch that `workflow.md` names or other change requests target, and say so. Before deleting an eligible branch, require its current remote tip to equal the change request's original head at merge, even for squash or rebase merges. Make deletion conditional on that exact tip, such as a Git deletion with an explicit `--force-with-lease`. Keep and report the branch when its tip differs or cannot be checked, the deletion condition fails, or conditional deletion is unavailable. Update the local base branch when a checkout of it is clean.

   Done when the host reports the change request merged and its resulting commit is verified on the target base.
6. **Close out.**
   - **Production.** When `workflow.md` assigns production verification to the agent and the change request merged into the branch that releases to production, find the release whose deployed revision contains the resulting commit, polling for up to 15 minutes when the merge starts it. Once that release has completed, read the currently deployed production revision from the deployment system and require it to contain the resulting commit. Run the verification `workflow.md` records, then read the deployed revision again. Count verification as passed only when the checks passed against the same deployed revision throughout, and report that revision with the evidence. A historical successful release alone does not establish this. When the deployed revision lacks the commit, cannot be established, or changes during the checks, report the deployment state and leave verification and its dependent closures pending. A failed or cancelled release, or a failed check, fails verification: report it with the recorded recovery procedure and leave recovery to its configured actor. A release that has not started, waits on another actor, or is still running when the poll ends leaves verification pending: report it.
   - **Closures.** Verify each closure event that the completed delivery and any production verification satisfy and `workflow.md` assigns to the agent or to provider automation: linked executable tickets closed, and the parent spec closed where its separate acceptance condition is met. A branch publication does not satisfy a merge-time event. Close each item assigned to the agent that is still open, then verify it. Report an item assigned to provider automation that did not transition, with its evidence, rather than closing it for the automation. When the spec stays open and every child ticket is now closed, do what `workflow.md` records for that moment: comment on the spec that it is ready for acceptance unless it already carries that comment, or only report it; with nothing recorded, report it. Without a configured workflow, close only executable tickets the change request links with a closing keyword, such as `Closes #12`, leaving planning specs and merely mentioned items open, and report any parent whose children are all closed.

   Done when every satisfied transition assigned to the agent is verified, every one assigned to provider automation is verified or reported, production verification assigned to the agent has passed, failed with its evidence, is reported pending, or does not apply to this merge, and pending events and transitions assigned to a human are reported with their evidence.

Report the commit, delivery mode and destination, branch and base, change request or review record when applicable, the approval the merge used, check results, verified delivery revision, ticket states, production verification, the delivered changes deploy cleaned up and reviewed itself, what `workflow.md` says happens next when it records a production release, and anything stopped or pending with its reason. When step 6 is pending, say that `/deploy` again on the branch, or naming the change request, resumes it once the merge or release has happened.

## Delivery without a change request

Use the configured review equivalent and delivery operation after step 2. Bind its review and approval evidence to the checked head and destination. If either revision changed, return to step 2; stop on a second such change. When the next action belongs to a human or provider automation, report the prepared revision, pending action, and required evidence instead of acting for them.

For an agent-owned action, satisfy its recorded prerequisites and deliver the checked revision to the configured destination. Branch-only delivery leaves that revision on the configured local or remote branch without a merge. Local delivery records the checked local branch or merges it into the configured local base, as the workflow directs. Integration-branch delivery uses its configured strategy and destination. Preserve unrelated work and require a clean destination checkout before a local merge. Apply step 2's conflict handling and recheck any resulting code changes before delivery.

Read back the destination state after the operation. For branch publication or local branch delivery, verify the destination ref equals the checked head. For a merge, verify that the resulting commit represents that head and is in the destination's history, accounting for squash or rebase identity changes. Run any required checks that become available only after delivery. When verification fails or remains pending, report the delivered revision and missing evidence, leave closures pending, and stop without repeating the delivery. Done when the configured destination and completion evidence verify the delivered revision; continue at step 6.