Skip to content

jupes/agent-forge-harness / .agents/skills/forge-ship

forge-ship

Verified

Verify and ship a completed Forge run with a walkthrough, pushed branch, and PR. Use for /forge-ship or the pipeline's shipping phase.

forge-ship

Phase 4 of 4 in the Forge pipeline (research → plan → implement → ship). It closes the loop: a human-readable summary of the entire run plus the actual push/PR. Output is reports/<slug>-ship.md and a pushed branch with a PR.

This phase complements the existing [[ship]] command — it adds the narrative summary and test walkthrough on top of the quality-gate/commit/push mechanics.

Prerequisites

bun run forge:phase-gate ship --slug <slug>     # verifies implement is complete in forge state
cat plans/research/<slug>.md                    # original goal
cat plans/drafts/<slug>.md                      # plan + checkpoints + Beads map

Beads must be reachable. If bd errors, stop and fix it (bd dolt start) before shipping.

--smith <name>: when the run was started with it, add --smith <name> to every forge:phase-gate call in this skill. The phase gate refuses a name that is not configured and records the smith on the run as its executor. It does not change the model of the session doing the work (.claude/workflows/forge.md, --smith).

Process

1. Gather the facts

git log --oneline <base>..HEAD          # commits this run produced
git diff --stat <base>..HEAD            # files + churn
bd list --all --limit 0 --json           # include closed and blocked plan tasks

Cross-reference against the plan's Beads Issue Map so every planned task is accounted for (closed, or explicitly deferred with a reason).

2. Build the before/after

Describe the observable change, not the diff. For each checkpoint: what the user could NOT do before, and what they can do now. Capture commands/URLs and expected output.

3. Write the ship report

Write to reports/<slug>-ship.md (create reports/ if needed):

Read the artifact template at this step and fill each applicable section with verified evidence.

4. Quality gate, push, PR

Gate the run through its correlation before anything is pushed. One command runs typecheck, lint and the tests, checks that the tree is clean and that a test file is among the branch's own commits, and logs the result against this run and the issue it names (reuse [[ship]] for the rest of the mechanics):

git status --porcelain                           # must be empty: commit what belongs to the run
bun run quality-gate --correlation <pointer>     # must exit 0
git pull --rebase origin <base>
git push origin <branch>
  • <pointer> is what every phase-gate write of this run that named a bead printed as data.correlation.pointer. It is one path for the whole run, .tmp/work/run-correlations/<slug>.json, relative to the checkout the run builds in. Run the gate in that checkout.
  • If that file is not there (a run whose writes named no bead, or one started before the phases named theirs), create it with the task the run worked last: bun run forge:correlate --bead <id> --run <slug>.
  • A failing check blocks the push: fix what it names and run the gate again. test-evidence reads every commit of the branch's own, the ones since origin/HEAD, however far back the tests are, and fails when none of them holds a test file. A branch whose commits change documentation only (.md, .mdx, .markdown, .txt, .rst, .adoc), or that has no commits of its own, has nothing to test: the check is skipped and its entry says so. With no origin/HEAD the gate reads the last five commits instead and says so (git remote set-head origin --auto sets it).
  • Strict verdict mode (AGENT_FORGE_EVAL_VERDICT=strict) is opt-in. When it is on, file the run's verdict with this pointer before the gate (.claude/commands/ship.md).

A run whose work is in another repository (repos/<repo>, or a worktree of one recorded with --checkout) is gated the same way, from this checkout, with that repository's own checks. Its correlation is in the run's checkout: join the checkout and the pointer the phase gate printed.

bun run quality-gate --correlation <checkout>/<pointer>   # from this checkout; must exit 0
  • The gate runs the checks list on the repository's entry in repos/repos.json ([[add-repo]] says how to write one), each in the run's checkout and without a shell. Then it runs clean-tree and test-evidence there. The entry is linked to the run and its issue, and logged as that checkout's.
  • A repository with no checks list is refused, and the refusal names the entry to fill in. So is one that tracks files under .tmp/work/run-correlations or .tmp/work/evaluations.
  • In strict mode the run's verdict is read from the run's checkout, where forge:verdict filed it.
  • Then pull and push in that repository.

The PR body MUST follow the canonical template — see [[pr-description]]. The ship report you just wrote is the source material: map its sections into the template (What Shipped → What Changed, the goal from research → Why It's Needed, the Test It Yourself walkthrough → How It Was Tested, real gate output → Test Evidence) and fill Risk & Rollback + Linked Issues & AC Trace.

mkdir -p .tmp/work
cp .claude/skills/pr-description/references/pr-template.md .tmp/work/pr-body.md
# Fill every section from reports/<slug>-ship.md + the plan's Beads map, then validate:
bun run .claude/skills/pr-description/scripts/check-pr-body.ts .tmp/work/pr-body.md   # must be "ok": true

gh pr create --title "<feature title>" --base <base> --body-file .tmp/work/pr-body.md

Keep reports/<slug>-ship.md as the local-only, gitignored record; the PR body is the template-conformant view of the same run.

5. Close out Beads + state

<close-id> is the issue this run closes: the feature or the epic. A run that closes neither keeps the id its implement write named. This is the one write that may name a feature or an epic (.claude/workflows/forge.md, Which bead a phase names).

When <close-id> is a feature or an epic, add its testing attestation first. A gate that runs linked to that issue requires it, and after the write below the run's pointer names that issue:

bd comments add <close-id> "worklog: testing-attestation automation=<yes|no> unit=<yes|no> notes=<short context>"
bd close <close-id>            # skip when the implement phase already closed it (a run that closes no feature or epic)
bd comments add <close-id> "worklog: shipped — PR #<n>; report reports/<slug>-ship.md"
# The tracker is local-only: do not run `bd dolt push`.
bun run forge:phase-gate ship --slug <slug> --write --bead <close-id>     # records the run complete

After ship completes, the forge run is finished — the Stop hook goes quiet and the state file can be archived or removed.

6. Present to the user

🚀 Shipped: <slug>
Report: reports/<slug>-ship.md
PR: <url>
Beads closed: <ids>

Try it: <the single most representative command from the walkthrough>

Exit Criteria

  • reports/<slug>-ship.md exists with before/after, Beads table, and a runnable walkthrough.
  • The quality gate passed through the run's correlation (for a run in another repository: from this checkout, with that repository's checks); branch pushed; PR created with a [[pr-description]]-conformant body (check-pr-body.ts reports ok: true).
  • Every planned Beads task is closed or deferred-with-reason; epic/feature closed.
  • Forge state advanced to ship complete.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall