agentleFS
Hacck3yHacck3y/ptk/.claude/skills/ship/SKILL.md

ship

Skill2 starsChanged 3 months agoApache-2.0View on GitHub

Build, commit, push & version bump workflow - automates the complete release cycle

  • Reads credentials
  • Installs packages
  • Commits and pushes

194 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use ios-sync, open-gstack-browser and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Saqlain-811Skill

    ios-sync

    Regenerate the iOS debug bridge against the latest upstream gstack templates. (gstack)

    Also in 6 projects that use this

  • seek888Skill

    open-gstack-browser

    Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. Opens a visible browser window where you can watch every action in real time. The sidebar shows a live activity feed and chat. Anti-bot stealth built in. Use when asked to "open gstack browser", "launch browser", "connect chrome", "open chrome", "real browser", "launch chrome", "side panel", or "control my browser". Voice triggers (speech-to-text aliases): "show me the browser".

    Also in 10 projects that use this

  • ayudaySkill

    setup-deploy

    Configure deployment settings for /land-and-deploy. Detects your deploy platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), production URL, health check endpoints, and deploy status commands. Writes the configuration to CLAUDE.md so all future deploys are automatic. Use when: "setup deploy", "configure deployment", "set up land-and-deploy", "how do I deploy with gstack", "add deploy config".

    Also in 19 projects that use this

  • ShreyRaviSkill

    landing-report

    Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

    Also in 9 projects that use this

  • zebbernSkill

    debug-fix

    Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)

    Also in 4 projects that use this

  • ramybarsoumSkill

    document-release

    Post-ship documentation update. Reads all project docs, cross-references the diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when asked to "update the docs", "sync documentation", or "post-ship docs". Proactively suggest after a PR is merged or code is shipped.

    Also in 23 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 181 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Manual invocation: When ready to release a new version

    line 12
  2. Distinctive:

    After feature completion: Before tagging and publishing

    line 13
  3. Very specific:

    Before running /ship, verify:

    line 18
  4. Distinctive:

    If release has critical issues:

    line 199
  5. Distinctive:

    Solution: Do not edit CHANGELOG.md manually.

    line 365

“Common” is measured: kept by at least 6 in 10 of the 181 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Ship Release

Systematic release workflow for PTK: build verification, version bump, changelog update, git tag, and push to trigger CI/CD.

When to Use

  • Manual invocation: When ready to release a new version
  • After feature completion: Before tagging and publishing
  • Before version bump: To automate the release checklist

Pre-Release Checklist (Auto-Verified)

Before running /ship, verify:

1. Quality Checks Pass

cargo fmt --all --check    # Code formatted
cargo clippy --all-targets # Zero warnings
cargo test --all           # All tests pass

2. Performance Benchmarks Pass

hyperfine 'target/release/ptk git status' --warmup 3
# Should show <10ms mean time

/usr/bin/time -l target/release/ptk git status
# Should show <5MB maximum resident set size

3. Integration Tests Pass

cargo install --path . --force  # Install locally
cargo test --ignored            # Run integration tests

4. Git Clean State

git status  # Should show "nothing to commit, working tree clean"

Release Workflow

Step 1: Determine Version Bump

Semantic Versioning (MAJOR.MINOR.PATCH):

  • MAJOR (v1.0.0): Breaking changes (rare for PTK)
  • MINOR (v0.X.0): New features, new filters, new commands
  • PATCH (v0.0.X): Bug fixes, performance improvements

Examples:

  • New filter added (ptk pytest) → MINOR bump (v0.16.0 → v0.17.0)
  • Bug fix in git log filter → PATCH bump (v0.16.0 → v0.16.1)
  • Breaking CLI arg change → MAJOR bump (v0.16.0 → v1.0.0)

Step 2: Update Version

Files to update:

  1. Cargo.toml (line 3): version = "X.Y.Z"
  2. README.md (if version mentioned)

Note: CHANGELOG.md is auto-generated by release-please from conventional commit messages — do not edit manually.

Example:

# Cargo.toml (before)
[package]
name = "ptk"
version = "0.16.0"  # Current version

# Cargo.toml (after - MINOR bump)
[package]
name = "ptk"
version = "0.17.0"  # New version

CHANGELOG.md template:

## [0.17.0] - 2026-02-15

### Added
- `ptk pytest` command for Python test filtering (90% token reduction)
- Support for `pytest` JSON output parsing
- Integration with `uv` package manager auto-detection

### Fixed
- Shell escaping for PowerShell on Windows
- Memory leak in regex pattern caching

### Changed
- Updated `cargo test` filter to show test names in failures

Step 3: Build and Verify

# Clean build
cargo clean
cargo build --release

# Verify binary
target/release/ptk --version
# Should show new version

# Run full quality checks
cargo fmt --all --check
cargo clippy --all-targets
cargo test --all

# Benchmark performance
hyperfine 'target/release/ptk git status' --warmup 3
# Should still be <10ms

Step 4: Commit Version Bump

# Stage version files
git add Cargo.toml Cargo.lock README.md

# Commit with version tag
git commit -m "chore(release): bump version to v0.17.0

- Updated Cargo.toml version
- Verified all quality checks pass
- Benchmarked performance (<10ms startup)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

Step 5: Create Git Tag

# Create annotated tag with changelog excerpt
git tag -a v0.17.0 -m "Release v0.17.0

Added:
- ptk pytest command (90% token reduction)
- Support for uv package manager

Fixed:
- Shell escaping for PowerShell
- Memory leak in regex caching

Performance: <10ms startup, <5MB memory"

Step 6: Push to Remote

# Push commit and tags
git push origin main
git push origin v0.17.0

# Trigger GitHub Actions release workflow
# (CI/CD will build binaries, create GitHub release, publish to crates.io if configured)

Post-Release Verification

After pushing, verify:

1. GitHub Actions CI/CD Pass

# Check GitHub Actions workflow status
gh run list --limit 1

# Watch latest run
gh run watch

2. GitHub Release Created

# Check if release created
gh release view v0.17.0

# Should show:
# - Release notes from git tag
# - Binaries attached (macOS, Linux x86_64/ARM64, Windows)
# - Checksums for verification

3. Installation Verification

# Test installation from release
curl -sSL https://github.com/hacck3y/ptk/releases/download/v0.17.0/ptk-macos-latest -o ptk
chmod +x ptk
./ptk --version
# Should show v0.17.0

Rollback Plan

If release has critical issues:

Option 1: Patch Release (Preferred)

# Fix issue in new branch
git checkout -b hotfix/v0.17.1
# Apply fix
cargo test --all
git commit -m "fix: critical issue in pytest filter"

# Release v0.17.1 (PATCH bump)
# Follow release workflow above

Option 2: Yank Release (crates.io only)

# Yank broken version from crates.io
cargo yank --vers 0.17.0

# Users can't download yanked version, but existing installs work

Option 3: Revert Tag (Last Resort)

# Delete tag locally
git tag -d v0.17.0

# Delete tag on remote
git push origin :refs/tags/v0.17.0

# Delete GitHub release
gh release delete v0.17.0 --yes

# Revert commit
git revert HEAD
git push origin main

Automated Release Script (Optional)

Save as scripts/ship.sh:

#!/bin/bash
set -euo pipefail

# Parse version argument
if [ $# -ne 1 ]; then
    echo "Usage: $0 <version>"
    echo "Example: $0 0.17.0"
    exit 1
fi

NEW_VERSION=$1

echo "🚀 Starting release workflow for v$NEW_VERSION"

# 1. Quality checks
echo "📦 Running quality checks..."
cargo fmt --all --check
cargo clippy --all-targets
cargo test --all

# 2. Update version
echo "🔢 Updating version to $NEW_VERSION..."
sed -i '' "s/^version = .*/version = \"$NEW_VERSION\"/" Cargo.toml

# 3. Build
echo "🔨 Building release binary..."
cargo build --release

# 4. Verify version
echo "✅ Verifying version..."
target/release/ptk --version | grep "$NEW_VERSION"

# 5. Commit
echo "💾 Committing version bump..."
git add Cargo.toml Cargo.lock
git commit -m "chore(release): bump version to v$NEW_VERSION

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# 6. Tag
echo "🏷️  Creating git tag..."
git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"

# 7. Push
echo "🚢 Pushing to remote..."
git push origin main
git push origin "v$NEW_VERSION"

echo "✅ Release v$NEW_VERSION shipped!"
echo "Monitor CI/CD: gh run watch"

Usage:

chmod +x scripts/ship.sh
./scripts/ship.sh 0.17.0

Release Frequency

Recommended cadence:

  • PATCH releases: As needed for critical bugs (24h turnaround)
  • MINOR releases: Weekly or bi-weekly for new features
  • MAJOR releases: Quarterly or when breaking changes necessary

Version History Reference

Check version history:

git tag -l "v*"  # List all version tags
git log --oneline --tags  # Show commits with tags

Example output:

v0.17.0 (HEAD -> main, tag: v0.17.0, origin/main)
v0.16.0
v0.15.1
v0.15.0

Common Issues

Issue: CI/CD Fails After Tag Push

Symptom: GitHub Actions workflow fails on release build

Solution:

# Fix issue locally
git checkout main
# Apply fix
cargo test --all
git commit -m "fix: CI/CD build issue"
git push origin main

# Delete old tag
git tag -d v0.17.0
git push origin :refs/tags/v0.17.0

# Create new tag
git tag -a v0.17.0 -m "Release v0.17.0 (rebuild)"
git push origin v0.17.0

Issue: Version Mismatch

Symptom: ptk --version shows old version after bump

Solution:

# Cargo.lock might be out of sync
cargo update -p ptk
cargo build --release

# Verify
target/release/ptk --version

Issue: Changelog Merge Conflict

Symptom: CHANGELOG.md has conflicts after rebase

Solution: Do not edit CHANGELOG.md manually. It is auto-generated by release-please from conventional commit messages when merging to master.

Security Considerations

Before releasing:

  • No secrets in code (API keys, tokens)
  • No .env files committed
  • Dependencies scanned (cargo audit)
  • Shell injection vulnerabilities reviewed
  • Cross-platform shell escaping tested

Dependency audit:

cargo install cargo-audit
cargo audit

# Example output:
# Crate: some-crate
# Version: 0.1.0
# Warning: vulnerability found
# Advisory: CVE-2024-XXXXX

If vulnerabilities found:

# Update vulnerable dependency
cargo update some-crate

# Verify fix
cargo audit

# Re-run quality checks
cargo test --all

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.