@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/skills/git/file-ticket/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "file-ticket",
+	"version": "0.3.0",
+	"description": "Turns something noticed mid-session into a tracker issue: captures evidence, dedups against existing issues, composes a labeled issue with acceptance criteria, confirms, and creates it via gh. Not for batch ticket creation from a PRD; use backlog. Not for diagnosing an existing issue; use fix-issue.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "file-ticket",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/git/fix-issue/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: fix-issue
+description: "Resolves a tracker issue end to end: fetches it, diagnoses only when the issue does not name the code, fixes test-first, and self-reviews against the acceptance criteria, leaving a verified uncommitted change. Not for filing; use file-ticket. Not for committing or PRs; use ship."
+triggers:
+  - fix issue 123
+  - take this ticket
+  - resolve the bug in issue
+  - implement this tracker issue
+  - fix a GitHub issue end to end
+version: 0.3.0
+license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (authenticated for issue viewing), POSIX-compatible shell
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - bash
+  - context
+  - code_nav
+  - dispatch
+  - tasks
+  - write
+  - edit
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/git/fix-issue
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+---
+
+# Fix Issue
+
+Resolve one tracker issue: diagnose only as much as the issue leaves unknown, fix test-first, verify against the issue's own acceptance criteria. The skill ends with an uncommitted working tree and a completion report; committing, pushing, and PRs belong to `ship`.
+
+See [diagnosis and RCA](references/diagnosis-and-rca.md) for why-chain construction, root-cause documentation, and handling maintainer constraints.
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:fix-issue [--repo owner/repo] <issue-number|issue-url>
+```
+
+### Examples
+- `/skill:fix-issue 42`
+- `/skill:fix-issue #105`
+- `/skill:fix-issue https://github.com/iowarp/clio-coder/issues/271`
+- `/skill:fix-issue --repo acme/widgets 88`
+
+### Positional Arguments
+- `<issue-number|issue-url>`: The GitHub issue identifier to fix.
+  - Allowed forms:
+    - Pure integer: `42`
+    - Hash-prefixed integer: `#42`
+    - Full GitHub issue URL: `https://github.com/<owner>/<repo>/issues/<number>`
+  - Required. If omitted, prompt the user for the issue number or URL.
+
+### Options
+- `--repo <owner/repo>`: Target GitHub repository.
+  - If a full issue URL is provided, the repository is extracted directly from the URL and takes precedence.
+  - If only an issue number is provided, `--repo` overrides the default.
+  - Default: detected canonical repository (`gh repo view --json nameWithOwner -q .nameWithOwner` or Git remote tracking).
+  - Validation: Must match `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
+
+### Unknown Arguments and Validation
+- Unknown flags must be rejected with an error; do not pass unknown options to `gh`.
+- Issue numbers must be validated as digits; URLs must match GitHub issue URL format. Never interpolate raw user input into shell commands without safe quoting.
+
+## Step 1 — Fetch and Gate
+
+1. Deterministically resolve repository and issue ID.
+2. Fetch the issue content:
+   ```bash
+   gh issue view <id> --repo <owner/repo>
+   ```
+   If that fails (older `gh`, network, GraphQL quirks), fall back to:
+   ```bash
+   gh api repos/<owner>/<repo>/issues/<id>
+   gh api repos/<owner>/<repo>/issues/<id>/comments
+   ```
+   Never invent issue content: if both paths fail and the user did not paste the issue body, report the failure and stop.
+3. Gates before touching any code:
+   - **Issue closed**: report it; continue only on explicit user confirmation.
+   - **Linked PR exists**: report it and confirm before duplicating effort.
+   - **Maintainer comments**: authoritative guidance on constraints, architecture, or budgets must be respected per [diagnosis reference](references/diagnosis-and-rca.md).
+
+## Step 2 — Diagnose Only the Unknown
+
+Read the issue's evidence first:
+- If the issue already cites the failing code (`file:line`, an exact stack trace, or commit SHA), verify the code directly by reading it and skip broad exploration.
+- If the cause is unknown, build a structured why-chain with observed citations:
+  ```text
+  WHY <symptom>? -> because <cause> (evidence: file.ts:123)
+  ROOT CAUSE: <exact code to change> (evidence: file.ts:789)
+  ```
+- Routine fixes keep their why-chain in the completion report. For complex bugs, format a standalone RCA. Note: `ship` does not automatically post comments or modify labels on issues. If the repository workflow requires posting the RCA as an issue comment, prompt the user and use `gh issue comment` with explicit confirmation.
+
+## Step 3 — Fix Test-First
+
+1. Write a focused reproducing test before editing implementation code.
+2. Run the test and observe it fail for the stated defect reason.
+3. Make the smallest necessary change to resolve the root cause.
+4. Stay strictly within the issue scope. Any adjacent defects observed are documented in the report or filed via `file-ticket`, never bundled silently into this fix.
+
+## Step 4 — Verify
+
+1. Run the reproducing test to verify it now passes.
+2. Run the project's detected check suite (tests, typecheck, lint) and any validation commands mentioned in the issue.
+3. Self-review the diff (`git diff`) against the issue's acceptance criteria, validating each criterion with real evidence.
+
+## Step 5 — Report and Stop
+
+Leave the working tree uncommitted. Deliver a structured report:
+- Root cause (why-chain or verified issue evidence)
+- Files modified with net line diffs
+- Acceptance criteria checklist with verification evidence
+- Validation commands executed and their actual outputs
+- Out-of-scope observations or follow-ups
+
+Handoff: Inform the user that the change is verified and uncommitted, ready for `ship`.
+
+## Red Flags
+
+- Re-deriving a root cause the issue already accurately documents.
+- Changing implementation code before a reproducing test fails.
+- Bundling out-of-scope refactoring or fixes into the change.
+- Stating "all checks pass" without listing the actual commands and outputs.
+- Committing, pushing, or creating pull requests from this skill.

package/library/skills/git/fix-issue/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "fix-issue",
+	"version": "0.3.0",
+	"description": "Resolves a tracker issue end to end: fetches it, diagnoses only when the issue does not name the code, fixes test-first, and self-reviews against the acceptance criteria, leaving a verified uncommitted change. Not for filing; use file-ticket. Not for committing or PRs; use ship.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "fix-issue",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/git/resolve-merge-conflicts/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: resolve-merge-conflicts
+description: Resolves a merge, rebase, or cherry-pick stopped on conflicts by reconstructing both sides' intent, validating with the project's own checks, and completing the operation. Not for integrating many branches; use worktree-merge.
+triggers:
+  - merge conflict
+  - fix these conflicts
+  - finish the merge
+  - finish the rebase
+  - resolve conflict markers
+version: 0.4.0
+license: Apache-2.0
+compatibility: git >=2.30.0, POSIX-compatible shell
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - edit
+  - write
+  - verify
+  - tasks
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/git/resolve-merge-conflicts
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/resolve-merge-conflicts
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+    - git-master
+---
+
+# Resolve Merge Conflicts
+
+Resolve conflicts stopped during a merge, rebase, or cherry-pick from intent, not from picking whichever side makes markers disappear. The job ends with the operation completed and the project's validation checks green.
+
+See [conflict matrix](references/conflict-matrix.md) for operation detection, the rebase ours/theirs reversal, and resolution patterns across conflict types (content, modify/delete, rename, binary, submodule, and lockfiles).
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:resolve-merge-conflicts [--checks auto|command] [--continue|--no-continue]
+```
+
+### Examples
+- `/skill:resolve-merge-conflicts`
+- `/skill:resolve-merge-conflicts --checks "npm test"`
+- `/skill:resolve-merge-conflicts --no-continue`
+
+### Options
+- `--checks <auto|command>`: Validation checks execution mode.
+  - `auto` (default): Detects and runs test, typecheck, and lint commands from the repository (CI workflows, Makefile, package manifests).
+  - `<command>`: Custom shell command to run for verification (e.g. `npm test`, `cargo check`).
+- `--continue|--no-continue`: Whether to complete the in-flight operation after resolution and validation.
+  - `--continue` (default): Runs the operation's continue command (`git merge --continue`, `git rebase --continue`, or `git cherry-pick --continue`).
+  - `--no-continue`: Leaves resolved files staged in the index and stops without executing the continue command.
+
+### Unknown Arguments and Safe Execution
+- Unknown flags must be rejected with an error. Never interpolate untrusted user text into shell execution without proper quoting.
+
+## Step 1 — Map the State and Operation
+
+> [!IMPORTANT]
+> Execute steps directly; do not declare task boards or write artifact files. Run discrete git commands sequentially; never nest commands inside `$(...)` command substitutions or subshells.
+
+Identify the in-flight operation per [conflict matrix](references/conflict-matrix.md):
+- **Merge**: `.git/MERGE_HEAD` exists. `HEAD` is ours (target branch), `MERGE_HEAD` is theirs (incoming branch).
+- **Rebase**: `.git/rebase-merge` or `.git/rebase-apply` exists.
+  > [!WARNING]
+  > In `git rebase`, `--ours` and `--theirs` are **reversed**!
+  > - `HEAD` ("ours") is the upstream branch being rebased onto.
+  > - `REBASE_HEAD` ("theirs") is your branch commit being replayed.
+- **Cherry-pick**: `.git/CHERRY_PICK_HEAD` exists. `HEAD` is target branch, `CHERRY_PICK_HEAD` is commit being cherry-picked.
+
+Query all unmerged paths:
+```bash
+git diff --name-only --diff-filter=U
+```
+
+## Step 2 — Reconstruct Both Intents
+
+For each conflicting file, determine why each side modified the code:
+- Check commit logs:
+  ```bash
+  # In merge:
+  git log --oneline HEAD..MERGE_HEAD -- <file>
+  git log --oneline MERGE_HEAD..HEAD -- <file>
+  # In rebase:
+  git log -1 REBASE_HEAD -- <file>
+  ```
+- Read commit messages and linked issue references. A resolution without understanding both intents is an ungrounded guess.
+
+## Step 3 — Resolve Each Conflict by Type
+
+Handle each file according to its conflict class:
+- **Content conflict markers**: Preserve both changes if compatible (e.g. non-overlapping functions or independent parameters). If incompatible, select the change aligned with the operation goal, or prompt the user via `ask_user`. Verify no markers remain:
+  ```bash
+  grep -rn "<<<<<<<\|>>>>>>>" <files>
+  ```
+- **Add / Add**: Merge file contents if same concept, or rename if distinct concepts.
+- **Modify / Delete**: Trace whether deletion was deliberate refactoring or accidental; preserve or remove accordingly.
+- **Rename**: Follow renamed files and integrate changes into the canonical filename.
+- **Binary files**: Check out appropriate version (`git checkout --ours` / `--theirs`) or rebuild asset from source.
+- **Submodules**: Resolve submodule commit pointer via `git diff --submodule` and submodule history.
+- **Lockfiles**: Do not manually resolve JSON/YAML markers in package lockfiles. Re-derive them via the package manager (`npm install --package-lock-only`, `pnpm install --lockfile-only`, `cargo check`, `uv lock`).
+
+Stage resolved files: `git add <files>`.
+
+## Step 4 — Validate
+
+Run the validation suite determined by `--checks`:
+- If `auto`: execute detected typecheck, tests, and linter.
+- If `<command>`: execute the specified validation command.
+- If any check fails, fix regressions caused by the resolution before proceeding.
+
+## Step 5 — Complete Operation or Multi-Stop Loop
+
+If `--no-continue` was specified:
+- Report that all conflicts are resolved and files are staged; stop here.
+
+If `--continue` is active (default):
+- Execute the operation-specific continue command:
+  - **Merge**: `git merge --continue` (or `git commit`)
+  - **Rebase**: `git rebase --continue`
+  - **Cherry-pick**: `git cherry-pick --continue`
+- **Multi-stop rebases**: If git stops on a subsequent commit conflict, loop back to Step 1 and repeat until the rebase completes.
+- **Operation Abort**: If the user decides the operation is invalid or if unresolvable contradictions occur, run the operation-specific abort command (`git merge --abort`, `git rebase --abort`, or `git cherry-pick --abort`) and verify the tree returns to clean pre-operation state.
+
+## Step 6 — Report
+
+Summarize:
+- Completed operation type (merge, rebase, cherry-pick)
+- Each conflicting file, conflict type, and how intent was resolved
+- Validation checks run and real outputs
+- Current branch status and clean working tree verification
+
+## Red Flags
+
+- Taking `--ours` or `--theirs` wholesale without reading both sides.
+- Inverting intent during a rebase by misunderstanding reversed ours/theirs semantics.
+- Hand-editing conflict markers in binary files or complex lockfiles.
+- Leaving `<<<<<<<` or `>>>>>>>` markers in any committed file.
+- Declaring done without running validation checks.
+- Executing an abort without user instruction.

package/library/skills/git/resolve-merge-conflicts/evals.md

@@ -0,0 +1,85 @@
+# Evals — resolve-merge-conflicts
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
+
+## S1 — Compatible two-sided conflict
+Setup: the merge of feat-rename stopped on a conflict in util.js. Resolve it and finish the merge.
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
+git config commit.gpgsign false
+printf 'function getUser(id) {\n  return db.find(id);\n}\n\nmodule.exports = { getUser };\n' > util.js
+git add util.js
+git commit -qm "chore: seed util"
+git checkout -qb feat-rename
+printf 'function findUser(id) {\n  return db.find(id);\n}\n\nmodule.exports = { findUser };\n' > util.js
+git commit -qam "refactor: rename getUser to findUser"
+git checkout -q main
+printf 'function getUser(id) {\n  return db.find(id);\n}\n\nfunction getUserName(id) {\n  return getUser(id).name;\n}\n\nmodule.exports = { getUser, getUserName };\n' > util.js
+git commit -qam "feat: add getUserName call site"
+git merge feat-rename > merge-output.txt 2>&1 || true
+```
+
+Expected:
+- Reads both sides' history (log/show on main and feat-rename) before editing.
+- Resolution preserves both intents: the function is named `findUser` and `getUserName` calls `findUser`.
+- The merge is committed and no conflict markers remain in `util.js`.
+
+## S2 — Incompatible conflict
+Setup: both sides changed the same default to different values.
+
+Expected:
+- Identifies the incompatibility. Picks per the merge's stated goal or prompts the user; trade-off recorded in the report.
+
+## S3 — Mid-rebase, multiple stops
+Setup: a rebase is stopped on its first conflict with more commits still to replay; resolve and finish the whole rebase.
+
+Expected:
+- Correctly treats `HEAD` as upstream target and `REBASE_HEAD` as incoming replayed commit (recognizes reversed ours/theirs).
+- Continues the rebase with `git rebase --continue` across multiple stops until complete.
+- Runs validation checks at completion.
+
+## S4 — Binary file conflict
+Setup: merge conflict on a binary asset (e.g. `logo.png`).
+
+Expected:
+- Detects binary conflict (no text conflict markers present).
+- Determines intended version and resolves using `git checkout --ours` or `git checkout --theirs`.
+- Stages binary asset with `git add logo.png`.
+
+## S5 — Modify/delete conflict
+Setup: one branch modified `helper.js`, the other deleted it.
+
+Expected:
+- Checks git status for `CONFLICT (modify/delete)`.
+- Inspects the commit that deleted the file to determine if deletion was intentional.
+- Resolves by either staging the file (`git add helper.js`) or completing the deletion (`git rm helper.js`).
+
+## S6 — Operation-specific abort behavior
+Setup: user requests aborting an in-flight rebase or merge.
+
+Expected:
+- For merge: invokes `git merge --abort`.
+- For rebase: invokes `git rebase --abort`.
+- Verifies working tree returns to clean pre-operation state.
+
+## S7 — No-continue flag
+Setup: user runs `/skill:resolve-merge-conflicts --no-continue`.
+
+Expected:
+- Resolves all conflict markers and stages resolved files with `git add`.
+- Does not run `git merge --continue` or `git rebase --continue`.
+- Reports files staged and ready for user inspection.
+
+## Baseline failure modes to watch for (RED)
+- Running `git checkout --theirs` on everything to make markers go away.
+- Inverting intent during a rebase due to ours/theirs reversal.
+- Leaving conflict markers in files.
+- Running generic abort when resolution is achievable.
+
+## Smoke record (2026-08-13)
+One representative scenario via `clio-coder eval skill` against Nemo-3.5-Lightning (30B local, llamacpp on mini), full-auto sandbox. PASS. Both sides' history read; both intents preserved; merge committed, no markers.

package/library/skills/git/resolve-merge-conflicts/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "resolve-merge-conflicts",
+	"version": "0.4.0",
+	"description": "Resolves a merge, rebase, or cherry-pick stopped on conflicts by reconstructing both sides' intent, validating with the project's own checks, and completing the operation. Not for integrating many branches; use worktree-merge.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "resolve-merge-conflicts",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/git/ship/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ship
+description: "Ships finished work: writes one reviewed atomic commit, keeps maintainer branches local, or pushes a contributor branch to their fork and opens a PR only on explicit intent. Not for producing the change; use fix-issue."
+triggers:
+  - ship this
+  - commit this
+  - commit and open the PR
+  - push and open a pull request
+  - get this up for review
+version: 0.5.0
+license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (required for pr mode), POSIX-compatible shell
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - tasks
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/skills/git/ship
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+    - git-master
+---
+
+# Ship
+
+Move finished, verified work out safely. This skill enforces strict mode separation: local commits, contributor fork PRs, maintainer-local integration handoffs, and post-merge closeouts.
+
+See [remote and branch policy](references/remote-and-branch-policy.md) for remote detection and publication rules, and [PR template](assets/pr-template.md) for standard pull request layout.
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:ship commit|pr|closeout [--base branch] [--fork remote] [--issue number] [paths...]
+```
+
+### Examples
+- `/skill:ship commit src/cli/run.ts tests/run.test.ts`
+- `/skill:ship pr --base main --fork fork --issue 105`
+- `/skill:ship commit --issue 42`
+- `/skill:ship closeout --base main`
+
+### Positional Arguments
+- `mode`: The operational mode. Must be one of:
+  - `commit`: Review and stage changes, then create one atomic conventional commit. Never pushes; never opens a PR.
+  - `pr`: Validate clean tree, push topic branch to contributor fork remote, and open a pull request against canonical base.
+  - `closeout`: Clean up local worktrees and branches after a PR is verified merged; delegates to `branch-closeout`.
+- `paths...`: Optional explicit file paths to stage for `commit`. If omitted, inspects working tree status and prompts user before staging.
+
+### Options
+- `--base <branch>`: Target base branch on the canonical remote (e.g. `main`, `master`).
+  - Default: detected default branch from `gh repo view` or remote tracking.
+  - Validation: Must be a valid git ref name (`git check-ref-format --branch <branch>`).
+- `--fork <remote>`: Remote name pointing to the contributor's personal fork.
+  - Default: detected fork remote from Git URLs.
+  - Refusal Guard: Never assumed to be `origin`. If the chosen fork remote points to the canonical repository in a canonical-main-only project, topic pushes are strictly refused.
+- `--issue <number>`: Issue number or identifier to reference in commit footer (`fixes #N`) and PR description.
+
+### Unknown Arguments and Validation
+- Reject unknown options with an error. Validate ref names and file paths before executing git commands. Never interpolate unvalidated user strings into raw shell commands.
+
+## Step 1 — Project Conventions Win
+
+Inspect project instructions (`CLIO-CODER.md`, `AGENTS.md`, `CONTRIBUTING.md`, `CLAUDE.md`) for commit formats, PR templates, and branching policy. Detected repository policy overrides default assumptions.
+
+## Step 2 — Commit Mode (`commit`)
+
+Review the entire working tree before staging:
+1. Run `git status --porcelain` and `git diff HEAD`.
+2. Exclude secret-shaped files (`.env*`, credentials, keys), generated build outputs, and unrelated files.
+3. Stage explicit paths only (using `paths...` or prompted list). Never run `git add -A` blindly.
+4. Compose one atomic conventional commit:
+   `<type>(<scope>): <imperative summary>`
+   Include `fixes #N` or `refs #N` footer when `--issue <number>` is provided.
+5. If hooks or commit signing fail, report the exact error and halt. Use `--no-verify` only upon explicit user instruction.
+6. If the selected mode is `commit`, report `git log -1 --stat` and finish here.
+
+## Step 3 — Classify Remotes and Gate Publication
+
+For `pr` mode, classify remotes per [remote and branch policy](references/remote-and-branch-policy.md):
+1. Resolve canonical repository via `gh repo view` and match against `git remote -v`.
+2. Resolve `--fork <remote>`.
+3. Evaluate publication gates:
+   - **On base branch directly**: STOP. Work must be on a topic branch.
+   - **Uncommitted changes remain**: STOP. Stash or commit before pushing.
+   - **Canonical remote is main-only**:
+     - Maintainer clones keeping branches local: Report commit complete and ready for local integration (e.g. fast-forward or `worktree-merge`). Refuse to push topic branch to canonical remote.
+     - Contributor clones: Require push to fork remote `<fork>`, never canonical.
+   - **Open PR exists**: STOP and print the existing PR URL.
+   - **Merged PR exists**: Report merged status; suggest `closeout` mode.
+
+## Step 4 — Contributor Fork Push and PR (`pr`)
+
+1. Push topic branch to the verified fork remote using an explicit refspec:
+   ```bash
+   git push -u <fork> refs/heads/<topic>:refs/heads/<topic>
+   ```
+2. Open the pull request against the canonical repository:
+   ```bash
+   gh pr create --repo <canonical-owner/repo> --base <base> --head <fork-owner>:<topic> --title "..." --body-file "$pr_body_file"
+   ```
+3. Use repository `.github/PULL_REQUEST_TEMPLATE.md` or [standard PR template](assets/pr-template.md). Detail Summary, Changes, Validation commands actually run, and Linked Issues.
+4. Report PR URL, number, and review instructions.
+
+## Step 5 — Closeout Mode (`closeout`)
+
+When invoked as `ship closeout` (or when user requests cleanup of merged work):
+1. Ensure the user explicitly requested closeout.
+2. Delegate to `/skill:branch-closeout` or execute the closeout protocol:
+   - Verify merge/squash landing evidence on canonical base branch.
+   - Inspect worktree for uncommitted or untracked changes.
+   - Remove worktree with `git worktree remove` (never `rm -rf`).
+   - Safely delete local branch (`git branch -d`).
+   - Audit remaining worktrees, local branches, stashes, and remote heads.
+
+## Red Flags
+
+- Blurring commit and PR phases: running `git push` or `gh pr create` when user only asked to commit.
+- Assuming a remote named `origin` is a fork or canonical without checking its URL.
+- Pushing a topic branch to a canonical-main-only repository.
+- Staging files with `git add -A` without inspecting untracked files.
+- Claiming validation checks passed when they were never run.
+- Automatically deleting branches or worktrees without verifying merge evidence.

package/library/skills/git/ship/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "ship",
+	"version": "0.5.0",
+	"description": "Ships finished work: writes one reviewed atomic commit, keeps maintainer branches local, or pushes a contributor branch to their fork and opens a PR only on explicit intent. Not for producing the change; use fix-issue.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "ship",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}