Kit Preamble — ship

---

name: ship description: Finalizes tests/docs/changelog and merges the PR to make it deployment-ready. disable-model-invocation: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(bash scripts/kit_update_check.py ), Bash(python3 scripts/), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *)

Kit Preamble — ship

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

Project Context Detection

Run these checks silently at the start. Use results to adapt behavior:

• [ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
• [ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.
• [ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Checkpoint Verification Pattern

Every phase has a mandatory checkpoint. Run the verification command and check exit code. If exit code is not 0, STOP immediately and report failure. Do NOT proceed to the next phase. Standard prefix:

bash scripts/checkpoint.sh

Append --skill <name> --phase <phase> --issue <ID> for the specific check. checkpoint.sh resolves the main repo root internally, so the command stays a single prefix-matchable form (safe to allowlist as Bash(bash scripts/checkpoint.sh *)).

Worktree Setup Pattern

Pipeline skills operate in git worktrees to isolate changes from main.

• Create + freeze: WT="$(bash scripts/wt_setup.sh <branch>)" — creates the worktree via scripts/worktree.sh create and writes .claude-kit/freeze-dir.txt inside it in a single step.
• Resolve main root: bash scripts/worktree.sh root
• Remove safely: bash scripts/wt_cleanup.sh <branch> — cd's to main root inside a subshell, then removes the worktree (never leaves CWD dangling). All file operations happen inside $WT/. Shared files live on main only.

Registry Update Pattern

Shared files (issues.md, STATUS.md, CHANGELOG.md) are managed on main only. Always use registry_edit.sh for concurrent-safe writes — it resolves the main repo root internally and delegates to flock_edit.sh:

bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'

Never commit these files to feature branches.

Self-Review Requirements

Before completing any major phase, pause and verify:

• Does the output satisfy the stated acceptance criteria?
• Are there edge cases not covered?
• Could this break existing functionality?
• Rate confidence: High / Medium / Low. If Low, flag to the user before proceeding.

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors. Steps:

1. Identify PR to merge (current branch or most recent done issue PR).
2. Ensure tests pass locally and PR checks are green.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase checks --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

3. Update docs/README.md; append CHANGELOG.md.

3.5) Ask documenter subagent to review and update project documentation:

• Use the Task tool to launch a documenter subagent (agents/documenter.md).
• Pass the PR diff summary, list of changed files, and existing docs/ contents as context.
• Documenter checks docs/ (README, runbook, troubleshooting, contributing) against the code changes.
• If docs are outdated or missing coverage for the changes: update them.
• If no doc updates needed: skip silently.

Update shared files via the registry wrapper:

bash scripts/registry_edit.sh STATUS.md -- bash -c '<update command>'

4. Merge via gh pr merge (merge/squash per repo rules) and delete branch.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase merge --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

5. Clean up worktree if one exists for this branch. Use the wt_cleanup.sh wrapper — it cd's to the main repo root and removes the worktree in a single subshell, so the caller's CWD is never left inside a deleted directory:

   bash scripts/wt_cleanup.sh <branch>
   

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase cleanup --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

6. Post-merge smoke test on main (MANDATORY):

   git checkout main && git pull
   

   • Python: pytest -q --tb=short
   • JS/TS: npm test
   • Platform gates: verify_gates.py runs automatically via checkpoint (e2e-web, e2e-mobile, api, integration, load — as configured in docs/test_plan.md).
   • If tests or gates fail: alert the user immediately with failing output and suggest git revert -m 1 <merge_commit>.

CHECKPOINT — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill ship --phase smoke --issue $ARGUMENTS If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

7. Post-ship test gap advisory (optional, non-blocking):
   • Identify files changed in the merged PR: git diff --name-only HEAD~1 HEAD
   • Filter to source files only (exclude test files, configs, docs, generated files)
   • For each changed source file, check if a corresponding test file exists:
     • Python src/module.py → tests/test_module.py
     • JS/TS src/component.ts → src/component.test.ts or src/component.spec.ts
   • If gaps found, report to user:

     Test coverage gaps detected in shipped code:
     - src/auth.py → no corresponding test file
     - src/webhook.py → test exists but may lack coverage for new functions
     Suggestion: run `/testgen <path>` to generate missing tests.
     

   • This step is advisory only — it does NOT block the ship or fail the pipeline.
   • If no gaps found, skip silently.

Shared Registry Files

IMPORTANT: Never commit issues.md, STATUS.md, or CHANGELOG.md to the feature branch. These are registry files managed only on main. Always use bash scripts/registry_edit.sh <file> -- bash -c '<update command>' — the wrapper resolves the main repo root internally.

Error Handling

• Pre-merge checks (must all pass before merging):
  1. gh pr checks <pr> — all CI checks must be green.
  2. Local test suite must pass.
  3. PR must not be in draft state. If any check fails: stop and report which check failed.
• If gh pr merge fails: report the error (e.g., merge conflicts, branch protection rules).
• If post-merge smoke test fails on main:
  1. Immediately alert the user with the failing test output.
  2. Suggest git revert -m 1 <merge_commit> to revert the merge.
  3. Do NOT auto-revert without user confirmation.

Rollback

• If merge must be reverted:
  1. git revert -m 1 <merge_commit_sha> on main.
  2. Push the revert commit.
  3. Update CHANGELOG.md with a revert entry.
  4. Update STATUS.md to reflect the reverted state.
• Branch is already deleted after merge; if rework is needed, create a new branch from the revert.