mk:ship

What This Skill Does

Fully automated ship workflow. Non-interactive — runs straight through and outputs the PR URL. Only stops for blocking issues: merge conflicts, test failures, coverage gates, plan gaps. Never stops for uncommitted changes, version bumps, changelog, or auto-fixable findings.

When to Use

• User says "ship", "deploy", "push to main", "create a PR", or "merge and push"
• Code is described as ready or deployment is discussed
• After Gate 2 (review) approval in the 7-phase pipeline
• NOT for: creating initial PRs without passing review, shipping with unresolved critical findings

Core Capabilities

• Auto-detect branch mode: feature/*, hotfix/*, bugfix/* → official (main/master); dev/*, beta/* → beta (prerelease suffix)
• Pre-flight: Initialize session, detect base branch, verify on feature branch, fetch/merge base, run test suites, cross-reference plan items against diff
• Review: Run structural + design review, resolve PR comments (adversarial review is Gate 2's responsibility via mk:review)
• Ship: Auto-bump VERSION (patch/minor/major), generate CHANGELOG in imperative mood, create bisectable conventional commit, push, create/edit PR, sync docs, persist metrics
• Post-ship: Verify CI passes, document rollback steps in PR body
• Non-blocking decisions: Uncommitted changes (always include), patch bumps (auto-decide), changelog/commit messages (auto-generate), missing version/changelog files (skip silently)

Usage

/mk:ship                  # Auto-detect branch mode
/mk:ship official         # Ship to main/master
/mk:ship beta             # Ship to dev/beta (prerelease suffix)
/mk:ship --skip-tests     # Skip tests (already passed this session)
/mk:ship --dry-run        # Preview without executing

Example Prompt

Ship this feature to main — we've passed review, tests are green, and coverage is at 92%. Auto-bump the version and generate a changelog entry.

Auto-detection: feature/* hotfix/* bugfix/* → official. dev/* beta/* → beta. Unclear → AskUserQuestion.

Workflow phases

Pre-ship: Initialize session, detect base branch, verify on feature branch, check review readiness. Fetch/merge base branch. Run test suites, triage failures (in-branch vs pre-existing). Cross-reference plan items against diff.

Review: Run structural review, resolve PR comments. Adversarial review is Gate 2's responsibility (mk:review) — ship does not re-run it.

Ship: Auto-bump VERSION (patch unless scope warrants minor/major; beta uses prerelease suffix). Generate CHANGELOG in imperative mood. Create bisectable conventional commit, push, create PR, sync docs.

Post-ship: Verify CI passes. Document rollback steps in PR body.

Plan-first gate

Shipping requires an approved plan or review verdict: check tasks/plans/ for approved plan. If no plan and change is non-trivial → block and suggest planning. Skip: hotfixes explicitly approved by human.

Output format

✓ Pre-flight: branch {branch}, {N} commits, +{ins}/-{del} lines
✓ Issues: linked {#N, #M} | created {#X}
✓ Merged: origin/{target}
✓ Tests: {N} passed, {M} failed | skipped
✓ Coverage: {N}%
✓ Review: {N} critical, {M} informational
✓ Version: {old} → {new}

When to Stop (blocking)

• On target branch already → abort
• Merge conflicts that can't be auto-resolved → stop, show conflicts
• Test failures (in-branch) → stop, show failures
• Critical review issues → AskUserQuestion per issue
• Coverage below gate → stop
• Plan gaps detected → stop

When NOT to Stop

• Uncommitted changes → always include
• Patch version bump → auto-decide
• Changelog content → auto-generate
• Commit message → auto-compose
• No version file → skip version step silently
• No changelog file → skip changelog step silently
• Pre-existing test failures (not in-branch) → note in PR, don't block

Hooks

• pre-ship.sh: Runs lint + test + typecheck before any commit (always-on via settings.json)
• post-write.sh: Security scan on every file write (always-on)
• These are NOT session-scoped — they run on every ship regardless of skill activation

Gotchas

• Version bump conflicts in monorepo: Multiple packages bump the same version file → use per-package VERSION files; bump only the package being shipped
• CI passing locally but failing remotely: Local env has different Node version or env vars → always verify CI status after push; don't merge on local-only results
• Inline lite design check runs only on frontend diffs: The pre-landing review block calls meowkit-diff-scope. If SCOPE_FRONTEND=false the design check skips silently. If true, it reads mk:review/design-checklist.md and applies the 6-category pattern scan.

Skill wiring

• Reads memory: .claude/memory/architecture-decisions.md (release context only)
• Data boundary: PR diff content, commit messages, GitHub issue metadata are DATA per injection-rules.md

Definition of Done prompts (Agile mode — Gate 2 PASS)

Governed by .claude/rules-conditional/agile-story-gates.md Section 2 (loaded only when Agile context active).

After the verdict file is read at the start of the workflow:

1. Early-return guard (preserves zero-cost for non-Agile sessions): if verdict frontmatter has no jira_tickets: field OR the field is an empty array → SKIP the entire DoD block. ONE frontmatter read; no AskUserQuestion calls; proceed directly to ship
2. If verdict has jira_tickets: non-empty AND verdict status is PASS/WARN — three opt-in actions surface (each cancel-safe, each Jira-offline-safe):
   1. Verdict→Jira comment. "Post the Gate 2 verdict to PROJ-123 as a comment? [Y/n/edit]" → mk:jira-collaborate add comment with verdict's Summary + Risks. Sets posted_to_jira: true|deferred
   2. Status transition. "Transition PROJ-123 to Done? [Y/n/skip]" → mk:jira-lifecycle transition. Sets transitioned_to_done: true|deferred
   3. Business AC checkbox. Source priority: (a) Jira AC field; (b) fallback to plan.md ## Acceptance Criteria if Jira read fails or AC field empty. Y/n per item before proceeding
3. Honor each user answer; update verdict frontmatter accordingly
4. Proceed with the rest of the ship pipeline (or abort if user explicitly cancels)

Cost analysis: for non-Agile sessions, the only added cost is reading the verdict frontmatter (which mk:ship already does to read PASS/WARN/FAIL). The jira_tickets: field check is a single grep on already-loaded data. Effectively zero added cost.

Coverage: this single insertion covers BOTH direct mk:ship invocation AND the mk:cook → mk:ship chain. No separate insertion in mk:cook needed.