| name | ship |
| description | Open a PR for the current branch against main. GitHub only — for ADO/Bitbucket projects use /ship from the installed pncli skills instead. Runs the full pre-PR gate (build, lint, typecheck, tests, code review, docs) using parallel subagents before opening the PR. Use whenever the user says "open a PR", "create a PR", "ship this", "pull request", or "/ship". |
| providers | none |
| category | pr-workflow |
| services | git |
Run the full pre-PR gate and open the PR. Parallelize as much as possible.
Make sure there are no outstanding untracked changes before starting.
Phase 0 — GitHub issue check
Check the current branch name for an issue number (e.g., kolatts/75-add-ship-skill → #75).
If no issue number is found in the branch name:
- Always create one. Do not ask — just run
gh issue create --title "<title>" --body "<description>", inferring a reasonable title and body from the branch name and commit list (from Phase 1 Agent A if available, otherwise from the branch name alone).
- Extract the issue number from the created issue URL and use it throughout.
If an issue number is already present, proceed.
Phase 1 — Gather context (parallel)
Launch two subagents simultaneously:
Agent A — Diff + branch info
- Run
git log origin/main..HEAD --oneline to get commits on this branch
- Run
git diff origin/main..HEAD --stat to see which files changed
- Run
git diff origin/main..HEAD --name-only to get the raw file list
- Run
gh pr list --head "$(git branch --show-current)" --state open to check if a PR already exists
- Report: branch name, commit list, changed files (with paths), existing PR URL (if any)
Agent B — Docs audit
- Run
git diff origin/main..HEAD --name-only to get the changed file list
- Read every file in
docs/ and every README.md in the repo (glob **/README.md)
- Read
CLAUDE.md sections relevant to the changed files
- Read the changed source files themselves
- Check
site/src/pages/ and site/src/components/ for any GitHub Pages content that references changed commands, skills, or features — flag anything stale
- Identify any new or modified
pncli commands in the changed files. For each, extract the full command signature: name, subcommands, arguments, and all options/flags with their types and descriptions
- Report:
- Which docs/README sections are stale or inaccurate
- Which GitHub Pages site pages need updating
- A complete list of new/updated pncli commands with their full signatures (to include in the PR body)
Wait for both agents to complete before proceeding.
Phase 2 — Pre-PR gate (parallel)
If a PR already exists (Agent A found one), skip straight to Phase 3.
Launch three subagents simultaneously:
Agent C — Build + lint + typecheck
npm run typecheck — must produce 0 errors. Stop and report if it fails.npm run lint — report any errors or warnings.npm run build — must succeed. Stop and report if it fails.
- Report: typecheck result, lint issues (if any), build result
Agent D — Code review
- Run
git diff origin/main..HEAD to get the full diff
- Read each changed file in full
- Review for correctness, quality, and consistency with CLAUDE.md conventions (Conventional Commits, TypeScript strict, ESM module format)
- Rate each issue: Major (blocks merge), Minor (should fix), Nit (optional)
- Report: overall decision (Approve / Request Changes), all issues with file + line + severity
Agent E — Tests
- Run
npm test and report pass/fail/counts
- If no tests exist, report that and note which changed files could benefit from coverage
- Report: test result summary
Wait for all three agents to complete.
Phase 3 — Fix loop
Collect all issues from Phase 2:
- Typecheck or build errors → fix them
- Lint errors → fix them (warnings are informational; fix if trivial)
- Code review issues rated Major or Minor → fix them; skip Nits unless trivial
- Failing tests → fix them
- Stale docs or README sections (from Agent B) → update them
- Stale GitHub Pages site content (from Agent B) → update the affected files in
site/src/
- Screenshots are only required if
site/src/ files were directly edited. If the only site-related change was adding a skill to an ordering array, no screenshots are needed.
After fixing, re-run Agent C to confirm build + lint + typecheck all pass, and re-run Agent E if any source files changed.
Phase 4 — Commit fixes (if any)
If Phase 3 produced any changes:
git add the changed files- Show the staged diff and confirm with the user before committing
- Commit format:
fix(pre-pr): address review feedback
Phase 5 — PR preview
Construct the PR title and body (do not open the PR yet):
Title: strip the <username>/ prefix and any leading issue number from the branch name, then convert to Conventional Commit format:
type(scope): description- Example: branch
kolatts/issue-42-add-ship-skill → feat(skills): add ship skill
Body:
## Summary
<bullet points from commit list>
## Commands added / updated
<for each new or modified pncli command from Agent B's report:>
- `pncli <command> <subcommand> [args]` — <one-line description>
- `--flag <type>` — description
- `--flag2` — description (flag, no value)
...
(omit this section entirely if no commands were added or changed)
## Pre-PR gate
- ✅ Build: passed
- ✅ Typecheck: 0 errors
- ✅ Lint: <clean / N warnings>
- ✅ Code review: <Approve / issues fixed>
- ✅ Tests: <N passed / no tests>
- ✅ Docs: <updated / no changes needed>
Closes #<issue-number>
Show the formatted title and body to the user, then immediately proceed to open the PR without waiting for confirmation.
Phase 6 — Open PR
gh pr create --title "<title>" --body "<body>"
gh pr merge <PR-URL> --auto --squash
Report the PR URL to the user.
Phase 7 — Post-open watch loop
After opening the PR, immediately invoke /loop 10m with the following recurring task:
Check the PR status: gh pr view <PR-URL> --json state,mergeable,reviewDecision,reviews. Act based on what you find:
If state is MERGED: Report "PR merged ✅" and stop the loop.
If mergeable is CONFLICTING:
Resolve it: git fetch origin main && git merge origin/main, fix merge conflicts, git add and git commit -m "fix(merge): resolve merge conflicts". Push. Report what was resolved.
If reviewDecision is CHANGES_REQUESTED:
Fetch review comments: gh pr view <PR-URL> --json reviews,comments. Read every requested change.
Re-run Phases 2–4 (build + lint + typecheck + tests + code review, fix all issues, commit). Push. Report what was fixed.
If state is OPEN and no issues: Report "PR open, checks running — nothing to do yet."
If state is CLOSED (not merged): Report "PR closed without merging ⚠️" and stop the loop.
