/ship

name: ship
description: Fast-track small features without full PRD process
category: Git Workflow
version: 0.4.4
aliases: [quick-ship]

Quick Ship Command

Ship small features/fixes fast without full PRD overhead, with optional worktree isolation.

Purpose

For small changes that don't need full PRD:

• Bug fixes
• Small UI tweaks
• Dependency updates
• Minor refactors
• Quick experiments

**NEW in v0.4.4**: Automatic context detection - run from Main OR from worktree directly! **v0.4.3**: Support for worktree isolation with `--worktree` flag.

Context Detection (Auto)

The `/ship` command **automatically detects** where you run it from:

From Main Repository

# Working directory: ~/Documents/watchora
$ /ship "Fix auth bug"
→ Behavior: Works on Main (default)
→ Optional: Add --worktree to use hotfix worktree

From Hotfix Worktree

# Working directory: ~/Documents/watchora/worktrees/hotfix
$ /ship "Fix auth bug"
→ Behavior: Automatically uses worktree (no --worktree needed!)
→ Syncs, locks, creates branch, works in current directory

**Key Point**: If you have a dedicated Cursor window open on `worktrees/hotfix/`, you can use `/ship` directly from there!

When to Use

**Use Quick Ship for**:

• Features < 4 hours
• Single developer work
• Clear scope, no unknowns
• Low risk changes

**Use Full PRD for**:

• Features > 1 day
• Multiple developers
• Unclear requirements
• High-risk changes
• Customer-facing features

Usage

# From Main: Work on Main (quick, simple)
/ship "Fix login button alignment"

# From Main: With worktree isolation (safer, larger fixes)
/ship "Refactor auth module" --worktree

# From Worktree: Auto-detects worktree context
cd worktrees/hotfix/
/ship "Fix auth bug"       # Automatically uses worktree!

# Manage active fix (works from anywhere)
/ship --complete           # Finish and merge
/ship --abort              # Cancel fix
/ship --status             # Show current status
/ship --pause              # Pause current fix
/ship --resume             # Resume paused fix

# Migrate from Main to worktree
/ship --to-worktree        # Move current fix to worktree

Options

| Option | Description | |--------|-------------| | `--worktree` | Use hotfix worktree for isolation | | `--to-worktree` | Migrate current fix from Main to worktree | | `--complete` | Complete current fix (commit + PR + merge) | | `--abort` | Abort current fix without merging | | `--status` | Show current fix status | | `--pause` | Pause fix and save state | | `--resume` | Resume paused fix |

Workflow: Default (Main)

Step 1: Start Fix on Main

$ /ship "Fix dark mode toggle"

✅ Quick fix on Main
📝 Branch: quickship/fix-dark-mode-toggle

💡 Working on Main - keep it small!

Step 2: Guided Implementation

AI provides inline guidance for the fix:

• File locations
• Code changes
• Testing approach

Step 3: Smart Warnings

As you work, smart detection monitors:

# After 20 minutes, 8 files, 150 lines...

⚠️  LARGE FIX DETECTED
- 8 files changed
- 150 lines modified
- 22 minutes elapsed

💡 This is getting large. Consider:
  1. /ship --complete (finish on Main)
  2. /ship --to-worktree (migrate to worktree)
  3. Continue on Main (suppress warning)

Choose: _

**Thresholds**:

• Files: > 5 files
• Lines: > 100 lines
• Time: > 30 minutes

Step 4: Complete Fix

$ /ship --complete

✅ Committed: fix: Dark mode toggle improvements
📤 PR #234 created
⏳ Waiting for checks...
✅ Checks passed, auto-merged
🎉 Merged to main
🧹 Cleaned up branch

Workflow: With Worktree (from Main)

Step 1: Start Fix in Worktree

$ /ship "Refactor authentication module" --worktree

🔍 Checking worktree hotfix/...

# AUTO-SYNC (Intelligent)
🔄 Syncing worktree (3 commits behind)...

Recent changes:
  - a3f2c1d fix: OAuth timeout
  - 8d4e2a9 feat: Better logging
  - 1c8f3b2 refactor: API cleanup

✅ Synced with main

# START FIX
✅ Started in worktrees/hotfix/
📝 Branch: hotfix/refactor-auth-module
🔒 Locked worktree (one fix at a time)

💻 Open in new window: code worktrees/hotfix/

**Auto-sync thresholds**:

• 0 commits: ✅ No sync needed
• 1-10 commits: 🔄 Silent auto-sync
• 10-50 commits: ⚠️ Propose sync with preview
• 50+ commits: ❌ Force sync (required)

Step 2: Isolated Development

Work in `worktrees/hotfix/`:

• No size limits
• No time warnings
• Complete isolation
• Can open in separate Cursor window

Step 3: Complete Fix

$ /ship --complete

✅ Committed & pushed
📤 PR #235 created
⏳ Waiting for checks...
✅ Checks passed, auto-merging
🎉 Merged to main

# AUTO-CLEANUP
🔄 Returning to parking branch...
🧹 Deleted branch hotfix/refactor-auth-module
🔄 Syncing with main...
✅ Worktree ready for next fix
🔓 Unlocked worktree

↩️  Returned to Main

Workflow: From Worktree Directly (NEW in v0.4.4)

Setup: Open Cursor Window on Worktree

# One-time setup: Open dedicated Cursor window
cd ~/Documents/watchora/worktrees/hotfix/
code .  # Opens Cursor in worktree directory

Step 1: Start Fix (from Worktree)

# You're already in worktrees/hotfix/
$ pwd
~/Documents/watchora/worktrees/hotfix

# Run /ship directly - no --worktree flag needed!
$ /ship "Fix authentication bug"

🔍 Detected: Running from worktree hotfix/
🎯 Auto-enabling worktree mode

# AUTO-SYNC (Intelligent)
🔄 Checking sync status...
✅ Synced with main (or auto-sync if needed)

# START FIX
✅ Started in current directory
📝 Branch: hotfix/fix-authentication-bug
🔒 Locked worktree (one fix at a time)

💡 Working in worktree - no limits!

Step 2: Development (Same Directory)

You work in the **same directory** where you launched `/ship`:

• Already in `worktrees/hotfix/`
• All your tools/extensions work normally
• Commit as you go
• No need to switch directories

Step 3: Complete Fix (from Worktree)

# Still in worktrees/hotfix/
$ /ship --complete

✅ Committed & pushed
📤 PR #236 cre