| name | shipping-methodology |
| description | Use when running claudikins-kernel:ship, preparing PRs, writing changelogs, deciding merge strategy, or handling CI failures — enforces GRFP-style iterative approval, code integrity validation, and human-gated merges |
| allowed-tools | ["Read","Grep","Glob","Bash","Edit","AskUserQuestion","Skill","mcp__plugin_claudikins-tool-executor_tool-executor__search_tools","mcp__plugin_claudikins-tool-executor_tool-executor__get_tool_schema","mcp__plugin_claudikins-tool-executor_tool-executor__execute_code"] |
Shipping Methodology
When to use this skill
Use this skill when you need to:
- Run the
claudikins-kernel:ship command
- Prepare commit messages and PR descriptions
- Update changelogs and documentation
- Decide merge strategy (squash vs preserve)
- Handle CI failures or merge conflicts
- Validate code integrity before shipping
Core Philosophy
"Ship with confidence, not hope." - Shipping philosophy
Shipping is the final gate. Apply GRFP-style iterative workflow to every stage.
The Five Principles
- Gate check first - claudikins-kernel:verify must have passed. No exceptions.
- Code integrity - Ship exactly what was verified. No sneaky changes.
- GRFP everywhere - Section-by-section approval at every stage.
- Human decides - No auto-merging. Human approves final merge.
- Clean up after - Delete branches, update docs, celebrate.
The Five Stages
Stage 1: Pre-Ship Review
Show what's being shipped. Human confirms ready.
| Check | What to Show |
|---|
| Verification status | All phases PASS from claudikins-kernel:verify |
| Branches to merge | List all execute/task-* branches |
| Evidence summary | Screenshots, curl responses from catastrophiser |
| Code delta | Lines added/removed, files changed |
Checkpoint:
Ready to ship?
Verified: ✓ All checks passed
Branches: 3 branches to merge
Changes: +450 / -120 lines
[Continue] [Back to Verify] [Abort]
Stage 2: Commit Strategy
Draft commit message(s). Human approves.
Decision:
How should we commit?
[Squash into single commit] [Preserve commit history]
Squash (recommended for features):
- Single clean commit on main
- Clear feature boundary
- Easier to revert if needed
Preserve (for large multi-part work):
- Keeps granular history
- Better for debugging
- Use for multi-feature batches
Checkpoint:
Commit message:
feat(auth): Add authentication middleware
- JWT token validation
- Role-based access control
- Session management
Closes #42
[Accept] [Revise] [Back]
Stage 3: Documentation (git-perfectionist)
Update README, CHANGELOG, version. GRFP-style.
git-perfectionist uses github-readme plugin:
- Deep-dive on current docs
- Identify gaps from changes
- Pen-wielding for updates
- Section-by-section approval
Files to update:
| File | What to Update |
|---|
| README.md | Features, usage, installation if changed |
| CHANGELOG.md | Add entry in Keep a Changelog format |
| package.json / Cargo.toml / pyproject.toml | Version bump if needed |
Checkpoint:
Documentation updates:
README.md:
- Added: Authentication section
- Updated: Installation (new deps)
CHANGELOG.md:
- Added: v1.2.0 entry
Version: 1.1.0 → 1.2.0 (minor)
[Accept] [Revise] [Skip]
Stage 4: PR Creation
Draft PR title and body. Section-by-section approval.
PR Title Pattern:
feat(scope): Short description
PR Body Structure:
## Summary
[2-3 bullet points of what changed]
## Changes
[Detailed breakdown]
## Testing
[How it was verified]
## Screenshots
[If applicable]
Checkpoint:
PR ready to create:
Title: feat(auth): Add authentication middleware
Body:
## Summary
- Added JWT token validation
- Implemented role-based access control
...
[Create PR] [Revise] [Back]
Stage 5: Final Merge
CI passes. Human approves. Merge and cleanup.
CI Status Check:
CI Status: ⏳ Running...
[Wait for CI] [View logs] [Merge anyway]
On CI pass:
CI Status: ✓ All checks passed
Ready to merge PR #42 to main?
[Merge] [Request review first] [Cancel]
After merge:
- Delete feature branches (unless --no-delete-branch)
- Update ship-state.json
- Celebrate
Final output:
Done! Shipped to main.
PR #42 merged ✓
Branches cleaned up ✓
Version: 1.1.0 → 1.2.0
Nice work!
Rationalizations to Resist
Agents under pressure find excuses. These are all violations:
| Excuse | Reality |
|---|
| "Verify passed yesterday, close enough" | Stale verification = no verification. Re-run claudikins-kernel:verify. |
| "Just a tiny fix after verify, no big deal" | Any change after verify invalidates it. Re-run claudikins-kernel:verify. |
| "CI is flaky, I'll merge anyway" | Flaky CI hides real failures. Fix or explicitly skip with caveat. |
| "It's just a typo, skip the PR" | All changes go through PR. No exceptions. |
| "Both reviewers passed, auto-merge is fine" | Human approves final merge. Always. |
| "I'll update the changelog later" | Changelog is part of shipping. Do it now. |
| "Force push is fine, it's my branch" | Never force push to protected branches. Ever. |
| "Skip docs, nobody reads them" | Docs are part of shipping. GRFP them. |
| "The gate check is too strict" | The gate exists for a reason. Pass it properly. |
All of these mean: Follow the methodology. Shortcuts create incidents.
Red Flags — STOP and Reassess
If you're thinking any of these, you're about to violate the methodology:
- "Let me just push this one change..."
- "Verify is probably still valid"
- "CI will pass next time"
- "I'll do the PR properly next time"
- "Auto-merge saves time"
- "Docs can wait"
- "Force push will fix it"
- "The human already approved something similar"
All of these mean: STOP. Gate check exists. Human decides. Follow the stages.
Gate Check Pattern (CRITICAL)
The ship-init.sh hook enforces the claudikins-kernel:verify gate with code integrity validation.
Required Checks
if [ ! -f "$VERIFY_STATE" ]; then
echo "ERROR: claudikins-kernel:verify has not been run"
exit 2
fi
UNLOCK=$(jq -r '.unlock_ship // false' "$VERIFY_STATE")
if [ "$UNLOCK" != "true" ]; then
echo "ERROR: claudikins-kernel:verify did not pass or was not approved"
exit 2
fi
Code Integrity (C-5, C-7)
Ensure we ship exactly what was verified:
VERIFY_COMMIT=$(jq -r '.verified_commit_sha' "$VERIFY_STATE")
CURRENT_COMMIT=$(git rev-parse HEAD)
if [ "$VERIFY_COMMIT" != "$CURRENT_COMMIT" ]; then
echo "ERROR: Code changed since verification"
exit 2
fi
VERIFIED_MANIFEST=$(jq -r '.verified_manifest' "$VERIFY_STATE")
CURRENT_MANIFEST=$(sha256sum "$MANIFEST_FILE" | cut -d' ' -f1)
if [ "$VERIFIED_MANIFEST" != "$CURRENT_MANIFEST" ]; then
echo "ERROR: Source files changed after verification"
exit 2
fi
If integrity check fails:
Code has changed since verification.
Verified commit: abc123
Current commit: def456
[Re-run claudikins-kernel:verify] [Abort]
Commit Message Patterns
Feature
feat(scope): Short description
- Bullet point of what changed
- Another change
Closes #123
Bug Fix
fix(scope): Short description
Root cause: What was wrong
Fix: What we did
Fixes #456
Breaking Change
feat(scope)!: Short description
BREAKING CHANGE: What breaks and migration path
- Change 1
- Change 2
Chore (no user-facing change)
chore(scope): Short description
- Internal refactor
- Dependency update
See commit-message-patterns.md for full guide.
CHANGELOG Format
Follow Keep a Changelog format:
## [Unreleased]
## [1.2.0] - 2026-01-17
### Added
- Authentication middleware with JWT support (#42)
### Changed
- Updated error messages for clarity
### Fixed
- Token refresh race condition (#38)
## [1.1.0] - 2026-01-10
...
See changelog-merge-strategy.md for merging entries.
External Service Failures
GitHub API Failure (E-6, E-7, E-8)
PR creation failed.
Error: GitHub API returned 503
Retry 1/3...
Pattern: Max 3 retries with exponential backoff.
If persistent:
GitHub API unavailable after 3 retries.
[Try again] [Save as draft PR] [Manual merge]
Save state with pending_merge: true for recovery.
CI Failure
CI failed.
Failed checks:
- lint: 2 errors
- test: 1 failure
[View logs] [Fix and retry] [Skip CI] [Abort]
See ci-failure-handling.md for recovery patterns.
Force Push Protection (S-23)
Never force push to protected branches.
PROTECTED_BRANCHES="main master release"
if echo "$PROTECTED_BRANCHES" | grep -q "$TARGET"; then
if [ "$FORCE" = "true" ]; then
echo "ERROR: Cannot force push to $TARGET"
exit 2
fi
fi
See force-push-protection.md for safeguards.
Breaking Change Detection (S-24)
Detect breaking changes before shipping:
| Signal | Indicates |
|---|
| Removed public function | Breaking |
| Changed function signature | Breaking |
| Removed config option | Breaking |
| Changed default behaviour | Potentially breaking |
If breaking change detected:
Breaking change detected!
- Removed: authenticate() function
- Changed: login() now requires email
This requires a MAJOR version bump.
[Acknowledge and continue] [Abort]
See breaking-change-detection.md for detection patterns.
Anti-Patterns
Don't do these:
- Shipping without claudikins-kernel:verify passing
- Modifying code after verification
- Force pushing to main/master
- Auto-merging without human approval
- Skipping documentation updates
- Ignoring CI failures
- Using vague commit messages ("fix stuff")
- Forgetting to delete feature branches
State Tracking
ship-state.json
{
"session_id": "ship-2026-01-17-1130",
"verify_session_id": "verify-2026-01-17-1100",
"target": "main",
"phases": {
"pre_ship_review": { "status": "APPROVED" },
"commit_strategy": { "status": "APPROVED", "strategy": "squash" },
"documentation": {
"status": "APPROVED",
"files_updated": ["README.md", "CHANGELOG.md"]
},
"pr_creation": { "status": "CREATED", "pr_number": 42 },
"merge": { "status": "MERGED", "sha": "abc123" }
},
"cleanup": {
"branches_deleted": ["execute/task-1-auth", "execute/task-2-routes"]
},
"shipped_at": "2026-01-17T11:46:00Z"
}
References
Full documentation in this skill's references/ folder:
