playbooks

home / skills / tkersey / dotfiles / ship

ship skill

/codex/skills/ship

This skill finalizes validated work by confirming signals, summarizing proof, optionally commenting beads, and opening a PR without merging.

npx playbooks add skill tkersey/dotfiles --skill ship

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1016 B
---
name: ship
description: "Finalize work after validation: confirm a signal, capture proof in the PR description, and open a PR (no merge). Use when asked to run `$ship`, ship/finalize a branch, prepare or open a PR without merging, or publish validation proof before handoff."
---

# Ship

## Overview
Finalize deliverables after validation and produce a concise proof trail.

## Workflow
1. Confirm a recent validation signal exists for the current change set; if not, run `validate`.
2. Summarize proof: commands/signals and outcomes.
3. Capture the proof directly in the PR description (or update the PR body if it already exists).
4. Open a PR (do not merge), using `gh` where applicable.
5. Report PR status and any remaining follow-ups.

## Guardrails
- Never ship without a signal.
- Keep proof concise and scoped to this change.
- If PR creation is blocked (auth/remote), state the exact blocker and next command.

## Output
- Proof summary (signals + results).
- PR creation status.
- Next steps if any.

Overview

This skill finalizes a change after validation by confirming a signal, capturing concise proof, and opening a pull request without merging. It creates a clear handoff artifact so reviewers and maintainers can see the validation trail and next steps. Use it to prepare branches for review or to publish validation evidence before handing off work.

How this skill works

The skill first checks for a recent validation signal tied to the current change set; if absent it suggests running validate. It collects the commands, signals, and outcomes that prove the change passed validation, posts that proof to an active bead comment when a .beads directory is present, and opens a PR using the GitHub CLI if possible. Finally, it reports the PR status and any blockers or follow-ups needed.

When to use it

  • You want to finalize a feature branch after tests/validation complete.
  • You need to publish validation proof before handing the change to reviewers.
  • You must open a PR for review but should not merge it yet.
  • You use bead-based proof comments and want to attach validation evidence.
  • You ran validations manually and need a concise record for audit or handoff.

Best practices

  • Require a clear validation signal before shipping; do not proceed without it.
  • Keep the proof summary minimal: commands run, key outputs, and pass/fail status.
  • Scope proof to the current change set; avoid unrelated logs or noise.
  • Only comment on an active bead if a .beads directory exists in the repo.
  • If PR creation fails, record the exact blocker and the next git/gh command to run.

Example use cases

  • Finalize a dotfiles tweak after running the validation suite and open a PR for review.
  • Attach CI/local test output to an active bead comment so maintainers can verify proof.
  • Prepare a branch for handoff by summarizing validation steps and opening a PR without merging.
  • When auth or remote config blocks PR creation, surface the specific error and suggested fix.

FAQ

What counts as a valid signal?

A valid signal is a recent passing validation run tied to the current change set: test suite success, linters clean, or an explicit validate command output. If none exists, run validate before shipping.

When should I comment on a bead?

Comment on a bead only if the repository contains a .beads directory and an active bead exists for this change. Include only the concise proof summary and any short commands used.