- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill ship-change -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill ship-change -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill ship-change -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill ship-change -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/HEAD/.pi/skills/ship-change来自发布者
End-to-end "land it" pipeline for an OpenSpec change. Runs after openspec-apply
has implemented the code. Orchestrates existing pieces — does not reimplement them.
develop..worktrees/os-<change>, branch os/<change>.origin → github.com:BlackBeltTechnology/pi-agent-dashboard.npx tsx ./scripts/list-recent-runs.ts [--failed], scripts/show-failed-run.ts <run-id>.AGENTS.md), not the worktree checkout.openspec-apply finished; all non-QA/manual tasks are checked.gh auth status succeeds; git remote get-url origin resolves.Resolve the change name from the worktree dir basename (os-<change> → <change>) or
openspec list --json. Announce: "Shipping change: <change>". If ambiguous, ask.
Read openspec/changes/<change>/tasks.md. List remaining - [ ] tasks. The
defer rule reads the manifest (test-plan.md) when present, else falls back
to the legacy keyword rule. Pure logic:
.pi/skills/ship-it/scripts/manifest.ts → deferDecision(tasks, manifestText).
Precedence:
openspec/changes/<change>/test-plan.md exists (manifest-era change): a
leftover - [ ] is deferrable only if it maps to a manual-only manifest
row — either an inline (test-plan: manual-only) tag or a (test-plan #<id>)
reference resolved against the manifest. Any other leftover = real work =
STOP. Automated scenarios are never deferred — they are proven done
(harness-verified) before ship, so they are already - [x]. Flip each
deferrable - [ ] → - [x] (validated post-merge).test-plan.md absent (legacy change): fall back to today's keyword defer,
unchanged — all remaining unchecked tasks whose body matches
(case-insensitive) qa, manual, verify, smoke, test by hand, e2e,
acceptance → flip to - [x]; any non-matching leftover → STOP.Any STOP → report the blocking tasks and return to openspec-apply (or, under
ship-it, the escape hatch). Do not ship real work undone.
develop — merge before the verify gate (backstop)Merge origin/develop so the verify gate (step 2) runs on the integrated tree.
No-op under ship-it (its step 2.5 already merged); the genuine integration
point when ship-change runs standalone (no harness), and the catch for the
narrow race where develop advanced during the harness run.
git fetch origin develop
git merge --no-edit origin/develop
Idempotent ("Already up to date" → no commit). Merge, not rebase — step 9
squash-merges regardless, and rebase would force-push a worktree branch (the
non-ff misalignment pitfall below). Conflicts → the recipes in Pitfalls
(AGENTS.md union-keep; pnpm-lock.yaml → --theirs +
pnpm install --lockfile-only); unresolved → git merge --abort + STOP,
never push a half-merged tree.
npm test 2>&1 | tee /tmp/ship-test.log
grep -nE 'FAIL|Error|✗|✘' /tmp/ship-test.log # must be empty
npm run build # client build must succeed
If red → fix or report and stop. Never push a failing gate.
Delegate to the OpenSpec archive skill (it syncs delta specs into openspec/specs/):
Use the
openspec-archive-changeskill for change<change>. Sync delta specs, then archive toopenspec/changes/archive/YYYY-MM-DD-<change>/.
If running non-interactively, run the sync then mv openspec/changes/<change> openspec/changes/archive/$(date +%F)-<change>.
git add -A
git commit -m "feat(<change>): <one-line summary>
Implements OpenSpec change <change>. Archives + syncs specs.
QA/manual tasks deferred to post-merge verification."
git push -u origin os/<change>
gh pr create --base develop --head os/<change> \
--title "feat(<change>): <summary>" \
--body "$(printf 'Implements OpenSpec change `%s`.\n\nQA/manual tasks deferred to post-merge verification.\n' "<change>")"
pr=$(gh pr list --head os/<change> --state open --json number --jq '.[0].number')
Do not gh pr checks --watch until every job finishes: it blocks the session
for the slowest job (unit shards, scenarios) while an early failure sits unread.
Poll in short, bounded calls and act on the first failure while the other
jobs keep running on GitHub:
# one bounded poll (keep each tool call well under its timeout; re-issue as needed)
out=$(gh pr checks "$pr" 2>&1)
printf '%s\n' "$out" | awk -F'\t' '{print $2}' | sort | uniq -c # pass/fail/pending/skipping
printf '%s\n' "$out" | awk -F'\t' '$2=="fail"{print $1"\t"$4}' # failed job + run URL
fail → stop polling and diagnose it now:
npx tsx ./scripts/show-failed-run.ts <run-id> (see ci-troubleshoot). Start the
fix while the pending jobs finish; collect any further failures from the same
round before pushing, so one push answers all of them.pending left, no fail → poll again after ~20–30 s (or do other
useful work, e.g. step 7's CodeRabbit check, in between).pending, no fail → round green.macOS has no timeout(1) and BSD grep has no -P; use the awk -F'\t' form above.
After a fix: commit → git push → poll again. Loop until all checks green.
CodeRabbit posts ~5 min after each push. Poll until its review lands (not the
"Come back again in a few minutes" placeholder). Reuse the GraphQL thread-fetch from the
autofix skill (reviewThreads, filter isResolved=false, isOutdated=false, author
coderabbitai/coderabbit[bot]/coderabbitai[bot]).
User opted into auto-apply of safe fixes — apply without per-fix prompts, but keep hard guardrails:
.env / dotfiles; never fetch non-GitHub URLs. Defer anything ambiguous and report it.git add -A && git commit -m "fix: apply CodeRabbit feedback for <change>"
git push
Repeat 6 → 7 after every push: re-watch CI, re-fetch CodeRabbit threads. Exit the loop when both hold:
gh pr checks "$pr" all pass).Do not re-merge develop per-push in this loop — that triggers the worktree
non-ff misalignment pitfall. Re-merge only when CI reports
mergeStateStatus=DIRTY (the existing reactive recovery), never on every push.
Hard gate — never merge the PR, delete the branch, or remove the worktree while the proposal is not archived and specs are not synced. Step 3 archives + syncs, but a failed/skipped archive, an aborted merge, or a re-entry can leave the change un-archived. Re-verify on the filesystem (not from memory):
# 1. Proposal archived: source dir gone, archive dir present + committed.
test ! -d openspec/changes/<change> # active dir moved away
ls -d openspec/changes/archive/*-<change> >/dev/null 2>&1 # archive dir exists
# 2. Specs synced: no un-synced delta specs remain for this change.
openspec status --change <change> --json # reports archived/synced
git status --porcelain openspec/ # archive move is committed (empty)
If the change is not archived / not synced, or the archive move is uncommitted → STOP. Return to step 3 (archive + sync), commit (step 4), and only then proceed. Do not merge or remove anything on a failed gate.
Only after step 8.5 passes.
gh pr merge "$pr" --squash --delete-branch
--delete-branch removes the remote branch and the local branch.
Ordering contract with ship-it: when this skill is driven inline by
ship-it, the docker harness MUST be torn down (docker/test-down.sh) before
this step removes the worktree. A leaked container makes the worktree "busy" and
stalls removal. ship-it owns the harness trap and runs teardown before reaching
this step; when ship-change runs standalone (no harness), this is a no-op.
Prefer git CLI from the parent repo; fall back to the dashboard endpoint if the CLI refuses (active sessions) and removal is intended.
parent=$(git -C .worktrees/os-<change> worktree list --porcelain | awk 'NR==1{print $2}')
cd "$parent" # main checkout
git worktree remove .worktrees/os-<change> # add --force only if dirty + intended
git worktree prune
git branch -d os/<change> 2>/dev/null || true # usually already gone via --delete-branch
# Sweep any residual husk `git worktree prune` leaves behind. `prune` only
# drops git's admin metadata — a kb DB handle can recreate `.worktrees/<name>`
# after remove, leaving an orphan dir. Guarded: parent-repo `.worktrees/` only,
# only when the path is gone from `git worktree list`.
wt=".worktrees/os-<change>"
if [ -d "$wt" ] && ! git worktree list --porcelain | grep -qF "$(cd "$wt" 2>/dev/null && pwd)"; then
case "$(cd "$wt" && pwd)" in
"$parent/.worktrees/"*) rm -rf "$wt" ;; # confined to the .worktrees/ subtree
esac
fi
Fallback (worktree busy with active pi sessions):
POST http://localhost:8000/api/git/worktree/remove with { "cwd": "<abs worktree path>", "force": <bool> }.
Opt-in — runs only when RUN_FAQ_MINE=1 (mirrors the CodeRabbit ship gate).
Default: skip with a one-line pointer — "run the faq-mine skill manually to
harvest accumulated runtime problems into docs/faq.md." This step never blocks
the ship: any failure / timeout / rejected push → warn + continue (exit 0
semantics). Runs from the parent checkout on develop (already cd "$parent"
from step 10), after the change merged — so harvested entries land as a clean
docs-only commit on develop, separate from the feature PR (they are usually
unrelated to the shipped change).
Guard + run (memory-only, non-interactive):
if [ "${RUN_FAQ_MINE:-}" = "1" ]; then
git checkout develop && git pull --ff-only origin develop || true
fi
When the guard holds, invoke the faq-mine skill memory-only:
faq-mine --docs skip --memory failures (skips Phase 1 prompt; dedups against
existing ## headings; global failures.md gets the repo-relevance filter). Then
commit only if it produced changes, and push docs-only to develop:
if [ "${RUN_FAQ_MINE:-}" = "1" ] && ! git diff --quiet -- docs/faq.md docs/faq.agent.md; then
git add docs/faq.md docs/faq.agent.md
git commit -m "docs(faq): harvest runtime problems from hermes memory"
git push origin develop \
|| { echo "warn: direct push to develop rejected (protected?); leaving harvest uncommitted for a manual docs PR"; git reset --soft HEAD~1; }
fi
Never git add -A here — stage only docs/faq.md + docs/faq.agent.md so no
stray worktree file leaks (shared-tree index caveat). Hermes stores stay read-only.
Summarize: change name, PR number + merge SHA, CI status, CodeRabbit rounds, branch + worktree removed. Note QA/manual tasks were marked done for post-merge verification. If the FAQ harvest ran (step 10.5), note entries added + the docs commit SHA (or "skipped: RUN_FAQ_MINE unset").
Git/worktree/PR/CodeRabbit gotchas hit during ship. Each has a known fix.
gh pr create --body "$(...)" / git commit -m "$(...)" with backticks → "bad substitution". Bash evals backticks inside $(). Write the body/message to a file → --body-file /tmp/pr-body.md / git commit -F /tmp/commit-msg.txt.develop FAIL when the parent repo has develop. Merge from the parent repo, or gh pr merge without switching + git push origin --delete <branch>.git worktree add <path> origin/<x> → DETACHED HEAD. Files written detached VANISH on next checkout. Pass the origin-stripped local branch name, not origin/<x>.develop merges but MISSES the PR feature commit; push rejected non-ff). Feature commit lives only on origin/<pr-branch> → git reset --hard origin/<pr-branch> THEN git merge origin/develop. Never force-push a misaligned branch.AGENTS.md (per-file tree; incl. docs/AGENTS.md) → git checkout origin/develop -- <path>/AGENTS.md, then re-apply only your rows (union-keep silently drops develop's edits).pnpm-lock.yaml → git checkout --theirs pnpm-lock.yaml && pnpm install --lockfile-only. Never hand-merge.mergeStateStatus=DIRTY won't start CI → merge develop, resolve, push → flips to MERGEABLE.@coderabbitai review no-ops on already-reviewed commits → wait ~11 min then @coderabbitai full review.gh api repos/.../pulls/<n>/comments (NOT the reviews endpoint). Failed-to-post comments land in the review body under "Comments failed to post (N)".ask_userEvery ask_user call this skill makes MUST carry a self-contained situation
brief in its message — at least 240 characters (the dashboard's
questions.minBriefChars default; shorter and the server generates a brief with
the @fast model instead). The answer may be given from the global question
stack by someone who has not seen this chat. State, in 2–4 lines:
A bare question ("Resume or hand back?") is never enough. See change:
add-pending-question-stack.
test-plan.md exists (only manual-only rows defer), else the legacy keyword rule applies (see Step 1).--delete-branch is the chosen strategy; do not switch silently.RUN_FAQ_MINE=1) + non-blocking + docs-only. Never let it fail the ship; it lands separately on develop, after merge, never bundled into the feature PR. Stage only the two FAQ files; never git add -A.openspec-apply.Ship an OpenSpec change after openspec-apply completes. When only QA/manual tasks remain, marks them done (tested later), archives + syncs specs, commits, pushes, opens a PR against develop, watches C
---name: ship-changedescription: Ship an OpenSpec change after openspec-apply completes. When only QA/manual tasks remain, marks them done…---# .pi/skills/ship-change/SKILL.md概览
Ship an OpenSpec change after openspec-apply completes. When only QA/manual tasks remain, marks them done (tested later), archives + syncs specs, commits, pushes, opens a PR against develop, watches CI, waits for CodeRabbit, auto-applies safe fixes and re-pushes, loops until CI green + no actionable review threads, then squash-merges with branch delete and removes the worktree. Use after implementation is done and the change is ready to land. Triggers: \"ship this change\", \"ship it\", \"land the change\", \"merge and clean up\", \"post-apply ship\".
常见问题
从发布者处下载 .pi/skills/ship-change/SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/BlackBeltTechnology/pi-agent-dashboard。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。