Ship a completed branch to a pull request with ak:ship

Use ak:ship when implementation on a feature branch is complete and you want one workflow to prepare it for review. The Skill synchronizes the target branch, runs test and review gates, updates applicable release artifacts, commits and pushes the branch, then creates or updates an evidence-rich GitHub pull request. With --merge, it hands that PR to ak:review-pr for review, fixes, replies, merge, and CI convergence. Without --merge, it does not merge the PR. It never deploys the application.

Choose ak:ship for PR preparation

Use ak:ship when

• The branch is complete enough to enter official or beta review.
• You want tests, pre-landing review, versioning, changelog, documentation, Git, issue linkage, and PR creation coordinated in one pipeline.
• The repository uses GitHub and the branch can be pushed normally.
• You are ready for every current worktree change to be considered for the ship commit.

Choose another workflow when

• You still need implementation. Use ak:cook.
• You only need local verification or review. Use ak:test or ak:code-review.
• The pull request already exists and only needs review, repair, reply, or merge. Use ak:review-pr.
• You want to publish a built application. Use ak:deploy after the release gates and repository policy allow it.

Prepare the branch and GitHub access

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Run from a feature branch, never the intended target branch.
• Inspect git status, including untracked files. Move unrelated work out of the worktree because the pipeline intentionally includes all changes.
• Ensure the target remote branch and the project's test command are available.
• Install and authenticate gh with issue and pull-request permissions, and confirm normal Git push access to the feature branch.
• Decide whether version, changelog, journal, docs, issue creation, plan state, commit, push, and PR writes are all intended.

Select the release path and gates

Automatic technical-journal behavior resolves in this order: --skip-journal, project journal.auto, user journal.auto, then the default true. A preference-resolution error or any unexpected output keeps journaling enabled. journal.auto=false skips the automatic journal but does not suppress an explicit --social; --skip-journal still suppresses the entire social step.

/ak:ship official

/ak:ship official

$ak:ship official

Run --dry-run first when target detection or included files are uncertain. Multiple or unknown mode tokens and unrecognized flags stop for clarification instead of being guessed. A strong request states the intended target branch, existing test evidence, version policy, related issue, files that must not ship, and whether creating a new issue is acceptable.

Follow the observable pipeline

1. Pre-flight resolves the release. The Skill normalizes mode aliases and checks the current branch, target, status, diff, and commits. Running on the target branch aborts. With --advice, kongming gives a go/no-go and risk checkpoint before mutation.
2. Issue linkage is established. Existing issues are found from branch and commit evidence; when none is found, the workflow can create a structured GitHub issue for traceability.
3. The target is merged locally. It fetches and merges origin/<target> so later checks exercise the combined state. Complex conflicts stop the run.
4. Tests and review run. The detected test runner executes unless skipped, followed by a two-pass critical and informational review unless skipped. Test failures block shipping. Critical findings require a fix, explicit risk acceptance, or false-positive decision. With --advice, a second kongming checkpoint evaluates this evidence before any release or GitHub writes.
5. Release artifacts are updated. A detected version source receives a patch bump by default; significant changes require a minor-or-patch decision. Existing changelogs receive a generated entry.
6. Journal, docs, and plan state are handled. Journal and official docs tasks run in the background unless skipped. A resolved plan is checked and marked completed only when evidence supports it; its index stays active until merge.
7. Everything intended is committed and pushed. git add -A stages all current changes, scans the staged diff for secrets, creates a conventional commit, and performs a regular push without force.
8. The PR is created or updated. The body records end-to-end work, delegation, decisions, plan deviations, evidence, checklist, human actions, linked issues, and ship mode in the configured writing language. The title remains an English conventional commit.
9. Plan linkage is recorded. When a plan was finalized, its index records the PR number so the later merge workflow can close it safely.
10. Optional review and merge converges. With --merge, ak:review-pr owns PR review, fixes, replies, merge readiness, merge, and post-merge CI. The ship stops unless it reports approval, a completed merge, and green CI.
11. Dual-target shipping advances carefully. With --both, the beta stage runs first. The stable stage starts only after a beta PR exists and, with --merge, its merge CI is green. A promotion-based repository can instead report the stable stage as pending the beta merge.

Understand the write boundary

The pipeline can create or modify all of the following:

• Local merge state, conflict resolutions, source fixes, version files, changelog, journal, docs, and plan files.
• One or more local commits, including review fixes and the final ship commit.
• The remote feature branch through a normal push.
• A GitHub issue when no related issue is found.
• One or, with --both, two pull requests, or the title and body of existing pull requests.
• With --merge, review replies, fixes, merges, and post-merge CI convergence through ak:review-pr.

Safety gates remain:

• Staged secret detection stops the commit. Never add a credential merely to keep the pipeline moving.
• Push is never forced. A rejected push can use one deliberate rebase retry; destructive history rewriting is outside the workflow. Neither --merge nor --both bypasses branch protection or required checks.
• Missing gh stops after the push, so a pushed branch is not evidence that a PR exists.
• Background journal or docs work can finish after later steps have started; verify its files are present before accepting the final commit evidence.
• Without --merge, ak:ship does not merge the PR. Even with --merge, it does not close the plan index, publish a release, or deploy an application. Those require later workflows and separate authority.

Verify the handoff

A complete result should include:

• Canonical mode, source branch, target branch, commit count, and diff summary; with --both, separate beta and stable stage status.
• Linked or created issue numbers.
• Target-merge result, test command and counts, and review findings or explicit skip evidence.
• Version change, changelog, journal, docs, and plan results when applicable.
• Final commit SHA, pushed remote branch, and each validated PR URL.
• Advice checkpoint status when --advice was requested, plus review verdict, merge status, and CI status when --merge was requested.
• An evidence-rich PR body with honest None, Not run, or Unavailable markers instead of invented activity.
• Any human action, accepted critical risk, missing screenshot, pending CI, or unresolved question.

Release tests directly cover writing-language resolution and the EN/VI PR-body section contract. They do not exercise the full fetch, merge, test, background task, commit, push, issue, and PR pipeline against a live repository.

Troubleshoot without bypassing gates

After the PR exists, use ak:review-pr for review and merge readiness. Use ak:deploy only after the repository's release gates permit publication.