workflow-ship

Files (1)

• SKILL.md

SKILL.md (first lines)

# Workflow Ship

Ship the current feature branch by pushing, opening a PR, merging it to `main`, and cleaning up safely.

## Trigger Phrases

- `workflow:ship`
- `ship workflow`
- `ship this branch`
- `publish this branch`
- `open and merge a PR`
- `push, PR, merge, and clean up`

## Process

1. Verify branch state:
   - Run `git branch --show-current`.
   - Stop if the branch is `main` or `master`.
   - Run `git status --short --branch`.
   - Stop if there are uncommitted changes and suggest `workflow:commit`.
   - Resolve the base ref: use local `main` when present, otherwise use `origin/main`.
   - Run `git log <base-ref>..HEAD --oneline` and stop if there are no commits ahead of the base ref.

2. Run Codex review as final gate:
   - Check for docs-only diff first:
     - Run `git diff --name-only <base-ref>...HEAD`.
     - If every changed path matches the regex `(^|.*/)(README|LICENSE)[^/]*$|\.md$|^docs/`, the diff is docs-only.
     - Print one line to the user: "Docs-only diff detected — skipping review."
     - Skip the rest of step 2 and continue to step 3.
   - Verify `codex` is on PATH (`command -v codex`). If missing, stop with a clear error — do not silently skip.
   - Run `codex review --base main` in the foreground. Stream the output to the user.
   - If `codex` exits non-zero, stop and report — do not push.
   - Parse the reviewer stdout for the regex `Review comment:|\[P[0-3]\]`.
   - If there is no match, the review is clean. Continue to step 3 without prompting.
   - If there is a match, halt. Before presenting the options, write a short plain-language summary **in Dutch** using this exact format:
     ```
     Severity: laag / midden / hoog
     Wat er speelt: <1-2 zinnen, plain language>
     Advies: ship / fix eerst / jouw call
     ```
     Map codex priority to severity as a soft guideline:
     - `P0` present → **hoog** / fix eerst
     - `P1` present (no `P0`) → **midden** / jouw call
     - only `P2` / `P3` / nits → **laag** / ship
     Deviating from the mapping is allowed when context warrants it (e.g. P1 in a comment, P2 touching auth) — add one short sentence explaining why.
     After the summary, present two options to the user (use `AskUserQuestion` in Claude Code; in Codex or other hosts, prompt the user explicitly and wait for an answer):
     - `Abort ship` (Recommended) — stop the workflow. The user fixes the findings outside ship (e.g. via `workflow:commit`) and re-runs `workflow:ship`. Do not attempt fixes inside this workflow.
     - `Ignore findings and ship anyway` — continue to step 3.

3. Push the branch:
   - Detect whether an upstream exists with `git rev-parse --abbrev-ref --symbolic-full-name @{u}`.
   - If no upstream exists, run `git push -u origin <branch>`.
   - If upstream exists, run `git push`.

4. Summarize the shipment:
   - Run `git log <base-ref>..HEAD --oneline`.
   - Run `git diff --stat <base-ref>...HEAD`.
   - Show the commits and a compact summary before creating the PR.

5. Create the PR:
   - Use `gh pr create`.
   - Derive the title from the branch name and commits using conventional-commit style.
   - Include a body with `## Summary` and `## Test plan`.
   - Show the PR URL.

6. Merge safely:
   - Run `gh pr merge <number> --merge --delete-branch`.
   - If the merge fails because checks are failing, conflicts exist, or review is required, stop and report the blocker.
   - Never force-merge.

7. Update local main:
   - Switch to `main`.
   - Pull the latest `main`.

8. Delete the local branch:
   - Run `git branch -d <branch>`.
   - If safe deletion fails, do not use `-D`; report the reason and let the user decide.

9. Confirm final state:
   - Run `git status --short --branch`.
   - Run `git branch --list`.
   - Confirm the worktree is clean and on `main`.

## Error Handling

- If the branch has no commits ahead of `main`, stop and say there is nothing to ship.
- If `codex` is not on PATH, stop with a clear error — do not silently skip the review gate.
- If `codex review` exits non-zero, stop and report the failure — do not push.
- If `gh` is not authenticated or available, stop and report the exact blocker.
- If the remote branch was already deleted by the merge step, skip remote deletion silently.

## Command Notes

- Follow the active agent and project shell rules.
- Use non-interactive git commands whenever possible.
- Do not run destructive commands unless the user explicitly asks for them.

From fimoklei/pm-ai-playbook, MIT.

More from fimoklei/pm-ai-playbook