ship
Branch-level release with five gates before the act - clean-state, tests, eval-vs-target, docs drift, and attribution sweep; any failing gate stops the release with its output. Then push, and under push: branch-pr open a report-shaped PR wiring the issue-closing reference in tickets mode or PLAN task IDs in document mode. Use when the user asks to ship, release, cut, or open the PR for a feature or branch.
- License 许可
- MIT
- 最近更新
- 2026-09-28
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- ship
- description
- Branch-level release with five gates before the act - clean-state, tests, eval-vs-target, docs drift, and attribution sweep; any failing gate stops the release with its output. Then push, and under push: branch-pr open a report-shaped PR wiring the issue-closing reference in tickets mode or PLAN task IDs in document mode. Use when the user asks to ship, release, cut, or open the PR for a feature or branch.
- argument-hint
- [branch | notes]
02 资源文件 2
- 参考文档references/changelog.md3.5 KB
- 参考文档references/ship-gates.md7.3 KB
03 SKILL.md 正文
/ship — release a feature, gate by gate
/do ships one subtask; /ship ships a feature branch — the accumulated commits, checked as a set. The value is the gates: "ready to merge" usually rests on things nobody re-verified, and /ship verifies each one before anything outward-facing happens. There is no force path — a failing gate stops the release and hands the output to the user.
Adjacent skills: /do (ships one subtask; /ship releases a branch) ·
/audit code (review for defects; /ship runs release gates, not a code
read) · /qa and /secure (called before shipping when the change warrants
it; /ship does not re-run them).
<!-- acstack:runtime --> Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:
link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)" # empty = not symlinked
pack="$(dirname "$(dirname "$link")")" # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
"$pack/bin/acstack-config" || true # resolved keys, with sources
"$pack/bin/acstack-update-check" || true # ≤1 fetch/day; silent ONLY if already checked today
"$pack/bin/acstack-recall" || true # LEARNINGS.md + bug-class names, capped 3KB
else
echo "runtime off — proceeding without recall/update-check"
fi
<!-- /acstack:runtime -->
<!-- acstack:principles -->
Operating principles
- Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
- Never delete a decision. Supersede it:
~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason. - Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
- Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
- Attribution: follow the project's
attributionsetting (defaultnone) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit-m/-Fmessages only. - Config: read
.claude/acstack.mdat the project root (fall back to~/.claude/acstack.md) before acting.## Settingskeys override pack defaults; a## <skill-name>section overrides both. Unknown keys and sections are ignored. - Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
- Recall: if
LEARNINGS.mdexists at the project root, read it before starting. - Conduct: follow the
acstack-conductblock in this repo's AGENTS.md — the word is the mode; the user sets the pace. - Hackathon lane: if the project's AGENTS.md carries the
acstack:hackathon-laneblock, only/dochanges the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route. <!-- /acstack:principles -->
One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name
its path in the report's scope line. If more than one candidate set exists
— a monorepo, nested products, an apps/* tree each with its own docs —
list the candidates and STOP. Never pick one silently: a confident answer
about the wrong product is worse than no answer (conduct rule 8).
The five gates
Run in order; each reports before the act. Any gate that fails STOPS the
release with its evidence — the user decides what to fix. Exact commands
and the PR body template live in references/ship-gates.md.
One documented exception: gate 4's journal-mention check proposes
/journal rather than blocking. It matches commit subjects verbatim
against JOURNAL.md, and journals rarely quote subjects, so it is
near-always negative even for well-journaled work — a check that weak
must not hold a release. Every other gate blocks. The exception is named
here so the rule stays true everywhere else.
-
State. Working tree clean; current branch is not the default (on default → offer to cut
<branch-prefix><slug>, don't ship from it); the branch is ahead of the default by the commits being shipped. Every gate is branch-local (5.17.6): its verdict is about this branch's tree at this commit. Gate 4's drift is measured against PLAN and JOURNAL as of this branch, which the integrator may already have moved on the default — the merged tree is theirs to re-check, with the project's re-derivation tool if it has one. The report says so with the canonical scope line (under "The act"), never by implication. -
Tests. Run the project's suite — the
test-commandconfig key if set, otherwise auto-detected — and record the summary numbers verbatim. No suite and notest-command→ say so plainly; a missing suite is never a silent pass. -
Eval. If
eval/spec.mdexists, run the eval by its own run command. Read its exit code BEFORE its headline — the code says whether a number exists at all, and comparing a headline produced by a half-dead run is how a crash gets shipped as a score. The runner contract (../eval-run/references/runner-template.md, item 7) defines three, and this gate reads the VALUE, not merely zero/non-zero:Exit Gate 3 does 0Compare headline vs target, then run the non-regression floor below. 1BLOCK — "the eval did not run." Report it as a harness failure, never as a score. Quote the runner's own NO SCORE line. Do not compare a stale results file to the target: there is no new number. 2BLOCK — "completed with N errored cases." Name N and the categories. The headline is computed over fewer graded cases than the golden set holds, so it is under-covered rather than wrong, and the remedy is the subject or the environment — not the target. A runner predating this contract may still exit
1on a completed run with errored cases; that reads as a BLOCK either way, so the gate stays safe against an old runner — it just names the cause less precisely. Below target BLOCKS the ship (this is what makes "the eval is the spec" bite at release time). No eval → one honest line, gate passes. Then the per-category TARGETS from the spec — these are not the same check as the floor below, and the floor cannot stand in for them. The spec's Targets table states a minimum per category (refusal | 100%,edge | ≥ 80%, …). Read that table and BLOCK when any category is under its own target, naming the category, its rate and its target. Without this, a category can rise and still be far below the bar it was written to meet: a refusal category going 40% → 60% passes a regression check and fails the spec, and refusal is exactly where that matters. Forgiven failures do not count toward a category target. The runner prints a category asp + afwith the forgiven count in brackets — use the plainp, because/eval-specstates the policy is "never used to move a category over its target", and reading the bracketed number is precisely that move. No Targets table in the spec → say so plainly and pass this sub-gate; never invent a target.Then the per-category non-regression floor, which neither the headline nor the targets give you: compare the new results file against the LAST COMMITTED one and BLOCK when any category fell, naming the category and both rates. A change that lifts the overall number while breaking every refusal case clears the target comparison above — refusal is small, so its collapse barely moves an average — and that is the case this floor exists for.
../eval-run/references/regression-gate.pydoes the comparison. No committed baseline passes and SAYS so; an absent baseline reported as a clean pass is false confidence, not a pass. -
Docs. Cheap drift pass, not a full audit: README quickstart still true; the shipped work's PLAN exit criterion run if runnable; JOURNAL mentions the work (if not → propose /journal before shipping). Deep drift stays /audit docs.
-
Attribution. Sweep the branch's commit messages and the intended PR body per the
attributionconfig — defaultnonemeans any AI trailer or tool mention fails the gate, listing the offenders.
The act
Only when all five pass. Push per push config. Whether a PR follows
depends on that config — everything below about PR bodies applies only
under push: branch-pr.
Under push: direct there is no PR to open. Say so plainly, push the
branch, and report the gate evidence as the release record — do not
invent a PR step the config disabled. If the user wants a PR anyway,
they ask; /ship never flips the config on their behalf. gh is
required only where a PR is actually opened — that is push: branch-pr, and tickets mode's issue-closing links. Under push: direct a missing gh blocks nothing: check the precondition where it
applies, and on failure name which one failed and stop with the branch
pushed.
Then propose the changelog entry — references/changelog.md. /ship
cut releases and wrote none until 4.64. It is PROPOSED and never committed
or pushed without the user saying so: a changelog is outward-facing text
with their name on it. The reference carries where the facts come from
(commits bound the range, the journal supplies the framing — neither alone
is enough) and what never goes in.
Under push: branch-pr, the PR body is report-shaped: what-and-why lede,
the scope line, a per-gate evidence table (the test/eval numbers, the doc
checks), and an out-of-scope line. The scope line is the same in every
report this pack's branch-reading skills make — one source line, verbatim
(5.17.6):
Scope: branch <branch> @ <sha> vs <default> @ <sha> — a verdict about this branch's tree, not the project's; the merged tree is the integrator's to re-check.
Under push: direct the same content is delivered as the report itself,
since there is no PR to carry it.
- Tickets mode: the PR carries
Fixes #Nfor each issue the branch completes (from the commits'#Nrefs and the milestone) and is tied to that milestone. Preconditions as above, plus a GitHub remote. - Document mode: the body names the PLAN task IDs shipped; a phase
exit criterion that passed in gate 4 is ticked per /do's convention —
committed to the branch (
completed <phase> exit criterion) BEFORE the push, so the tick ships with the work and gate 1's clean-tree assertion stays honest. No orphan post-push edit.
The report's first line is the verdict — SHIPPED — <PR url>,
BLOCKED at gate <n> — <reason>, or PUSHED (no PR — push: direct) —
then one line per gate as its evidence. A reader who stops after one
line must still know whether the release happened. /ship opens the PR;
it never merges — the merge is a human act.
Hackathon mode (mode: hackathon)
No hackathon path, deliberately. When the project's AGENTS.md carries the
acstack:hackathon-lane block, stop before gate 1 and say so. Every
session there sits on a task branch that /do merges into the local main
itself (see ../do/references/hackathon-lane.md); shipping one would push
it, or open a pull request against origin/main, which has none of the
local landings. In the lane there is no such branch left.
Correction (2026-09-24): there always is one, the session's own task
branch, found by a disprove-agent. At submission, run the project's tests
yourself and push main (git push origin main); the plan's
## Submission checklist is the gate.
04 同仓库更多 Skills
why
Decision archaeology - answers why the code, config, or plan is the way it is by searching the record in a fixed order: BRIEF constraints, dated PLAN decisions, JOURNAL entries, then git history. Stops at the first real answer, cites it with a date, and says no recorded rationale rather than inventing one. Use when someone asks why something is this way, why a choice was made, or where a decision is written down.
verify
Audit a completion claim made by someone else - another session, agent, or teammate - against the running system rather than the diff. Re-derives what the claim's acceptance demands, runs it, and returns CONFIRMED, OVERSTATED, FALSE or UNVERIFIABLE with the command and its output. Never fixes, never edits the claim or the acceptance. Use when handed a "done", "all green", "merged" or "it works" you did not produce yourself.
triage
Backlog hygiene sweep - stale items, duplicate pairs, missing acceptance criteria, unblocked-but-unassigned work, and milestone burn, delivered as a report first with only user-approved actions applied. Works on GitHub Issues in tickets mode and on PLAN.md checkboxes in document mode. Use when the user asks to triage, groom, or clean up the backlog or the plan's open tasks.
ticket
Capture a brain-dump as a well-formed work item - verb-first title, acceptance criteria, file paths when known, an out-of-scope line. Files a GitHub issue in tickets mode or appends a numbered PLAN.md task in document mode; unknowns are marked TBD, never invented. Use when the user brain-dumps an idea, bug, or task to capture for later, or asks to ticket, file, or note something as work.
secure
Security review with a confidence gate - a finding exists only with a concrete exploit scenario and a high/medium/low confidence rating; everything else goes to a worth-hardening list, never inflated. Sweeps five surfaces: auth gates, secrets hygiene, injection and unsafe sinks, unsafe deserialization/crypto/transport, and LLM tool-use trust boundaries. Reports only, never fixes. Use when the user asks for a security review or to check vulnerabilities, secrets, or auth.
retro
Trend review across many sessions - velocity vs planned dates, eval-score trend toward target, failure-category trends from journal triage and investigations, and a status check on every open PLAN risk. Reads JOURNAL/PLAN/eval history, writes a dated retro entry into JOURNAL.md. Use when the user asks for a retro, a weekly review, or a phase-end wrap-up.