ytstack:ship
Adapted from gstack's ship skill (MIT, Garry Tan), baseline in metadata.upstream; see NOTICE.
The release path for a feature branch: integrate the base, prove the change with the project's own tests, audit coverage and plan completion, review the diff, cut the version and CHANGELOG, sync the docs, commit, push and open (or update) the pull request. It runs with git, gh and the project's test command; nothing else is required. In a ytstack project it also refuses to ship a slice that is not closed on paper and puts the slice's outcomes into the PR body.
This skill differs from upstream gstack ship: no review log, receipts, merge queue, Greptile/Capy, outside-voice CLI, Apple release, budget handoff, measure loop or specialist review army; the review is one checklist pass plus one fresh-context adversarial subagent, and every helper binary is replaced by plain git/gh. Commit subjects and PR titles keep the <type>: / M###-S##-T##: prefix that ytstack projects use (upstream dropped it in v1.99).
Anti-Pattern: "The tests passed earlier in this session, just push it"
Earlier runs tested a different tree. The base moved, review fixes landed, generated tests and doc edits changed content. A push is the moment a claim becomes public, so it rests on a run of the exact tree being pushed, merged with the current base. Rerun the suite (step 13); it costs minutes and saves a red main.
Checklist
You MUST create a task for each of these items and complete them in order:
- Run preamble -- resolver, branch, base branch, platform, slice paper state, version sources
- Preflight gates -- not on the base branch, git checkout, no open tasks, list the uncommitted changes that ship
- Merge the base --
git fetch + git merge origin/<base>; resolve or ask on conflicts
- Run tests -- the project's full suite on the merged code; triage failures (
references/tests.md)
- Coverage audit -- fresh-context subagent traces changed paths, coverage gate (
references/test-coverage.md)
- Plan completion -- bind the plan (slice plan in ytstack), audit, run plan verification, scope drift (
references/plan-completion.md)
- Pre-landing review -- checklist pass plus adversarial subagent, Fix-First, at most 3 fix cycles (
references/review-checklist.md)
- Version bump -- detect state, pick the level, write every version source
- CHANGELOG -- one user-facing entry covering every commit (only if a CHANGELOG exists)
- Follow-ups -- TODOS.md deferrals and completions (only if
TODOS.md exists)
- Documentation sync -- doc-audit subagent, validate its edits (
references/documentation-sync.md)
- Commit -- bisectable commits staged by name, release metadata last
- Verification gate -- fresh full test run (and build) of the exact tree to be pushed
- Push -- secret scan, idempotency check,
git push -u origin <branch>
- Pull request + report -- title, body, create or update, PR URL and next-step suggestion (
references/pr-body.md)
Process Flow
digraph ship {
"Start" [shape=doublecircle];
"Gates pass?" [shape=diamond];
"Merge base" [shape=box];
"Tests green?" [shape=diamond];
"Audits: coverage, plan" [shape=box];
"Review + Fix-First" [shape=box];
"Fixes applied?" [shape=diamond];
"Version, CHANGELOG, follow-ups, docs" [shape=box];
"Commit" [shape=box];
"Fresh run green?" [shape=diamond];
"Push + PR" [shape=box];
"Report PR URL" [shape=doublecircle];
"Stop with reason" [shape=doublecircle];
"Start" -> "Gates pass?";
"Gates pass?" -> "Merge base" [label="yes"];
"Gates pass?" -> "Stop with reason" [label="no"];
"Merge base" -> "Tests green?";
"Tests green?" -> "Audits: coverage, plan" [label="yes"];
"Tests green?" -> "Stop with reason" [label="in-branch failure"];
"Audits: coverage, plan" -> "Review + Fix-First";
"Review + Fix-First" -> "Fixes applied?";
"Fixes applied?" -> "Tests green?" [label="yes, cycle < 3"];
"Fixes applied?" -> "Version, CHANGELOG, follow-ups, docs" [label="no"];
"Version, CHANGELOG, follow-ups, docs" -> "Commit";
"Commit" -> "Fresh run green?";
"Fresh run green?" -> "Push + PR" [label="yes"];
"Fresh run green?" -> "Tests green?" [label="no, triage"];
"Push + PR" -> "Report PR URL";
}
Preamble
Run this first, from the checkout you are shipping:
# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.
_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"
if [ -f "$_LIB" ]; then
. "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null
_PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"
else
# Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.
_IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)
_PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
_YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""
[ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }
fi
cd "$_PROJECT_DIR" 2>/dev/null || true
_PROJECT_SLUG=$(basename "$_PROJECT_DIR") # display only
_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)
_BRANCH=$(git branch --show-current 2>/dev/null); _BRANCH=${_BRANCH:-unknown}
echo "BRANCH: $_BRANCH"
echo "PROJECT_SLUG: $_PROJECT_SLUG"
echo "HAS_YTSTACK: $_HAS_YTSTACK"
echo "YTSTACK_SCOPE: $_YT_SCOPE"
echo "YT_DIR: $_YT_DIR"
echo "IS_GIT: $_IS_GIT"
# Non-interactive detection
if [ -n "$YTSTACK_NON_INTERACTIVE" ] || [ -n "$OPENCLAW_SESSION" ] || [ -n "$CLAUDE_AGENT_TEAM_MEMBER" ]; then
echo "YTSTACK_NON_INTERACTIVE: true"
else
echo "YTSTACK_NON_INTERACTIVE: false"
fi
# Active work + slice paper state: every task in the slice plan needs a non-draft summary.
_M=none; _S=none; _OPEN_TASKS=""; _SLICE_PLAN=none
if [ -n "$_YT_DIR" ] && [ -f "$_YT_DIR/STATE.md" ]; then
_M=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1); _M=${_M:-none}
_S=$(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1); _S=${_S:-none}
echo "CURRENT_MILESTONE: $_M"
echo "ACTIVE_SLICE: $_S"
if [ -f "$_YT_DIR/$_M-$_S-PLAN.md" ]; then
_SLICE_PLAN="$_YT_DIR/$_M-$_S-PLAN.md"
for t in $(grep -oE '^- \[.\] T[0-9][0-9] --' "$_SLICE_PLAN" | grep -oE 'T[0-9][0-9]'); do
f="$_YT_DIR/$_M-$_S-$t-SUMMARY.md"
{ [ ! -f "$f" ] || grep -q '^closed: draft' "$f"; } && _OPEN_TASKS="$_OPEN_TASKS $t"
done
fi
fi
echo "SLICE_PLAN: $_SLICE_PLAN"
echo "OPEN_TASKS: ${_OPEN_TASKS:-none}"
# Hosting platform and base branch (PR target, else the repo default).
_REMOTE=$(git remote get-url origin 2>/dev/null || echo "")
_PLATFORM=unknown
case "$_REMOTE" in *github.com*) _PLATFORM=github ;; *gitlab*) _PLATFORM=gitlab ;; esac
_GH=no; command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && _GH=yes
[ "$_PLATFORM" = unknown ] && [ -n "$_REMOTE" ] && [ "$_GH" = yes ] && _PLATFORM=github
_BASE=""
if [ "$_PLATFORM" = github ] && [ "$_GH" = yes ]; then
_BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || true)
[ -n "$_BASE" ] || _BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || true)
fi
[ -n "$_BASE" ] || _BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
[ -n "$_BASE" ] || { git rev-parse --verify -q origin/main >/dev/null 2>&1 && _BASE=main; }
[ -n "$_BASE" ] || { git rev-parse --verify -q origin/master >/dev/null 2>&1 && _BASE=master; }
_BASE=${_BASE:-main}
echo "REMOTE: ${_REMOTE:-none}"
echo "PLATFORM: $_PLATFORM"
echo "GH_AUTH: $_GH"
echo "BASE_BRANCH: $_BASE"
echo "ON_BASE: $([ "$_BRANCH" = "$_BASE" ] && echo yes || echo no)"
echo "DIRTY: $([ -n "$(git status --porcelain 2>/dev/null)" ] && echo yes || echo no)"
# Version sources: current tree vs the (last fetched) base.
_rd() { if [ -n "$_REF" ]; then git show "$_REF:$1" 2>/dev/null; else cat "$1" 2>/dev/null; fi; }
_ver() { _REF="$1"; _v=$(_rd VERSION | head -1 | tr -d '[:space:]')
for _j in package.json .claude-plugin/plugin.json .codex-plugin/plugin.json; do
[ -n "$_v" ] || _v=$(_rd "$_j" | grep -m1 '"version"' | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
done
for _t in pyproject.toml Cargo.toml; do
[ -n "$_v" ] || _v=$(_rd "$_t" | grep -m1 -E '^version[[:space:]]*=' | sed -E 's/^version[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/')
done
echo "$_v"; }
_VS=""
for f in VERSION package.json .claude-plugin/plugin.json .codex-plugin/plugin.json pyproject.toml Cargo.toml; do
[ -f "$f" ] && _VS="$_VS $f"
done
echo "VERSION_SOURCES:${_VS:- none}"
_CUR=$(_ver ""); echo "CURRENT_VERSION: ${_CUR:-none}"
_BV=""; git rev-parse --verify -q "origin/$_BASE" >/dev/null 2>&1 && _BV=$(_ver "origin/$_BASE")
echo "BASE_VERSION: ${_BV:-none}"
echo "LAST_TAG: $(git describe --tags --abbrev=0 2>/dev/null || echo none)"
echo "CHANGELOG: $([ -f CHANGELOG.md ] && echo CHANGELOG.md || echo none)"
echo "TODOS: $([ -f TODOS.md ] && echo TODOS.md || echo none)"
echo "TEST_DOC: $(grep -lE '^## Testing' CLAUDE.md AGENTS.md TESTING.md 2>/dev/null | tr '\n' ' ')"
Flags read later: OPEN_TASKS, SLICE_PLAN, BASE_BRANCH (written <base> below), PLATFORM, GH_AUTH, VERSION_SOURCES, CURRENT_VERSION, BASE_VERSION, CHANGELOG, TODOS, TEST_DOC. Re-read BASE_VERSION after step 3's fetch when it said none.
Spawned sessions. When YTSTACK_NON_INTERACTIVE is true, never call AskUserQuestion: take the RECOMMENDATION option and log one line, [ytstack:ship] auto-picked <X> (<label>) because YTSTACK_NON_INTERACTIVE=true. Choices that need a human (a loosened test gate, an unverifiable plan item, accepting a documentation risk) are never auto-accepted: they stay open and the PR is opened as a draft, or the ship stops where the step says so.
Routine work needs no confirmation: including the branch's uncommitted changes, a PATCH or MICRO bump, the CHANGELOG draft, commit grouping, marking completed TODOs and AUTO-FIX review findings. Ask only where a step says so.
Procedure
1. Run preamble
Run the bash block above and keep its output; later steps refer to the flags by name.
2. Preflight gates
IS_GIT is no: stop with "not a git checkout".
ON_BASE is yes: stop with "You're on the base branch <base>. Ship from a feature branch."
OPEN_TASKS is not none: stop and name each task that still needs ytstack:summarize-task. A closed: draft stub is not a summary.
PLATFORM is not github or GH_AUTH is no: continue, and say once that step 15 will print the PR command to run by hand (GitLab: glab when it is installed).
DIRTY is yes: list the uncommitted and untracked files (git status --porcelain). They ship with this branch; do not ask. Name the .ytstack/ files among them (task summaries, STATE.md, DECISIONS.md and KNOWLEDGE.md entries); they are part of the change and get committed in step 12. A file that clearly belongs to unrelated work (another task's edits in a shared tree) stays unstaged and is named in the final report.
3. Merge the base branch (before tests)
git fetch origin "<base>" && git merge --no-edit "origin/<base>"; echo "MERGE_EXIT: $?"
git log --oneline "origin/<base>..HEAD" | wc -l | sed 's/^ */COMMITS_AHEAD: /'
git diff --stat "origin/<base>" | tail -1
A failed fetch: stop and report the error (no network, no access); nothing below runs on a stale base. Already up to date is fine. Never rebase.
Simple conflicts resolve without asking: VERSION and manifest versions (take the higher base version; step 8 bumps from there), CHANGELOG ordering (keep both entries, base entries below the branch's), lockfiles (regenerate with the package manager). Anything else:
Merging origin/{base} into {BRANCH} ({PROJECT_SLUG}) conflicts in {N} files: {file: one-line nature of the conflict, each}.
Simplify: the base branch changed the same lines this branch changed. Someone has to decide which version wins, line by line. I have a proposal for each file.
RECOMMENDATION: Choose A because the proposals keep both changes where they are compatible, and you see each one before it is committed.
A) Resolve as I propose: I show each file's resolution, then commit the merge
Completeness: 10/10, effort: human: ~2 min / CC: ~5 min, tier: task
B) You resolve them yourself; I stop here and you re-run ship afterwards
Completeness: 10/10, effort: human: ~10 min / CC: 0, tier: task
C) Abort the merge (git merge --abort) and stop
Completeness: 3/10, effort: human: 0 / CC: 0, tier: task
After a resolved merge, commit it (git commit --no-edit) and continue; the tests below run on the merged code.
4. Run tests on the merged code
- Find the test command:
TEST_DOC names the file with a ## Testing section; read it. Not documented, or the project has no tests: read ${CLAUDE_SKILL_DIR}/references/tests.md sections 1-2 and follow them (ask for the command, or decide about a missing suite).
- Run the full suite. Run every applicable suite (unit, integration, shell tests), not just one. In a ytstack project also run each
## Verification command of the active slice's task plans. Keep the output in a log file (mktemp), print the summary lines.
- Read each result as pass, zero-run or count-unavailable (
references/tests.md section 3). A zero-run is a failure.
- Any failure: read
${CLAUDE_SKILL_DIR}/references/tests.md section 4 and triage. In-branch failures stop the ship.
- Prompt or eval files changed:
references/tests.md section 5.
- Print one line per suite:
Tests: <label> <N> passed or count unavailable. Remember the commands; step 13 reruns exactly these.
5. Coverage audit
Read ${CLAUDE_SKILL_DIR}/references/test-coverage.md and execute it: dispatch the audit subagent, process its result, apply the coverage gate. Keep the diagram, counts and gate result for the PR body. Tests it generates stay uncommitted until step 12.
6. Plan completion, plan verification, scope drift
Read ${CLAUDE_SKILL_DIR}/references/plan-completion.md and execute it in order: bind the plan (in a ytstack project the slice plan SLICE_PLAN plus its task plans and summaries), dispatch the audit, apply the gates, run the plan's verification checks, write the scope check. Deferrals approved here go to step 10.
7. Pre-landing review
Read ${CLAUDE_SKILL_DIR}/references/review-checklist.md and execute it: PR type, Pass 1 (CRITICAL) and Pass 2 (INFORMATIONAL) over the merge-base diff, the sideways sweep on every finding, the adversarial subagent for diffs of 200+ changed lines, then Fix-First. Gate-integrity hunks that step 5 flagged join Pass 1.
Fixes applied: commit them, rerun step 4, and review the new range again. At most 3 fix cycles; on the third, stop and name the remaining blockers to the user unfixed. A clean pass continues to step 8.
For a task-level two-stage review with the superpowers receiving discipline, ytstack:code-review exists; ship does not invoke it, its own review covers the whole branch diff.
8. Version bump
Skip the whole step when VERSION_SOURCES is none: print Version bump: skipped (no version source); step 9 writes under ## [Unreleased], step 15 uses an unprefixed title. Never create a VERSION file.
The project's own release rules win: read CLAUDE.md / AGENTS.md / CONTRIBUTING.md for a release or versioning section (which files carry the version, 3 or 4 components, who bumps) and follow it over the defaults below.
- Classify.
- ALREADY_BUMPED:
CURRENT_VERSION is higher than BASE_VERSION. Keep it; never bump twice. Derive the level from the first component that changed.
- FRESH:
CURRENT_VERSION equals BASE_VERSION (or the base has no version yet).
- DRIFT: the version sources disagree with each other (
grep -n '"version"\|^version' <each source>). When exactly one source still holds BASE_VERSION and the others agree on a higher one, set the stale one to match and continue as ALREADY_BUMPED. Any other disagreement: stop and show the values; the user reconciles them.
- Pick the level from the diff (FRESH only):
- MICRO (4-component versions only): under 50 changed lines, trivial tweak or config. With 3 components this is PATCH.
- PATCH: 50+ lines, no feature signal.
- MINOR: any feature signal (new command, route, page, skill, migration, module) or 500+ lines. Ask.
- MAJOR: breaking change or a milestone release. Ask.
Shipping {BRANCH} of {PROJECT_SLUG} (currently v{CURRENT_VERSION}). The diff {has a feature signal: {signal} | breaks {what}}, which suggests a {MINOR|MAJOR} bump to v{proposed}.
Simplify: the version number tells users what to expect. A minor bump says "new things, nothing breaks"; a major bump says "you may have to change something"; a patch says "fixes only".
RECOMMENDATION: Choose A because {the signal} is {a new capability users can use | a change existing users must adapt to}.
A) {MINOR|MAJOR} bump to v{proposed}
Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task
B) One level smaller: v{smaller}
Completeness: 7/10, effort: human: 0 / CC: ~1 min, tier: task
C) Cancel the ship before any release write
Completeness: 10/10, effort: human: 0 / CC: 0, tier: task
- Check for collisions (FRESH and ALREADY_BUMPED):
git tag -l "v<NEW_VERSION>" must be empty. With GH_AUTH: yes, gh pr list --state open --json number,title,headRefName and look for another branch whose title claims v<NEW_VERSION> or higher at the same level. A sibling holds it: advance past the highest claimed version and say so; for ALREADY_BUMPED, ask before changing an existing version.
- Write (FRESH, or an approved re-bump) with Edit, one file at a time:
VERSION (keep its component count), package.json "version", .claude-plugin/plugin.json / .codex-plugin/plugin.json "version", pyproject.toml version = under [project] or [tool.poetry], Cargo.toml version = under [package], and the root package version in package-lock.json (top-level version and packages[""].version). Then grep -rn "<old version>" over the manifests and README badges the project keeps in sync (its release rules name them) and update those. Do not create a git tag.
- Print
Version: v<BASE_VERSION> -> v<NEW_VERSION> (<level>).
9. CHANGELOG
CHANGELOG is none: print CHANGELOG: skipped (none at CHANGELOG.md) and write nothing; the PR body carries the release notes. Never create the file.
- Read the CHANGELOG header and the latest entry to learn its format (heading style, date format, sections).
- List every commit on the branch:
git log origin/<base>..HEAD --oneline. Count them; this is the checklist.
- Read
git diff origin/<base> to understand what each commit changed.
- Group by theme before writing: features, performance, fixes, removals, infrastructure and tests, refactors.
- Write one entry with Edit (never Write on CHANGELOG.md), after the header and before the first release entry, dated today:
## [<NEW_VERSION>] - YYYY-MM-DD (or the file's own heading style), with ### Added / ### Changed / ### Fixed / ### Removed as applicable. Entries this branch already added for these commits are replaced by the one unified entry. FRESH and ALREADY_BUMPED both have a release version: the heading is NEW_VERSION (for ALREADY_BUMPED that is the version the branch already carries). Only when there is no release version (no version source, or the project's release rules leave the bump to someone else so NEW_VERSION equals BASE_VERSION) does the entry go under ## [Unreleased], never under an already released heading.
- Voice: lead with what the user can now do that they could not before. Plain language, no implementation detail, nothing about internal tracking (TODOS,
.ytstack bookkeeping): no tracker codes (issue keys, M###-S## refs) anywhere in the entry, and a bold lead that a user of the project understands without the repository's coined terms. Each bullet names a concrete change; cut any bullet that would fit every release.
- Cross-check against the commit list from item 2: every user-facing change appears. Merges, version bumps and fixes to work introduced earlier on this same branch need no bullet.
Do not ask the user to describe the changes; infer them from the diff and the commits.
10. Follow-ups (TODOS.md)
TODOS is none: do not create the file. Approved deferrals (step 6 NOT DONE items, step 4 pre-existing failures recorded as follow-ups, review findings deferred in step 7) go into the PR body's ## Follow-ups; in a ytstack project, also name them in the final report for ytstack:reassess-roadmap.
TODOS is TODOS.md:
- Add each approved deferral as an item under its component heading, priority-sorted:
### <Title>
**What:** one line. **Why:** the concrete problem. **Context:** enough to start in three months.
**Effort:** S / M / L / XL **Priority:** P0-P4 **Depends on:** <or None>
Plan deferrals are P1 with Deferred from plan: <path>; pre-existing test failures are P0 with the error output and the branch. Reuse a matching existing item instead of duplicating. Never invent unapproved follow-ups.
- Detect completed items: compare titles, files and behaviour with
git diff origin/<base> and git log origin/<base>..HEAD --oneline. Move proven completions to ## Completed with **Completed:** v<NEW_VERSION> (YYYY-MM-DD); leave uncertain ones open.
- Report additions, completions and the remaining count. A failed write is a warning, not a blocker; carry the unsaved items into the PR body and never claim they were saved.
11. Documentation sync
Read ${CLAUDE_SKILL_DIR}/references/documentation-sync.md and execute it on every ship: dispatch the doc-audit subagent, validate exactly what it changed, recover or ask when it is blocked. Keep documentation_section and the status line for the PR body.
12. Commit (bisectable chunks)
Already committed and nothing new: continue to step 13. Never create an empty commit. Check the branch first: git branch --show-current must print BRANCH.
- Group changes into logical commits: each source change with its tests; config and routes with what uses them; migrations may stand alone; docs from step 11 with the change they describe or as one
docs: commit. Under 50 lines across fewer than 4 files may be one commit.
- Order dependencies first (infrastructure, then models and services, then controllers and views). Each commit must work on its own: no broken imports, no missing code.
- Stage by name (
git add <paths>), never git add -A or git add .. Message <type>: <summary> (feat, fix, chore, refactor, docs, test) with a short body, or the project's convention (in a ytstack project, code that belongs to a task keeps its M###-S##-T##: prefix). A fix for an issue the user named adds Fixes #<n>. Add the session's commit attribution trailer when the host defines one.
.ytstack/ files that are part of the change (summaries, STATE.md, decision and knowledge entries) are committed, as chore: update ytstack state for <M###-S##> when they do not belong to a code commit.
- Last: the release metadata in one commit:
VERSION, manifests, lockfile version, CHANGELOG.md, TODOS.md, as chore: release v<NEW_VERSION> (or the project's release-commit convention).
Commit signing and hooks run as configured. A failed hook or signature is a blocker to report and fix at the cause, never to bypass.
13. Verification gate
IRON LAW: no completion claim without fresh verification evidence.
git status --porcelain must be empty except files you deliberately left out in step 2 (name them). Anything else: commit it per step 12 or stop.
- Rerun every suite from step 4 (same commands) on the committed tree whenever anything changed since that run: review fixes, generated tests, merged base, doc edits, the version bump. Only when literally nothing changed since a green run may you cite that run (command, result, time).
- Run the project's declared build when it has one (
build script in package.json, make build, the build step in CI) and its lint or check command when CI runs it (for ytstack itself: bin/ytstack-check). A missing prerequisite or failed build stops the ship: report the command and the error; never substitute another command.
- Any failure: back to step 4's triage; nothing is pushed red.
- Paste the evidence: per suite the command, exit code and pass count (or
count unavailable), and the build result. This is what the PR's ## Test plan cites.
14. Push
- Secret scan of the added lines:
git diff "origin/<base>...HEAD" | grep -nE '^\+.*(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|xox[abpors]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_-]{35})' && echo "SECRET_HIT" || echo "SECRET_CLEAN"
SECRET_HIT: STOP. Show the file and line (not the secret). Remove it from the code and the branch history before anything is pushed; a pushed credential must be rotated. Test fixtures with obviously fake values are fine once you have read them.
- Already pushed?
_L=$(git rev-parse HEAD); _R=$(git ls-remote --heads origin "refs/heads/<branch>" | cut -f1)
[ "$_L" = "$_R" ] && echo "PUSH: ALREADY_PUSHED" || echo "PUSH: NEEDED (remote ${_R:-none})"
A failed lookup: stop and report. ALREADY_PUSHED: go to step 15.
git push -u origin "<branch>".
- Push fails: stop, no PR claim. Non-fast-forward:
git fetch origin "<branch>", merge it (step 3's conflict rules), rerun steps 4 and 13, push again. Authentication, hook or network failure: report the error and fix the cause; never force-push, never --no-verify.
15. Pull request and report
Read ${CLAUDE_SKILL_DIR}/references/pr-body.md and execute it: look up the open PR, prepare the title, compose the body (in a ytstack project with the ## Slice section built from the slice goal and each task's Outcome paragraph), secret-check it, create or update the PR, print the URL. A draft PR when a loosened gate is left open or a plan item stays unverified.
Then report, in this shape:
SHIP: <PR URL | pushed, PR not created: <reason>>
Version: v<old> -> v<new> (<level>) | skipped
Tests: <label> <N> passed[, ...] | Build: <ok | none declared>
Coverage: <X>% value-weighted, gate <PASS | accepted risk | skipped>
Plan: <N/M done | not run> | Review: <summary line> | Docs: <updated | current | blocked>
Follow-ups: <count, where they are recorded>
Terminal State
The terminal state is one of:
- Returning control to the user with the PR URL (or the pushed branch and the manual PR command when the PR could not be created), plus one next-step suggestion:
ytstack:reassess-roadmap when the slice is complete, ytstack:retro when the milestone is complete, ytstack:document-release when a version is to be cut or the docs need a full post-ship pass.
- Exiting without a push (a gate stopped the ship: open tasks, on the base branch, in-branch test failures, a NOT DONE plan item the user chose to finish, a secret hit, a cancelled version bump, a blocked documentation audit). Name the gate and what clears it.
Do NOT auto-invoke any downstream skill, and do NOT merge the PR, enable auto-merge or delete the branch. The ONLY skills you may invoke after this one are the ones the user explicitly asks for; ytstack:reassess-roadmap, ytstack:retro, ytstack:document-release, ytstack:systematic-debugging and ytstack:finish-branch are suggestions to name, not to run.
1---2name: ship3description: "Ships the current branch (merge the base, tests, coverage and plan audit, pre-landing review, version and CHANGELOG, docs sync, commit, push, pull request), gated on ytstack's slice state. Use when a slice or milestone is closed on paper and verified, or when the user says ship it, open the PR, land this, create a PR. Not before every task of the slice has a summary (summarize-task), not for merging into the base locally (finish-branch), and never for a merge without an explicit merge instruction."4metadata:5 source: https://skillmd.com/skills/yesterday-ai/ship6 tier: task7 version: 1.0.28 upstream: "gstack v1.99.3.0 (ship/, commit 1d3c63c53)"9allowed-tools:10 - Bash11 - Read12 - Write13 - Edit14 - Grep15 - Glob16 - Agent17 - AskUserQuestion18---1920# ytstack:ship2122Adapted from gstack's `ship` skill (MIT, Garry Tan), baseline in `metadata.upstream`; see NOTICE.2324The release path for a feature branch: integrate the base, prove the change with the project's own tests, audit coverage and plan completion, review the diff, cut the version and CHANGELOG, sync the docs, commit, push and open (or update) the pull request. It runs with git, gh and the project's test command; nothing else is required. In a ytstack project it also refuses to ship a slice that is not closed on paper and puts the slice's outcomes into the PR body.2526This skill differs from upstream gstack ship: no review log, receipts, merge queue, Greptile/Capy, outside-voice CLI, Apple release, budget handoff, measure loop or specialist review army; the review is one checklist pass plus one fresh-context adversarial subagent, and every helper binary is replaced by plain git/gh. Commit subjects and PR titles keep the `<type>:` / `M###-S##-T##:` prefix that ytstack projects use (upstream dropped it in v1.99).2728<HARD-GATE>29Do NOT push, open a pull request, bump the version or write the CHANGELOG until the tests passed on the code merged with the base branch, and do NOT ship a ytstack slice while `OPEN_TASKS` is not `none`.30Do NOT merge the pull request, enable auto-merge or push to the base branch. A merge needs the user's explicit instruction; `ytstack:finish-branch` is the local-merge path.31Do NOT force-push, rebase a shared branch, or bypass hooks and commit signing (`--no-verify`, `--no-gpg-sign`).32</HARD-GATE>3334## Anti-Pattern: "The tests passed earlier in this session, just push it"3536Earlier runs tested a different tree. The base moved, review fixes landed, generated tests and doc edits changed content. A push is the moment a claim becomes public, so it rests on a run of the exact tree being pushed, merged with the current base. Rerun the suite (step 13); it costs minutes and saves a red main.3738## Checklist3940You MUST create a task for each of these items and complete them in order:41421. **Run preamble** -- resolver, branch, base branch, platform, slice paper state, version sources432. **Preflight gates** -- not on the base branch, git checkout, no open tasks, list the uncommitted changes that ship443. **Merge the base** -- `git fetch` + `git merge origin/<base>`; resolve or ask on conflicts454. **Run tests** -- the project's full suite on the merged code; triage failures (`references/tests.md`)465. **Coverage audit** -- fresh-context subagent traces changed paths, coverage gate (`references/test-coverage.md`)476. **Plan completion** -- bind the plan (slice plan in ytstack), audit, run plan verification, scope drift (`references/plan-completion.md`)487. **Pre-landing review** -- checklist pass plus adversarial subagent, Fix-First, at most 3 fix cycles (`references/review-checklist.md`)498. **Version bump** -- detect state, pick the level, write every version source509. **CHANGELOG** -- one user-facing entry covering every commit (only if a CHANGELOG exists)5110. **Follow-ups** -- TODOS.md deferrals and completions (only if `TODOS.md` exists)5211. **Documentation sync** -- doc-audit subagent, validate its edits (`references/documentation-sync.md`)5312. **Commit** -- bisectable commits staged by name, release metadata last5413. **Verification gate** -- fresh full test run (and build) of the exact tree to be pushed5514. **Push** -- secret scan, idempotency check, `git push -u origin <branch>`5615. **Pull request + report** -- title, body, create or update, PR URL and next-step suggestion (`references/pr-body.md`)5758## Process Flow5960```dot61digraph ship {62 "Start" [shape=doublecircle];63 "Gates pass?" [shape=diamond];64 "Merge base" [shape=box];65 "Tests green?" [shape=diamond];66 "Audits: coverage, plan" [shape=box];67 "Review + Fix-First" [shape=box];68 "Fixes applied?" [shape=diamond];69 "Version, CHANGELOG, follow-ups, docs" [shape=box];70 "Commit" [shape=box];71 "Fresh run green?" [shape=diamond];72 "Push + PR" [shape=box];73 "Report PR URL" [shape=doublecircle];74 "Stop with reason" [shape=doublecircle];7576 "Start" -> "Gates pass?";77 "Gates pass?" -> "Merge base" [label="yes"];78 "Gates pass?" -> "Stop with reason" [label="no"];79 "Merge base" -> "Tests green?";80 "Tests green?" -> "Audits: coverage, plan" [label="yes"];81 "Tests green?" -> "Stop with reason" [label="in-branch failure"];82 "Audits: coverage, plan" -> "Review + Fix-First";83 "Review + Fix-First" -> "Fixes applied?";84 "Fixes applied?" -> "Tests green?" [label="yes, cycle < 3"];85 "Fixes applied?" -> "Version, CHANGELOG, follow-ups, docs" [label="no"];86 "Version, CHANGELOG, follow-ups, docs" -> "Commit";87 "Commit" -> "Fresh run green?";88 "Fresh run green?" -> "Push + PR" [label="yes"];89 "Fresh run green?" -> "Tests green?" [label="no, triage"];90 "Push + PR" -> "Report PR URL";91}92```9394## Preamble9596Run this first, from the checkout you are shipping:9798```bash99# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.100_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"101if [ -f "$_LIB" ]; then102 . "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null103 _PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"104else105 # Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.106 _IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)107 _PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)108 _YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""109 [ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }110fi111cd "$_PROJECT_DIR" 2>/dev/null || true112_PROJECT_SLUG=$(basename "$_PROJECT_DIR") # display only113_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)114115_BRANCH=$(git branch --show-current 2>/dev/null); _BRANCH=${_BRANCH:-unknown}116echo "BRANCH: $_BRANCH"117echo "PROJECT_SLUG: $_PROJECT_SLUG"118echo "HAS_YTSTACK: $_HAS_YTSTACK"119echo "YTSTACK_SCOPE: $_YT_SCOPE"120echo "YT_DIR: $_YT_DIR"121echo "IS_GIT: $_IS_GIT"122123# Non-interactive detection124if [ -n "$YTSTACK_NON_INTERACTIVE" ] || [ -n "$OPENCLAW_SESSION" ] || [ -n "$CLAUDE_AGENT_TEAM_MEMBER" ]; then125 echo "YTSTACK_NON_INTERACTIVE: true"126else127 echo "YTSTACK_NON_INTERACTIVE: false"128fi129130# Active work + slice paper state: every task in the slice plan needs a non-draft summary.131_M=none; _S=none; _OPEN_TASKS=""; _SLICE_PLAN=none132if [ -n "$_YT_DIR" ] && [ -f "$_YT_DIR/STATE.md" ]; then133 _M=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1); _M=${_M:-none}134 _S=$(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1); _S=${_S:-none}135 echo "CURRENT_MILESTONE: $_M"136 echo "ACTIVE_SLICE: $_S"137 if [ -f "$_YT_DIR/$_M-$_S-PLAN.md" ]; then138 _SLICE_PLAN="$_YT_DIR/$_M-$_S-PLAN.md"139 for t in $(grep -oE '^- \[.\] T[0-9][0-9] --' "$_SLICE_PLAN" | grep -oE 'T[0-9][0-9]'); do140 f="$_YT_DIR/$_M-$_S-$t-SUMMARY.md"141 { [ ! -f "$f" ] || grep -q '^closed: draft' "$f"; } && _OPEN_TASKS="$_OPEN_TASKS $t"142 done143 fi144fi145echo "SLICE_PLAN: $_SLICE_PLAN"146echo "OPEN_TASKS: ${_OPEN_TASKS:-none}"147148# Hosting platform and base branch (PR target, else the repo default).149_REMOTE=$(git remote get-url origin 2>/dev/null || echo "")150_PLATFORM=unknown151case "$_REMOTE" in *github.com*) _PLATFORM=github ;; *gitlab*) _PLATFORM=gitlab ;; esac152_GH=no; command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && _GH=yes153[ "$_PLATFORM" = unknown ] && [ -n "$_REMOTE" ] && [ "$_GH" = yes ] && _PLATFORM=github154_BASE=""155if [ "$_PLATFORM" = github ] && [ "$_GH" = yes ]; then156 _BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || true)157 [ -n "$_BASE" ] || _BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || true)158fi159[ -n "$_BASE" ] || _BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')160[ -n "$_BASE" ] || { git rev-parse --verify -q origin/main >/dev/null 2>&1 && _BASE=main; }161[ -n "$_BASE" ] || { git rev-parse --verify -q origin/master >/dev/null 2>&1 && _BASE=master; }162_BASE=${_BASE:-main}163echo "REMOTE: ${_REMOTE:-none}"164echo "PLATFORM: $_PLATFORM"165echo "GH_AUTH: $_GH"166echo "BASE_BRANCH: $_BASE"167echo "ON_BASE: $([ "$_BRANCH" = "$_BASE" ] && echo yes || echo no)"168echo "DIRTY: $([ -n "$(git status --porcelain 2>/dev/null)" ] && echo yes || echo no)"169170# Version sources: current tree vs the (last fetched) base.171_rd() { if [ -n "$_REF" ]; then git show "$_REF:$1" 2>/dev/null; else cat "$1" 2>/dev/null; fi; }172_ver() { _REF="$1"; _v=$(_rd VERSION | head -1 | tr -d '[:space:]')173 for _j in package.json .claude-plugin/plugin.json .codex-plugin/plugin.json; do174 [ -n "$_v" ] || _v=$(_rd "$_j" | grep -m1 '"version"' | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')175 done176 for _t in pyproject.toml Cargo.toml; do177 [ -n "$_v" ] || _v=$(_rd "$_t" | grep -m1 -E '^version[[:space:]]*=' | sed -E 's/^version[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/')178 done179 echo "$_v"; }180_VS=""181for f in VERSION package.json .claude-plugin/plugin.json .codex-plugin/plugin.json pyproject.toml Cargo.toml; do182 [ -f "$f" ] && _VS="$_VS $f"183done184echo "VERSION_SOURCES:${_VS:- none}"185_CUR=$(_ver ""); echo "CURRENT_VERSION: ${_CUR:-none}"186_BV=""; git rev-parse --verify -q "origin/$_BASE" >/dev/null 2>&1 && _BV=$(_ver "origin/$_BASE")187echo "BASE_VERSION: ${_BV:-none}"188echo "LAST_TAG: $(git describe --tags --abbrev=0 2>/dev/null || echo none)"189echo "CHANGELOG: $([ -f CHANGELOG.md ] && echo CHANGELOG.md || echo none)"190echo "TODOS: $([ -f TODOS.md ] && echo TODOS.md || echo none)"191echo "TEST_DOC: $(grep -lE '^## Testing' CLAUDE.md AGENTS.md TESTING.md 2>/dev/null | tr '\n' ' ')"192```193194Flags read later: `OPEN_TASKS`, `SLICE_PLAN`, `BASE_BRANCH` (written `<base>` below), `PLATFORM`, `GH_AUTH`, `VERSION_SOURCES`, `CURRENT_VERSION`, `BASE_VERSION`, `CHANGELOG`, `TODOS`, `TEST_DOC`. Re-read `BASE_VERSION` after step 3's fetch when it said `none`.195196**Spawned sessions.** When `YTSTACK_NON_INTERACTIVE` is `true`, never call AskUserQuestion: take the `RECOMMENDATION` option and log one line, `[ytstack:ship] auto-picked <X> (<label>) because YTSTACK_NON_INTERACTIVE=true`. Choices that need a human (a loosened test gate, an unverifiable plan item, accepting a documentation risk) are never auto-accepted: they stay open and the PR is opened as a draft, or the ship stops where the step says so.197198**Routine work needs no confirmation:** including the branch's uncommitted changes, a PATCH or MICRO bump, the CHANGELOG draft, commit grouping, marking completed TODOs and AUTO-FIX review findings. Ask only where a step says so.199200## Procedure201202### 1. Run preamble203204Run the bash block above and keep its output; later steps refer to the flags by name.205206### 2. Preflight gates2072081. `IS_GIT` is `no`: stop with "not a git checkout".2092. `ON_BASE` is `yes`: stop with "You're on the base branch `<base>`. Ship from a feature branch."2103. `OPEN_TASKS` is not `none`: stop and name each task that still needs `ytstack:summarize-task`. A `closed: draft` stub is not a summary.2114. `PLATFORM` is not `github` or `GH_AUTH` is `no`: continue, and say once that step 15 will print the PR command to run by hand (GitLab: `glab` when it is installed).2125. `DIRTY` is `yes`: list the uncommitted and untracked files (`git status --porcelain`). They ship with this branch; do not ask. Name the `.ytstack/` files among them (task summaries, `STATE.md`, `DECISIONS.md` and `KNOWLEDGE.md` entries); they are part of the change and get committed in step 12. A file that clearly belongs to unrelated work (another task's edits in a shared tree) stays unstaged and is named in the final report.213214### 3. Merge the base branch (before tests)215216```bash217git fetch origin "<base>" && git merge --no-edit "origin/<base>"; echo "MERGE_EXIT: $?"218git log --oneline "origin/<base>..HEAD" | wc -l | sed 's/^ */COMMITS_AHEAD: /'219git diff --stat "origin/<base>" | tail -1220```221222A failed fetch: stop and report the error (no network, no access); nothing below runs on a stale base. Already up to date is fine. Never rebase.223224Simple conflicts resolve without asking: `VERSION` and manifest versions (take the higher base version; step 8 bumps from there), CHANGELOG ordering (keep both entries, base entries below the branch's), lockfiles (regenerate with the package manager). Anything else:225226> Merging `origin/{base}` into `{BRANCH}` ({PROJECT_SLUG}) conflicts in {N} files: {file: one-line nature of the conflict, each}.227>228> Simplify: the base branch changed the same lines this branch changed. Someone has to decide which version wins, line by line. I have a proposal for each file.229>230> RECOMMENDATION: Choose A because the proposals keep both changes where they are compatible, and you see each one before it is committed.231>232> A) Resolve as I propose: I show each file's resolution, then commit the merge233> Completeness: 10/10, effort: human: ~2 min / CC: ~5 min, tier: task234> B) You resolve them yourself; I stop here and you re-run ship afterwards235> Completeness: 10/10, effort: human: ~10 min / CC: 0, tier: task236> C) Abort the merge (`git merge --abort`) and stop237> Completeness: 3/10, effort: human: 0 / CC: 0, tier: task238239After a resolved merge, commit it (`git commit --no-edit`) and continue; the tests below run on the merged code.240241### 4. Run tests on the merged code2422431. Find the test command: `TEST_DOC` names the file with a `## Testing` section; read it. Not documented, or the project has no tests: read `${CLAUDE_SKILL_DIR}/references/tests.md` sections 1-2 and follow them (ask for the command, or decide about a missing suite).2442. Run the full suite. Run every applicable suite (unit, integration, shell tests), not just one. In a ytstack project also run each `## Verification` command of the active slice's task plans. Keep the output in a log file (`mktemp`), print the summary lines.2453. Read each result as pass, zero-run or count-unavailable (`references/tests.md` section 3). A zero-run is a failure.2464. Any failure: read `${CLAUDE_SKILL_DIR}/references/tests.md` section 4 and triage. In-branch failures stop the ship.2475. Prompt or eval files changed: `references/tests.md` section 5.2486. Print one line per suite: `Tests: <label> <N> passed` or `count unavailable`. Remember the commands; step 13 reruns exactly these.249250### 5. Coverage audit251252Read `${CLAUDE_SKILL_DIR}/references/test-coverage.md` and execute it: dispatch the audit subagent, process its result, apply the coverage gate. Keep the diagram, counts and gate result for the PR body. Tests it generates stay uncommitted until step 12.253254### 6. Plan completion, plan verification, scope drift255256Read `${CLAUDE_SKILL_DIR}/references/plan-completion.md` and execute it in order: bind the plan (in a ytstack project the slice plan `SLICE_PLAN` plus its task plans and summaries), dispatch the audit, apply the gates, run the plan's verification checks, write the scope check. Deferrals approved here go to step 10.257258### 7. Pre-landing review259260Read `${CLAUDE_SKILL_DIR}/references/review-checklist.md` and execute it: PR type, Pass 1 (CRITICAL) and Pass 2 (INFORMATIONAL) over the merge-base diff, the sideways sweep on every finding, the adversarial subagent for diffs of 200+ changed lines, then Fix-First. Gate-integrity hunks that step 5 flagged join Pass 1.261262Fixes applied: commit them, rerun step 4, and review the new range again. At most 3 fix cycles; on the third, stop and name the remaining blockers to the user unfixed. A clean pass continues to step 8.263264For a task-level two-stage review with the superpowers receiving discipline, `ytstack:code-review` exists; ship does not invoke it, its own review covers the whole branch diff.265266### 8. Version bump267268Skip the whole step when `VERSION_SOURCES` is `none`: print `Version bump: skipped (no version source)`; step 9 writes under `## [Unreleased]`, step 15 uses an unprefixed title. Never create a VERSION file.269270The project's own release rules win: read `CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING.md` for a release or versioning section (which files carry the version, 3 or 4 components, who bumps) and follow it over the defaults below.2712721. **Classify.**273 - **ALREADY_BUMPED:** `CURRENT_VERSION` is higher than `BASE_VERSION`. Keep it; never bump twice. Derive the level from the first component that changed.274 - **FRESH:** `CURRENT_VERSION` equals `BASE_VERSION` (or the base has no version yet).275 - **DRIFT:** the version sources disagree with each other (`grep -n '"version"\|^version' <each source>`). When exactly one source still holds `BASE_VERSION` and the others agree on a higher one, set the stale one to match and continue as ALREADY_BUMPED. Any other disagreement: stop and show the values; the user reconciles them.2762. **Pick the level** from the diff (FRESH only):277 - **MICRO** (4-component versions only): under 50 changed lines, trivial tweak or config. With 3 components this is PATCH.278 - **PATCH:** 50+ lines, no feature signal.279 - **MINOR:** any feature signal (new command, route, page, skill, migration, module) or 500+ lines. Ask.280 - **MAJOR:** breaking change or a milestone release. Ask.281282> Shipping `{BRANCH}` of `{PROJECT_SLUG}` (currently v{CURRENT_VERSION}). The diff {has a feature signal: {signal} | breaks {what}}, which suggests a {MINOR|MAJOR} bump to v{proposed}.283>284> Simplify: the version number tells users what to expect. A minor bump says "new things, nothing breaks"; a major bump says "you may have to change something"; a patch says "fixes only".285>286> RECOMMENDATION: Choose A because {the signal} is {a new capability users can use | a change existing users must adapt to}.287>288> A) {MINOR|MAJOR} bump to v{proposed}289> Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task290> B) One level smaller: v{smaller}291> Completeness: 7/10, effort: human: 0 / CC: ~1 min, tier: task292> C) Cancel the ship before any release write293> Completeness: 10/10, effort: human: 0 / CC: 0, tier: task2942953. **Check for collisions** (FRESH and ALREADY_BUMPED): `git tag -l "v<NEW_VERSION>"` must be empty. With `GH_AUTH: yes`, `gh pr list --state open --json number,title,headRefName` and look for another branch whose title claims `v<NEW_VERSION>` or higher at the same level. A sibling holds it: advance past the highest claimed version and say so; for ALREADY_BUMPED, ask before changing an existing version.2964. **Write** (FRESH, or an approved re-bump) with Edit, one file at a time: `VERSION` (keep its component count), `package.json` `"version"`, `.claude-plugin/plugin.json` / `.codex-plugin/plugin.json` `"version"`, `pyproject.toml` `version =` under `[project]` or `[tool.poetry]`, `Cargo.toml` `version =` under `[package]`, and the root package version in `package-lock.json` (top-level `version` and `packages[""].version`). Then `grep -rn "<old version>"` over the manifests and README badges the project keeps in sync (its release rules name them) and update those. Do not create a git tag.2975. Print `Version: v<BASE_VERSION> -> v<NEW_VERSION> (<level>)`.298299### 9. CHANGELOG300301`CHANGELOG` is `none`: print `CHANGELOG: skipped (none at CHANGELOG.md)` and write nothing; the PR body carries the release notes. Never create the file.3023031. Read the CHANGELOG header and the latest entry to learn its format (heading style, date format, sections).3042. List every commit on the branch: `git log origin/<base>..HEAD --oneline`. Count them; this is the checklist.3053. Read `git diff origin/<base>` to understand what each commit changed.3064. Group by theme before writing: features, performance, fixes, removals, infrastructure and tests, refactors.3075. Write one entry with Edit (never Write on CHANGELOG.md), after the header and before the first release entry, dated today: `## [<NEW_VERSION>] - YYYY-MM-DD` (or the file's own heading style), with `### Added` / `### Changed` / `### Fixed` / `### Removed` as applicable. Entries this branch already added for these commits are replaced by the one unified entry. FRESH and ALREADY_BUMPED both have a release version: the heading is `NEW_VERSION` (for ALREADY_BUMPED that is the version the branch already carries). Only when there is no release version (no version source, or the project's release rules leave the bump to someone else so `NEW_VERSION` equals `BASE_VERSION`) does the entry go under `## [Unreleased]`, never under an already released heading.3086. **Voice:** lead with what the user can now do that they could not before. Plain language, no implementation detail, nothing about internal tracking (TODOS, `.ytstack` bookkeeping): no tracker codes (issue keys, `M###-S##` refs) anywhere in the entry, and a bold lead that a user of the project understands without the repository's coined terms. Each bullet names a concrete change; cut any bullet that would fit every release.3097. **Cross-check** against the commit list from item 2: every user-facing change appears. Merges, version bumps and fixes to work introduced earlier on this same branch need no bullet.310311Do not ask the user to describe the changes; infer them from the diff and the commits.312313### 10. Follow-ups (TODOS.md)314315`TODOS` is `none`: do not create the file. Approved deferrals (step 6 NOT DONE items, step 4 pre-existing failures recorded as follow-ups, review findings deferred in step 7) go into the PR body's `## Follow-ups`; in a ytstack project, also name them in the final report for `ytstack:reassess-roadmap`.316317`TODOS` is `TODOS.md`:3183191. Add each approved deferral as an item under its component heading, priority-sorted:320 ```markdown321 ### <Title>322 **What:** one line. **Why:** the concrete problem. **Context:** enough to start in three months.323 **Effort:** S / M / L / XL **Priority:** P0-P4 **Depends on:** <or None>324 ```325 Plan deferrals are P1 with `Deferred from plan: <path>`; pre-existing test failures are P0 with the error output and the branch. Reuse a matching existing item instead of duplicating. Never invent unapproved follow-ups.3262. Detect completed items: compare titles, files and behaviour with `git diff origin/<base>` and `git log origin/<base>..HEAD --oneline`. Move proven completions to `## Completed` with `**Completed:** v<NEW_VERSION> (YYYY-MM-DD)`; leave uncertain ones open.3273. Report additions, completions and the remaining count. A failed write is a warning, not a blocker; carry the unsaved items into the PR body and never claim they were saved.328329### 11. Documentation sync330331Read `${CLAUDE_SKILL_DIR}/references/documentation-sync.md` and execute it on every ship: dispatch the doc-audit subagent, validate exactly what it changed, recover or ask when it is blocked. Keep `documentation_section` and the status line for the PR body.332333### 12. Commit (bisectable chunks)334335Already committed and nothing new: continue to step 13. Never create an empty commit. Check the branch first: `git branch --show-current` must print `BRANCH`.3363371. Group changes into logical commits: each source change with its tests; config and routes with what uses them; migrations may stand alone; docs from step 11 with the change they describe or as one `docs:` commit. Under 50 lines across fewer than 4 files may be one commit.3382. Order dependencies first (infrastructure, then models and services, then controllers and views). Each commit must work on its own: no broken imports, no missing code.3393. Stage by name (`git add <paths>`), never `git add -A` or `git add .`. Message `<type>: <summary>` (`feat`, `fix`, `chore`, `refactor`, `docs`, `test`) with a short body, or the project's convention (in a ytstack project, code that belongs to a task keeps its `M###-S##-T##:` prefix). A fix for an issue the user named adds `Fixes #<n>`. Add the session's commit attribution trailer when the host defines one.3404. `.ytstack/` files that are part of the change (summaries, `STATE.md`, decision and knowledge entries) are committed, as `chore: update ytstack state for <M###-S##>` when they do not belong to a code commit.3415. Last: the release metadata in one commit: `VERSION`, manifests, lockfile version, `CHANGELOG.md`, `TODOS.md`, as `chore: release v<NEW_VERSION>` (or the project's release-commit convention).342343Commit signing and hooks run as configured. A failed hook or signature is a blocker to report and fix at the cause, never to bypass.344345### 13. Verification gate346347**IRON LAW: no completion claim without fresh verification evidence.**3483491. `git status --porcelain` must be empty except files you deliberately left out in step 2 (name them). Anything else: commit it per step 12 or stop.3502. Rerun every suite from step 4 (same commands) on the committed tree whenever anything changed since that run: review fixes, generated tests, merged base, doc edits, the version bump. Only when literally nothing changed since a green run may you cite that run (command, result, time).3513. Run the project's declared build when it has one (`build` script in package.json, `make build`, the build step in CI) and its lint or check command when CI runs it (for ytstack itself: `bin/ytstack-check`). A missing prerequisite or failed build stops the ship: report the command and the error; never substitute another command.3524. Any failure: back to step 4's triage; nothing is pushed red.3535. Paste the evidence: per suite the command, exit code and pass count (or `count unavailable`), and the build result. This is what the PR's `## Test plan` cites.354355### 14. Push3563571. **Secret scan** of the added lines:358 ```bash359 git diff "origin/<base>...HEAD" | grep -nE '^\+.*(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|xox[abpors]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_-]{35})' && echo "SECRET_HIT" || echo "SECRET_CLEAN"360 ```361 `SECRET_HIT`: STOP. Show the file and line (not the secret). Remove it from the code and the branch history before anything is pushed; a pushed credential must be rotated. Test fixtures with obviously fake values are fine once you have read them.3622. **Already pushed?**363 ```bash364 _L=$(git rev-parse HEAD); _R=$(git ls-remote --heads origin "refs/heads/<branch>" | cut -f1)365 [ "$_L" = "$_R" ] && echo "PUSH: ALREADY_PUSHED" || echo "PUSH: NEEDED (remote ${_R:-none})"366 ```367 A failed lookup: stop and report. `ALREADY_PUSHED`: go to step 15.3683. `git push -u origin "<branch>"`.3694. **Push fails:** stop, no PR claim. Non-fast-forward: `git fetch origin "<branch>"`, merge it (step 3's conflict rules), rerun steps 4 and 13, push again. Authentication, hook or network failure: report the error and fix the cause; never force-push, never `--no-verify`.370371### 15. Pull request and report372373Read `${CLAUDE_SKILL_DIR}/references/pr-body.md` and execute it: look up the open PR, prepare the title, compose the body (in a ytstack project with the `## Slice` section built from the slice goal and each task's Outcome paragraph), secret-check it, create or update the PR, print the URL. A draft PR when a loosened gate is left open or a plan item stays unverified.374375Then report, in this shape:376377```378SHIP: <PR URL | pushed, PR not created: <reason>>379Version: v<old> -> v<new> (<level>) | skipped380Tests: <label> <N> passed[, ...] | Build: <ok | none declared>381Coverage: <X>% value-weighted, gate <PASS | accepted risk | skipped>382Plan: <N/M done | not run> | Review: <summary line> | Docs: <updated | current | blocked>383Follow-ups: <count, where they are recorded>384```385386## Terminal State387388The terminal state is one of:389390- Returning control to the user with the PR URL (or the pushed branch and the manual PR command when the PR could not be created), plus one next-step suggestion: `ytstack:reassess-roadmap` when the slice is complete, `ytstack:retro` when the milestone is complete, `ytstack:document-release` when a version is to be cut or the docs need a full post-ship pass.391- Exiting without a push (a gate stopped the ship: open tasks, on the base branch, in-branch test failures, a NOT DONE plan item the user chose to finish, a secret hit, a cancelled version bump, a blocked documentation audit). Name the gate and what clears it.392393Do NOT auto-invoke any downstream skill, and do NOT merge the PR, enable auto-merge or delete the branch. The ONLY skills you may invoke after this one are the ones the user explicitly asks for; `ytstack:reassess-roadmap`, `ytstack:retro`, `ytstack:document-release`, `ytstack:systematic-debugging` and `ytstack:finish-branch` are suggestions to name, not to run.