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

1. Gate check first - claudikins-kernel:verify must have passed. No exceptions.
2. Code integrity - Ship exactly what was verified. No sneaky changes.
3. GRFP everywhere - Section-by-section approval at every stage.
4. Human decides - No auto-merging. Human approves final merge.
5. Clean up after - Delete branches, update docs, celebrate.

The Five Stages

Stage 1: Pre-Ship Review

Show what's being shipped. Human confirms ready.

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:

1. Deep-dive on current docs
2. Identify gaps from changes
3. Pen-wielding for updates
4. Section-by-section approval

Files to update:

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:

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

# 1. Verify state exists
if [ ! -f "$VERIFY_STATE" ]; then
  echo "ERROR: claudikins-kernel:verify has not been run"
  exit 2
fi

# 2. Unlock flag is set
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:

# C-5: Commit hash validation
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

# C-7: File manifest validation
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
- Depe