Issue-driven development orchestrator. Turns improvement intent into a well-specified, bilingual issue set; clusters issues into milestones that map 1:1 to semver versions; enforces branch, commit, and PR conventions (GitHub Flow โ `<type>/<issue-N>-<slug>`, Conventional Commits, mandatory PR template, rebase-first merge); generates changelog entries and release notes deterministically from closed issues; leaves a durable audit trail for the next AI session. Direct-call only โ not part of the /vibesubin parallel sweep. Two tracks โ **GitHub track** (default) on GitHub with authenticated `gh` CLI; **PRD track** on any other host, using local markdown files under `docs/release-cycle/vX.Y.Z/` as the durable audit trail. Operator picks at Step 1.5. Every external mutation follows preview โ confirm โ mutate; created resources carry idempotency markers so re-runs noop instead of duplicating.
Instalar con Codex o Claude Copia este prompt, pรฉgalo en Codex, Claude u otro asistente, y deja que revise la pรกgina de la skill y la instale por ti.
Un comando directo omite el prompt de revisiรณn. Revisa el origen antes de ejecutarlo.
Instrucciones de origen ยท Vista previa de solo lectura
name
ship-cycle
description
Issue-driven development orchestrator. Turns improvement intent into a well-specified, bilingual issue set; clusters issues into milestones that map 1:1 to semver versions; enforces branch, commit, and PR conventions (GitHub Flow โ `<type>/<issue-N>-<slug>`, Conventional Commits, mandatory PR template, rebase-first merge); generates changelog entries and release notes deterministically from closed issues; leaves a durable audit trail for the next AI session. Direct-call only โ not part of the /vibesubin parallel sweep. Two tracks โ **GitHub track** (default) on GitHub with authenticated `gh` CLI; **PRD track** on any other host, using local markdown files under `docs/release-cycle/vX.Y.Z/` as the durable audit trail. Operator picks at Step 1.5. Every external mutation follows preview โ confirm โ mutate; created resources carry idempotency markers so re-runs noop instead of duplicating.
mutates
["direct","external"]
when_to_use
Trigger on "plan a release", "๋ฆด๋ฆฌ์ฆ ๊ณํ", "cut a release", "๋ฆด๋ฆฌ์ฆ ํ์", "์ด์๋ก ๋จ๊ธฐ๊ณ ์ฒ๋ฆฌ", "make issues for this", "bundle these findings into issues", "turn sweep findings into issues", "issue-driven", "์ด์ ๋๋ฆฌ๋ธ", "roadmap for 0.N.0", "ship cycle", "tag and release", "release notes ์จ์ค", "generate changelog from PRs", "์ฌ๋ฌ ์์ ์ ๋ฌถ์ด์ ๋ฆด๋ฆฌ์ฆ".
Turns improvement intent into shipped versions, deterministically: intent โ issues โ milestones = versions โ tagged release. Direct-call only. Given a backlog (pasted notes, a /vibesubin sweep report, or a named scope), this skill writes a well-specified bilingual issue set, clusters items into semver milestones, dispatches the implementation to the correct vibesubin specialist, and โ when a milestone closes โ runs the full release pipeline end-to-end: changelog aggregation, manifest bump, annotated tag, GitHub release, audit trail. No interpretation, no flourish โ the milestone state is the release state.
Actual code changes โ the fix itself is always another skill's job (refactor-verify, audit-security, etc.).
Release-note prose โ write-for-ai writes the user-facing narrative when the operator wants polish; this skill produces the functional-only scaffold.
CI wiring โ setup-ci owns workflow files.
Not a replacement for:
write-for-ai โ owns commit-message and PR-body style. This skill enforces when commits happen (Closes #N footer on each) and which PRs block a release, but not the prose inside them.
project-conventions โ owns branch-strategy defaults. This skill suggests issue-<N>-<slug> branch names, but defers to an existing project convention when one exists.
Host check and track selection
ship-cycle runs in one of two tracks. Both follow the same 11-step methodology and the same conventions (see references/pr-branch-conventions.md); they differ only in where the audit trail lives.
GitHub track (default) โ GitHub repo with authenticated gh CLI. Issues, milestones, PRs, and releases live on GitHub. The footer auto-closes issues at merge.
Closes #<N>
PRD track โ any other host (GitLab, Gitea, Forgejo, Bitbucket, self-hosted, plain git with no remote, or gh unauthenticated). Issues are markdown files under docs/release-cycle/vX.Y.Z/issues/NNN-slug.md; release artifacts live in the same directory. See references/prd-track.md for the full step-by-step mapping.
Detection at Step 1:
gh repo view --json name >/dev/null 2>&1 && HAS_GH_REPO=1 || HAS_GH_REPO=0
gh auth status >/dev/null 2>&1 && HAS_GH_AUTH=1 || HAS_GH_AUTH=0
If both are 1 โ default to GitHub track. If either is 0 โ default to PRD track. Step 1.5 surfaces the detection and lets the operator override.
State assumptions โ before acting
Before proceeding past Step 2, write an explicit Assumptions block to the session and ask the operator to confirm. A wrong assumption here silently corrupts every downstream step.
## Assumptions
- Track: <GitHub | PRD (local)>
- Repo state: <clean | dirty (N staged, M unstaged) | detached HEAD>
- Default branch: <main | master | dev>
- Current version: <from manifests โ path and value โ or "pre-1.0 / no manifests, using latest tag">
- Work scope: <pasted findings | sweep output at /tmp/... | user-named area "perf in src/api/">
- Issue language: <Korean | English | Japanese | Chinese>
- Milestone target: <new version to cut โ vX.Y.Z | just-issues mode, no release this cycle>
- Branch convention: <default: <type>/<issue-N>-<slug> per pr-branch-conventions.md โ or detected existing convention (e.g., "feature/<topic>") if CONTRIBUTING.md / CLAUDE.md / last 20 branches show one. For non-GitHub-Flow models (GitFlow, Trunk-based with release branches), see references/branch-models.md for ship-cycle's deferral behavior.>
- Merge strategy: <squash (default) | rebase | merge โ detected from repo settings + CONTRIBUTING.md>
Stop and ask when:
Scope is ambiguous ("clean up" with no target).
Language signal is missing โ prompt returned by the operator has no dominant language and no direct answer to the language question.
Working tree is dirty with a staged-plus-unstaged mix (unclear which changes the cycle is building on).
Current version can't be determined (no manifests, no tags) โ operator must state a starting version.
Never invent assumptions to keep moving. An invented default branch or an invented current version is worse than a blocked step.
Mutation contract โ preview, confirm, mutate
ship-cycle mutates external state (gh issue create, gh api ... -X PATCH, gh release create, git tag -a, git push). Every such call follows the same three-step contract:
Preview โ print the exact command and the rendered BODY content. No execution yet.
Confirm โ block on operator response. Accept approve / proceed / yes to advance; anything else (including silence) holds.
Mutate โ execute the command, capture its output (issue number, release URL, tag SHA), record the captured value in the audit trail.
Created resources carry an idempotency marker so re-runs detect prior runs and noop instead of duplicating:
Issue bodies and release notes contain <!-- ship-cycle:vX.Y.Z --> near the top.
Branch names follow the deterministic shape <type>/issue-<N>-<slug> from references/pr-branch-conventions.md ยง1 โ re-creating the same branch is a noop.
Milestone titles are vX.Y.Z exactly; reusing a title fetches the existing milestone instead of creating a duplicate.
dry-run mode (operator says dry-run at Step 7 or sets it via Step 1.5 override) skips every Mutate step and prints the would-be commands. Useful for sanity-check before a real run.
Rollback. Every external mutation has an inverse:
Mutation
Inverse
gh issue create
gh issue close <N> --comment "rolled back โ see <reason>"
gh api repos/.../milestones (create)
gh api repos/.../milestones/<N> -X PATCH -f state=closed
gh release create vX.Y.Z
gh release delete vX.Y.Z --yes (only if not yet announced; otherwise cut a follow-up patch)
git tag -a vX.Y.Z + push
git push --delete origin vX.Y.Z then git tag -d vX.Y.Z (rare; usually cut a follow-up patch instead)
Branch + PR
gh pr close <PR> --delete-branch
Never rewrite a published tag or release. If a release shipped with a mistake, cut a patch (vX.Y.Z+1) and edit the broken release's notes only to add a "Known issue โ use vX.Y.Z+1" banner.
Procedure โ 11 steps
Run in order. Each step has a verification or a confirm-gate. Do not skip.
Step 0.5 โ Offer upstream review
If the operator's intake at Step 4 will already include a concrete findings list (pasted sweep report, codex-fix output, PR review, scanner output, explicit named scope with evidence), skip this step with a one-liner โ "Findings already provided, skipping upstream review offer." โ and move on.
Otherwise, before running the host check, offer three paths and block until the operator picks one:
(a) Invoke /vibesubin for a parallel sweep and wait for its report; consume it as Step 4(a) input.
(b) Invoke a targeted worker if the operator named a specific concern โ /audit-security for a security focus, /fight-repo-rot for dead code or god files, /refactor-verify baseline snapshot for "is the repo green?". Consume the worker's output as Step 4(a) input.
(c) Proceed with operator-pasted findings as-is โ even rough notes are acceptable if the operator owns the scope.
Explicitly: ship-cycle does not run the review itself. It orchestrates around review output. If the operator picks (a) or (b), surface the exact invocation and wait; do not auto-invoke. If the operator picks (c) without evidence, Step 4's evidence-check will catch gaps and block.
Step 1 โ Host check
Run the two gh checks from the Host-check section above. On success, capture:
On failure (not a GitHub repo, or gh unauthenticated), do NOT stop. Fall through to Step 1.5 โ the PRD track is the fallback path, not an exit.
Step 1.5 โ Track selection
Surface the detected track and let the operator confirm or override:
## Track
Detected: <GitHub | PRD (local)>
Reason: <gh repo + gh auth both OK | gh repo missing | gh unauthenticated | non-GitHub remote: <URL>>
Proceed on this track? (yes / switch to <other>)
Default is the detected track. Accept the operator's override โ an operator on a GitHub repo may still prefer the PRD track for a local-first audit trail, and vice versa. Wait for confirmation before Step 2.
On the PRD track, the rest of this SKILL.md applies with the step-by-step mapping at references/prd-track.md โ read it alongside the main procedure. The conventions at references/pr-branch-conventions.md apply to both tracks.
Step 2 โ State assumptions
Populate the Assumptions block above. Detect each value:
git status --porcelain | head
git rev-parse --abbrev-ref HEAD
git describe --tags --abbrev=0 2>/dev/null || echo "no-tags"
test -f package.json && cat package.json | grep '"version"' | head -1
test -f Cargo.toml && cat Cargo.toml | grep '^version' | head -1
test -f pyproject.toml && cat pyproject.toml | grep '^version' | head -1
test -f .claude-plugin/marketplace.json && cat .claude-plugin/marketplace.json | grep '"version"' | head -1
Surface the block. Wait for operator confirmation. Stop-and-ask conditions above apply.
Step 3 โ Language elicitation
If the operator's prompt is unambiguously in one language, use it. Otherwise ask:
"Issue language: ํ๊ตญ์ด / English / ๆฅๆฌ่ช / ไธญๆ?"
Chosen language is the issue body's primary language. Section headings and checkboxes stay in English for gh parsing stability (see references/issue-body-template.md). English mirror is optional โ default off, enable only on explicit request.
Step 4 โ Intake
Three input paths:
(a) Pasted improvement list โ operator pastes items as prose, a checklist, or a scanner report. Parse into a flat candidate list.
(b) Hand off to /vibesubin first โ if the operator says "sweep first, then issues", surface the instruction to invoke /vibesubin and wait for the sweep report. Consume the report as path (a) once it arrives. Do not auto-invoke the sweep โ that is the operator's call.
(c) Named scope โ operator says "perf in src/api/". Grep, git log --since, or targeted Read to enumerate candidate items within that scope. Surface the enumeration for confirmation before converting to issues.
Normalize every source into a flat candidate-item list: [{summary, evidence, suggested_type, suggested_priority, suggested_area}]. Evidence is concrete (file:line, metric, grep count, log excerpt) โ if an item has no evidence, flag it and ask for one before drafting the issue.
Step 5 โ Draft candidate issues
For each candidate item, fill the template at references/issue-body-template.md. Body sections: Problem / Acceptance criteria / Implementation notes (with skill hand-off) / Linked. Title <72 chars, imperative, domain-prefixed. Labels: one type, one priority, one area.
Body goes in the language chosen at Step 3. Section headings and checkbox markers stay in English โ load-bearing for cross-session tooling.
Do NOT gh issue create yet. Drafts stay in the session until Step 7 is confirmed.
Mandatory acceptance-criteria fields for every issue (enforced by the issue-body template at references/issue-body-template.md):
A concrete test plan scoped to the issue's label. Bug โ regression test that reproduces the failure and then passes. Feat โ new test or fixture covering the added behavior. Refactor โ before/after equivalence (AST-diff or grep-count assertion). Docs/chore โ validate_skills.py + grep assertions that the doc changed as stated.
A concrete docs plan naming every file that must update in the same PR: CHANGELOG.md section entry, README table row or section edit, SKILL.md edit, CLAUDE.md change-type matrix entry โ whichever apply. Docs updates land in the SAME PR as the code fix, not in a follow-up.
A handoff-notes block at the bottom listing (a) what the next AI session needs to know to pick up adjacent work, (b) already-done-at references so a future session does not duplicate this work.
If a candidate issue is missing any of these three fields after drafting, block Step 6 (cluster) and report the gap for operator input.
Step 5.5 โ Write PRD.md
Before clustering, aggregate the candidate-issue set into a single PRD.md at the repo root (default) or at /tmp/<repo>-prd-vX.Y.Z.md if the operator prefers a non-committed draft. The PRD provides the theme-level view that individual issues cannot โ why these N issues matter, what success looks like, what is deferred.
Follow the template at references/prd-template.md. Sections produced:
Context โ the trigger (sweep, review, named scope), the state of the repo, the cycle window.
๋ถ๊ทน์ฑ ๋ชฉํ / North-star goals โ 1โ3 sentences naming the outcome the cycle exists to produce.
Themes โ each theme groups related issues under a shared objective (e.g., "Fix auth regressions", "Harden CI").
Success metrics โ observable signals that tell the operator the cycle succeeded (tests green, N issues closed, CHANGELOG entries dated, release tag live).
Issue cluster summary โ flat list of issue titles with labels and milestone target.
Deferred items โ candidate items explicitly pushed to a later cycle, with one-line reasons.
PRD is operator-facing โ surface it for approval before Step 6 clustering runs. If the operator requests edits, revise and re-surface; do not proceed to Step 6 until the PRD is approved.
If the cycle is a 1-milestone patch with fewer than 5 issues, the PRD may be inlined in the Step 7 approval prompt instead of a file โ operator's choice. Default to file for minor and major cycles; default to inline for patch cycles unless the operator asks otherwise.
Step 6 โ Classify into milestones
Apply the semver decision tree in references/milestone-rules.md:
feat (additive) / new skill / new endpoint / new config with default โ minor
breaking / removed API / renamed exported symbol โ major
Cluster heuristics: related items stay together; same-module items stay together; security-critical items get a dedicated milestone and cut immediately. Do not mix breaking + additive in one milestone โ split into major + follow-up minor (see worked example 3 in milestone-rules.md).
Every milestone has a title vX.Y.Z matching the manifest version convention of the repo.
Step 7 โ Confirm plan
Surface the plan as a table and block until the operator replies approve / merge / split / edit.
| Milestone | Version | Issues | Est size | Type |
|-----------|----------|-------------------------|----------|-------|
| v0.4.1 | patch | 3 bugs in src/api/ | small | patch |
| v0.5.0 | minor | 1 new skill + 2 docs | medium | minor |
| v1.0.0 | major | 1 rename (breaking) | small | major |
approve โ Step 8. merge / split / edit โ revise and re-present. Do not proceed to Step 8 until the operator explicitly approves.
Step 8 โ Create issues
Create milestones first, then issues. Capture gh output to record real issue numbers โ never invent them.
# 1. Create each milestone (idempotent โ reuse if title already exists)
gh api repos/"$REPO"/milestones -f title="vX.Y.Z" -f description="..." 2>/dev/null \
|| gh api repos/"$REPO"/milestones --jq '.[] | select(.title=="vX.Y.Z") | .number'
# 2. For each drafted issue, write body to a temp file and create
BODY=/tmp/ship-cycle-issue-<slug>.md
cat > "$BODY" <<'EOF'
<rendered body from Step 5>
EOF
gh issue create \
--title "<title>" \
--body-file "$BODY" \
--label "<type>,<priority>,<area>" \
--milestone "vX.Y.Z"
# โ capture stdout: https://github.com/owner/repo/issues/<N>
Dry-run mode: if the operator requested dry-run, print the commands and BODY contents without executing. Skip to Step 11 and report.
Step 9 โ Branch + execute
For each created issue, derive the branch name per references/pr-branch-conventions.md ยง1 and hand off to the right worker. Default shape:
<type> matches the issue's primary type label (feat, fix, refactor, perf, docs, chore, security, test, ci, design). If the repo has a detected existing convention per ยง1's detection rule (โฅ10 of last 20 branches matching, or explicit CONTRIBUTING.md / CLAUDE.md rule), defer to that convention and still embed the issue number.
Routing by label (hand-off, not invocation โ ship-cycle does not execute code changes):
Label
Hand-off skill
bug, refactor
/refactor-verify
perf
/refactor-verify (perf focus)
security
/audit-security
docs
/write-for-ai
chore + ci
/setup-ci
chore + secrets
/manage-secrets-env
chore + deps
/project-conventions
design, ui
/unify-design
chore + assets
/manage-assets
chore + dead-code
/fight-repo-rot โ /refactor-verify
Commit format: Conventional Commits + mandatory Closes #<N> footer per references/pr-branch-conventions.md ยง2. PR body: the six-section template (Context / What changed / Test plan / Docs plan / Risk / Handoff notes) per ยง3, with Closes #<N> as the first line. These are load-bearing for GitHub's auto-close, for Step 10's aggregation query, and for the Step 11 audit trail.
Rebase and conflict handling follow ยง5 โ rebase-first workflow, --force-with-lease only (never plain --force), no force-push to main / master / release/*. Merge strategy per ยง4 (repo settings first, CONTRIBUTING.md second, --squash default).
When the worker reports done and the PR merges, GitHub auto-closes the issue (GitHub track) or ship-cycle updates the issue file's frontmatter (PRD track โ see references/prd-track.md). If the worker cannot complete the item (baseline-red, missing context), leave the issue open and tag it blocked with a reason in a comment (or PRD-track frontmatter edit).
Step 9a โ Parallel dispatch for independent issues
When multiple issues in a milestone have no cross-file overlap โ derived from each issue body's Implementation notes โ scope files list โ dispatch them simultaneously as parallel Task-tool subagents. Sequential only when issues share files or one depends on another's output.
Default model: opus (per the project's global CLAUDE.md rule "All custom agents default to opus"). Override per-agent with model: sonnet or model: haiku only when the operator explicitly asks for cost/speed.
Default effort: max, unless the operator has specified otherwise.
Parallel ceiling: the orchestrator can dispatch 10+ independent issue workers simultaneously when the dependency graph is flat. Pattern to copy: the /vibesubin sweep launches 9 parallel specialists in one block โ same shape here for issue execution.
Ownership per worker: each parallel worker owns its branch, its commit, and its gh pr create. No cross-worker coordination until merge-time.
If two issues touch the same file, serialize them and note the dependency in the second issue's body under Depends on.
Step 9b โ CI green gate before merge
Per references/pr-branch-conventions.md ยง7: all checks must be SUCCESS or NEUTRAL โ including optional ones. SKIPPED is yellow, not green; surface and confirm before merge. Flaky checks get one re-run; second failure blocks merge.
PRD-track equivalent: run the project's documented test command (from package.json / Cargo.toml / pyproject.toml / Makefile); exit 0 = green. Do not merge without green on either track.
Step 10 โ Release when milestone closes
Follow references/release-pipeline.md. Short version โ 10 commands, in order:
Preflight โ milestone has zero open issues and zero open PRs; CI is green on the default branch; validator (if any) passes.
Aggregate โ gh issue list --milestone vX.Y.Z --state closed --json number,title,labels โ one CHANGELOG bullet per issue, functional-only style, grouped Added / Changed / Fixed / Removed / Security. CHANGELOG bullet style (functional-only, observable changes only, no narrative or meta-rationale) follows write-for-ai's Change log doc type โ this skill owns the aggregation mechanics (semver bucketing, issue-to-bullet mapping, group classification), not the style rules themselves. If the operator asks for release-note prose polish (TL;DR phrasing, migration tables, feature-highlight narrative), hand off to write-for-ai for the notes file while ship-cycle continues with the tag/release mechanics.
Move [Unreleased] entries under a new [X.Y.Z] โ YYYY-MM-DD heading.
Bump every manifest โ package.json / Cargo.toml / pyproject.toml / .claude-plugin/marketplace.json + plugins/*/plugin.json โ all in one commit.
Run tests and validator โ halt on red.
Commit โ chore(release): vX.Y.Z.
Push the commit and wait for CI green.
Tag โ git tag -a vX.Y.Z -m "<one-line summary>", then git push origin vX.Y.Z. Annotated, not lightweight.
Release notes to a temp file โ TL;DR, breaking (only if any), new features, fixes, under-the-hood, link to CHANGELOG.md.
Do not commit the release-notes temp file. CHANGELOG is the in-repo source of truth; the notes file is the GitHub-only extract.
Step 11 โ Audit trail
For every closed issue in the milestone:
gh issue comment <N> --body "Shipped in vX.Y.Z โ <release URL>. Resolved by #<PR-number>."
Close the milestone if it is still open:
MILESTONE_ID=$(gh api repos/"$REPO"/milestones --jq '.[] | select(.title=="vX.Y.Z") | .number')
gh api repos/"$REPO"/milestones/$MILESTONE_ID -X PATCH -f state=closed
Verify CHANGELOG.md has the dated heading. Link the release back to the milestone in the release notes' footer.
When closing an issue (post-merge), copy its handoff-notes block from the issue body into the close comment. A fresh AI session grepping closed issues for context can then find the handoff notes without re-reading the PR diff โ the comment becomes the durable reference.
Report done.
Sweep mode โ ship-cycle is not in the sweep
/vibesubin does not launch this skill in its parallel sweep. ship-cycle mutates โ it creates issues, suggests branches, commits release prep, pushes tags, publishes GitHub releases. That breaks the sweep's read-only invariant and its portable-engine invariant (it requires gh CLI + GitHub). If a sweep-style request arrives ("sweep and then turn findings into issues"), the operator invokes /vibesubin first, reviews the sweep report, then calls /ship-cycle separately with the approved findings as Step 4(a) input.
Documented here explicitly so a future maintainer does not add a sweep=read-only branch by mistake. Its absence is deliberate โ this is a process-category skill (see docs/PHILOSOPHY.md rule 10), and process skills are direct-call only by that rule. Same read-only-invariant logic keeps host-specific wrappers like codex-fix out of the sweep (rule 9) for a different reason: wrappers write files and invoke external tools. Both rules converge on the same exclusion โ process and wrapper skills stay out of /vibesubin.
Harsh mode โ no hedging
When the task context contains tone=harsh (from /vibesubin harsh or direct phrasing like "don't sugarcoat" / "๋งค์ด ๋ง" / "ๅณใใ"), switch output rules on every step:
Issue bodies: direct subject-verb โ "Fix the N+1 query in /api/users", not "Consider refactoring the user query for better performance". No "you could", no "we might want to".
Milestone classification: do not pad a patch version with nice-to-haves to look busy. If three items match and five were proposed, the milestone has three.
Release notes: lead with what was broken and what is fixed โ "Fixed session-redirect data loss (#42)", not "We're thrilled to ship improvements to the auth flow".
Verdict is binary: "Ready to tag" or "Blocker: N open issues in milestone, M failing checks". No "mostly ready", no "a few small items".
Stale-snapshot warnings are refusals: "HEAD moved since the sweep report โ re-run the sweep or proceed against the stale snapshot with explicit confirmation. Not proceeding silently."
Framing only. Evidence is identical to balanced mode โ same issue count, same CI state, same manifest SHAs. Never inflate severity. Never invent issues. Never write issues the operator did not approve in Step 7.
Layperson mode โ plain-language translation
When the task context contains explain=layperson (from /vibesubin explain, /vibesubin easy, "์ฝ๊ฒ ์ค๋ช ํด์ค", "์ผ๋ฐ์ธ๋ ์ดํด๋๊ฒ", "explain like I'm non-technical", "้้็บ่ ใงใๅใใใใใซ", "็จ้ไฟ็่ฏ่งฃ้"), add a plain-language layer to every finding this skill emits. Combines freely with tone=harsh. Full rules at /plugins/vibesubin/skills/vibesubin/references/layperson-translation.md.
Three dimensions per finding
Every finding gets three questions answered in plain language, in the operator's language (Korean / English / Japanese / Chinese):
Wrap each finding in the box format from the shared reference. Header uses urgency phrase and the finding number. Footer names the hand-off skill.
What does NOT change
Findings, counts, file:line references, evidence, and severity are identical to balanced/harsh output. Only the wrapping and dimension annotations are added.
Review modes โ full and partial
Full review: every issue in the milestone. Runs Steps 9โ10 until the milestone closes.
Partial review: operator names specific issue numbers ("review 5, 7, 9"). Run Steps 9โ10 only on those. Release at Step 10 only if the named subset forms a complete unit of work on its own โ otherwise advance the issues through Step 9, leave the milestone open, and report.
Partial-review output names the issues still open in the milestone so the operator sees the gap between what shipped and what the milestone promised.
Things not to do
Don't create issues without explicit operator approval at Step 7. Drafting is cheap; creating is committing to a public record.
Don't push tags without verifying CI green on the default branch. A tag on top of red CI is a regression vector.
Don't write release notes before CHANGELOG is updated. CHANGELOG is the source of truth; notes are extracts. Writing the extract first guarantees drift.
Don't bundle unrelated issues into one milestone for convenience. See milestone-rules.md example 3.
Don't use English-only templates when the operator chose Korean / Japanese / Chinese at Step 3. Body language is the operator's choice; section headings stay English for parsing stability.
Don't auto-close issues via commits that did not pass the owning skill's verification. If refactor-verify did not verify the fix, the issue does not get a Closes #N footer โ tag needs-verify and surface to the operator.
Don't add features the operator did not request. This skill specifies the issue set the operator approved. It does not propose new items mid-cycle.
Don't rewrite published tags or release notes. If a release shipped broken, cut a new patch (vX.Y.Z+1). Edit the broken release's notes only to add a "Known issue โ use vX.Y.Z+1" banner; never delete.
Don't invent issue numbers. Always consume gh issue create stdout for the actual number; never predict it.
Don't participate in /vibesubin's parallel sweep. Direct-call only. Documented above.
4-part output shape
Every response ends with the standard umbrella-compatible shape. Example stub:
## What I did
- Drafted 7 issues from the 2026-04-21 sweep report.
- Clustered into 2 milestones: v0.4.1 (5 bugs) and v0.5.0 (2 features).
- Created issues and milestones on GitHub โ #41 through #47.
## What I found
- Two items had no evidence section in the sweep report; added `needs-evidence` label and paused on those.
- The v0.4.1 cluster already exceeds the 5-item patch cap by 1. Split recommended.
## What I verified
- All 7 issues created with correct milestone, labels, and body language (Korean).
- `gh issue list --milestone v0.4.1 --state open` returns 5 issues.
- `gh auth status` returned authenticated before any mutation.
## What you should do next
- Confirm the split for v0.4.1 (5 + 1) or accept the cap override.
- Run `/refactor-verify` or `/audit-security` on the branches as they come up per Step 9's routing table.
- Return for Step 10 (release) once all 5 issues in v0.4.1 are closed.
Hand-offs
Inputs (who produces, how it arrives):
Source
Arrival
/vibesubin sweep report
Operator pastes the report or points to a file path; consumed in Step 4(a).
/codex-fix findings
Operator pastes the review-driven output; consumed in Step 4(a).
Pasted PR review
Operator pastes inline; consumed in Step 4(a).
Sentry / gitleaks / Semgrep
Operator pastes or points to output; consumed in Step 4(a).
Operator-named scope
"perf in src/api/"; consumed in Step 4(c).
Outputs (which skill ships which label):
Label / type
Target skill
bug, refactor, perf
/refactor-verify
security
/audit-security
docs
/write-for-ai
chore + ci
/setup-ci
chore + secrets
/manage-secrets-env
chore + deps / branch / layout
/project-conventions
chore + assets
/manage-assets
design, ui
/unify-design
chore + dead-code
/fight-repo-rot โ /refactor-verify
When not to use ship-cycle
Single-issue single-commit change: call the owning skill (/refactor-verify, /audit-security, /write-for-ai, etc.) directly. ship-cycle is for multi-item release cycles, not one-offs.
No intent to cut a version soon: if the operator just wants to log one item, gh issue create by hand (GitHub track) or an inline note (PRD track) is lighter than running this skill.
Operator is mid-refactor on a hot branch: finish the refactor with refactor-verify, come back to ship-cycle when the batch is ready.
Integration with /vibesubin sweep
Umbrella produces findings; operator reads the sweep report; operator invokes /ship-cycle with "turn these into issues". ship-cycle consumes the findings as Step 4(a) input, runs Steps 5โ11, ends at a published release. The umbrella itself does not launch ship-cycle โ ship-cycle is an explicit post-sweep handoff by the operator, same pattern as codex-fix.
