jupes/agent-forge-harness / .agents/skills/forge-ship
forge-ship
VerifiedVerify 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 asdata.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-evidencereads every commit of the branch's own, the ones sinceorigin/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 noorigin/HEADthe gate reads the last five commits instead and says so (git remote set-head origin --autosets 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
checkslist on the repository's entry inrepos/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
checkslist is refused, and the refusal names the entry to fill in. So is one that tracks files under.tmp/work/run-correlationsor.tmp/work/evaluations. - In strict mode the run's verdict is read from the run's checkout, where
forge:verdictfiled 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.mdexists 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.tsreportsok: true). - Every planned Beads task is closed or deferred-with-reason; epic/feature closed.
- Forge state advanced to
shipcomplete.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |