← All craftbooks

Ship

Ship and releaseevalv1.1.2released 2026-09-04workflow: release

Steps

Entry step: preflight. Each step names the specialist role it wants; the full working prompt is expandable.

1. Preflightdeveloperentry

   Confirm the working tree is shippable: the checked-out branch matches the requested branch, has an upstream, is clean, and contains the intended commits.

   Show working prompt

   Before creating a pull request, verify the exact state with read-only repository tools:
   
   1. Call `run_git({ subcommand: "status", args: ["--short", "--branch"] })` and confirm the checked-out branch is exactly `{{branch}}`, is not `main`/`master`, and has no uncommitted changes.
   2. Call `run_git({ subcommand: "rev-parse", args: ["--abbrev-ref", "--symbolic-full-name", "@{upstream}"] })` to prove the branch is already published. This craftbook creates a PR but does not push.
   3. Call `run_git({ subcommand: "log", args: ["-n", "10", "--oneline", "--decorate"] })` and confirm the recent commits match the intended scope.
   
   If the branch is wrong, dirty, on trunk, missing an upstream, or contains unexpected commits, write the exact blocker to task notes and report DONE_WITH_CONCERNS without advancing. Otherwise write the verified branch, upstream, clean status, ahead/behind state, and commit scope to task notes, then advance.

2. Run testsdeveloper

   Run the project's test command. Branches on failure to a triage step; on success advances to the review pass.

   Show working prompt

   Advance this step to execute its `run-tests` on-exit script exactly once. The script picks the project's primary test command and returns `{ passed: boolean, summary: string }`; the task routes automatically to self-review on success or to the halt step on failure. Do not call the script manually. If the task routes to halt, report DONE_WITH_CONCERNS with the recorded test failure and let the user fix it before re-running the craftbook.

3. Self-review passreviewer

   Walk your own diff before opening the PR. Last chance to catch obvious mistakes.

   Show working prompt

   Call `run_git({ subcommand: "diff", args: ["@{upstream}..."] })` and review the exact change set that will enter the pull request. Look for:
   
   - Debug prints or console logging left in
   - Commented-out code
   - Filenames that do not match the intended rename
   - Tests or migrations missing from the published branch
   - Changes outside the stated scope
   
   If anything is wrong, write the concrete findings to task notes and report DONE_WITH_CONCERNS without advancing; the user must correct, commit, and publish the branch before rerunning. If the diff is clean, record that verdict in task notes and advance.

4. Open PRdeveloper

   Open a pull request for the already-published branch.

   Show working prompt

   Advance this step to execute its `open-pr` on-exit script exactly once for the verified `{{branch}}` branch. The script calls `github_pr_create`; it does not push. The task advances only when the script returns a PR URL and otherwise routes to the halt step. Do not call the script manually or retry a failed creation blindly.

5. Wait for CIdeveloper

   Poll workflow runs / check status until the gate is green or fails.

   Show working prompt

   Advance this step to execute its `wait-checks` on-exit script exactly once for `{{branch}}` with the default ten-minute timeout. It polls `github_check_status` until the state settles. Do not call the script manually. The task routes automatically to summary on success and to halt on failure, timeout, or a missing result.

6. Summarydeveloper

   Stamp a final summary. PR opened, CI green, ready to merge.

   Show working prompt

   Write a one-paragraph DONE summary: PR number, URL, scope (one line), test result, CI verdict. Save to task notes. Report DONE.

7. Halteddeveloper

   Something blocked the ship — tests, CI, or push. Report DONE_WITH_CONCERNS.

   Show working prompt

   Report DONE_WITH_CONCERNS with the specific failure surfaced upstream. Do not retry, do not push past — the user needs to see this and decide.

Triggers

Phrases that suggest this craftbook to a crew.

• ship this
• ship it
• open a pr
• open the pr
• release this

Source

View this craftbook on GitHub · MIT license