povvo/claudikins-kernel/shipping-methodology

Name: shipping-methodology
Author: povvo

Claude Code and agent skill by povvo/claudikins-kernel

Trust tier 2

community
ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]

Source check pending

Checking that the SKILL.md file is still in the repository.

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

Install

npx vskill@latest install povvo/claudikins-kernel/shipping-methodology

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

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:

markdown

## 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

bash

# 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:

bash

# 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
- Dependency update

See commit-message-patterns.md for full guide.

CHANGELOG Format

Follow Keep a Changelog format:

markdown

## [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.

bash

# Check if target is protected
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

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:

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 96 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/shipping-methodology/SKILL.md

Popularity

Repository stars: 128
Repository forks: 7
7-day trend score: 24

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Extension points

hookPre/post lifecycle hooks

Learn the extensible skills standard

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/povvo/claudikins-kernel/shipping-methodology/badge)](https://verified-skill.com/skills/povvo/claudikins-kernel/shipping-methodology)

Something wrong with this skill or its page? Tell us.