/coco-ship

name: coco-ship
description: Use when finished work needs to reach a coco-managed repository (coco-research/coco or similar) — verifies branch state, commits, pushes through the corporate DLP guard only when actually needed, opens a PR against main, waits for CI, and reports the result. Never merges, never pushes to main directly.
domain: engineering
user-invocable: true

Shipping to a CoCo-managed Repo

Overview

Formalizes the branch → commit → guard-aware push → PR → CI-wait → report flow used for shipping work to `coco-research/coco` (or any repo carrying the same corporate git-guard pre-push hook), so it doesn't have to be re-derived by hand each time.

**Core principle:** Verify state → commit → detect whether the guard actually applies → confirm → push → open PR → wait for real CI → report. Never merge. Never push to `main` directly, regardless of how it's asked.

**Announce at start:** "I'm using the coco-ship skill to ship this branch."

This is the direct formalization of Option 2 ("Push and Create PR") in `finishing-a-development-branch`, specialized for repos that carry the corporate git-guard. It assumes implementation is already done and reviewed — it doesn't replace planning skills like `brainstorming`, `writing-plans`, or GSD's phase workflow, and it doesn't run tests itself (that's `finishing-a-development-branch`'s Step 1, or the project's own CI).

The Process

Step 1: Preflight

git status -sb
git branch --show-current

**If the current branch is `main` or `master`:** stop. Do not commit or push here. Offer to create a feature branch first:

git checkout -b <feature-branch-name>

**If there's nothing to commit and the branch isn't already ahead of its upstream:** stop and say so — there's nothing to ship.

Step 2: Commit

Use the standard git-commit protocol already in effect for this harness — this isn't a new invention, just invoked from inside the skill:

1. In parallel: `git status`, `git diff` (staged + unstaged), `git log` (recent messages, for style). 2. Draft a commit message from the actual diff — why, not just what — matching the repo's existing style. 3. Stage named files explicitly. Never `git add -A` or `git add .`. 4. Commit with a `Co-Authored-By` trailer, via a heredoc so formatting survives. 5. `git status` again to confirm a clean tree.

If a pre-commit hook fails, fix the issue, re-stage, and create a **new** commit — never `--amend` a commit that a failed hook means never actually landed.

Step 3: Detect whether the guard bypass is actually needed

Don't assume — check:

git remote -v
gh repo view <owner>/<repo> --json visibility,owner -q '"\(.visibility) \(.owner.login)"'
git config --show-origin --get core.hooksPath

A `GIT_GUARD_REASON` bypass is only needed when the repo is `PUBLIC` **and** the owner isn't on the guard's allowlist — check the actual guard config or ask the user which org(s) it allows, rather than assuming. If `core.hooksPath` doesn't point at the guard, don't assume a bypass is relevant on this machine at all — say so.

Step 4: Confirm — every time, no exceptions

This is an outward-facing action (push + open a PR), so it gets the same explicit go-ahead as any other push or PR in this session, regardless of how directly `coco-ship` was invoked. State plainly:

• Target repo and branch
• Whether a guard bypass will be used, and the **exact** reason string (not a placeholder)
• That this opens a PR against `main` — it does not push to `main` directly

Wait for a clear yes before Step 5. Invoking this skill is not itself that approval.

Step 5: Push

git push -u origin <branch>

Only when Step 3 determined a bypass is needed:

GIT_GUARD_REASON="<specific, real reason>" git push -u origin <branch>

**Never** `--no-verify`. **Never** a plain `--force`. A `--force-with-lease` update to an already-open PR's branch is allowed, but still gets its own confirmation, separate from Step 4's.

Step 6: Open the PR

gh pr create --base main --head <branch> --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed and why>

## Test plan
<what was verified, or a checklist of what to verify>
EOF
)"

Keep the title under 70 characters. Put detail in the body, not the title.

Step 7: Wait for CI

gh pr checks <n> --watch

Don't report done while checks are still pending. If a check fails, say so plainly with the failure, don't retry blindly.

Step 8: Report

State the PR URL, the CI result, and the mergeable/review-required status. Say plainly that merging is the user's call — **this skill never merges and never self-approves.** If the PR author can't self-approve (most repos), say that explicitly rather than implying the PR is ready to merge on its own.

Quick Reference

| Step | Action | Confirmation needed? | |------|--------|----------------------| | 1 | Preflight (refuse on main) | — | | 2 | Commit | — | | 3 | Detect guard need | — | | 4 | State plan, ask | **Yes — always** | | 5 | Push | (covered by Step 4) | | 6 | Open PR | (covered by Step 4) | | 7 | Wait for CI | — | | 8 | Report | — |

Common Mistakes

**Assuming the guard bypass is needed without checking**

• **Problem:** Sets `GIT_GUARD_REASON` on every push, even to private or allowlisted repos, or misses

that the guard isn't even installed on this machine.

• **Fix:** Always run Step 3's checks; only set the env var when the repo is genuinely public and

non-allowlisted.

**Treating skill invocation as approval**

• **Problem:** Runs Steps 5–6 immediately because the user said "ship this," without a distinct

confirmation of the actual push/PR plan.

• **Fix:** Step 4 is a separate, explicit ask every time — state the repo, branch, guard reason (if

any), and that a PR (not a direct push to main) will follow.

**Reporting success before CI resolves**

• **Problem:** Says "done" right after `gh pr create`, while checks are s