Name: ship
Author: Yassinello

Prompt file imported from Yassinello/claude-plugin-prd-workflow (.claude/commands/ship.md). Copyright stays with the author.

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 created
⏳ Waiting for checks...
✅ Checks passed, auto-merging
🎉 Merged to main

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

📍 Still in: worktrees/hotfix/ (ready for next fix)

Advantage: You stay in the same Cursor window the entire time!

Collision Handling

One fix at a time in hotfix worktree:

$ /ship "Fix autre" --worktree

❌ Fix already in progress in worktrees/hotfix/

Current fix: hotfix/refactor-auth-module
Started: 25 minutes ago
Files: 7 modified

⚠️  Only ONE fix at a time in hotfix worktree

Options:
1. Finish current fix: /ship --complete
2. Work on Main instead: /ship "Fix autre"
3. Abort current fix: /ship --abort

💡 For urgent small fixes, use Main:
  /ship "Fix autre"

Choose: _

Migration: Main → Worktree

Started on Main but fix is growing:

# Working on Main...
⚠️  LARGE FIX DETECTED (warning appears)

$ /ship --to-worktree

🔄 Migrating to worktree...

# Process:
1. ✅ Commit WIP on Main
   git add .
   git commit -m "WIP: Large fix"

2. ✅ Setup worktree hotfix/
   Auto-sync if needed

3. ✅ Cherry-pick WIP to worktree
   cd worktrees/hotfix/
   git checkout -b hotfix/large-fix
   git cherry-pick <wip-commit>

4. ✅ Reset Main
   cd main-repo/
   git reset --hard HEAD~1

5. ✅ Continue in worktree
   💻 Open: code worktrees/hotfix/

Migration complete!
Continue working in worktrees/hotfix/

State Management

Lock File

.claude-lock in worktrees/hotfix/:

{
  "status": "in_progress",
  "type": "hotfix",
  "branch": "hotfix/refactor-auth",
  "started_at": "2025-01-13T10:30:00Z",
  "started_by": "/ship --worktree",
  "description": "Refactor authentication module",
  "files_changed": 7,
  "lines_changed": 234,
  "commits": 3,
  "last_commit": "a3f2c1d Improve auth flow"
}

Status Check

$ /ship --status

📊 Current Fix Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📍 Location: worktrees/hotfix/
📝 Branch: hotfix/refactor-auth-module
⏱️  Started: 25 minutes ago
📊 Progress:
  - Files: 7 modified
  - Lines: +234 -87
  - Commits: 3

Recent commits:
  - a3f2c1d Improve auth flow
  - 8d4e2a9 Add tests
  - 1c8f3b2 Refactor middleware

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Actions:
  - /ship --complete (finish)
  - /ship --pause (save for later)
  - /ship --abort (cancel)

Pause & Resume

Pause Fix

$ /ship --pause

💾 Pausing fix...

✅ Committed WIP state
📝 Updated lock file (status: paused)
🔄 Returned to parking branch

Fix paused. Resume with: /ship --resume

Resume Fix

$ /ship --resume

📋 Paused fixes:

1. hotfix/refactor-auth-module
   Started: 2 hours ago
   Files: 7 modified
   Last: Improve auth flow

Resume which fix? (1): 1

🔄 Resuming fix...
✅ Checked out branch: hotfix/refactor-auth-module
📊 Fix status loaded

Continue working!

Configuration

Respects .claude/config-worktrees.json:

{
  "worktrees": {
    "hotfix": {
      "path": "worktrees/hotfix",
      "branch_parking": "hotfix"
    }
  },
  "warnings": {
    "files_threshold": 5,
    "lines_threshold": 100,
    "time_threshold_minutes": 30
  },
  "auto_complete": {
    "auto_merge_if_checks_pass": true,
    "cleanup_after_merge": true
  }
}

Examples

Example 1: Simple Fix on Main

$ /ship "Fix typo in error message"

# Small fix, 1 file, 2 lines
# No warnings
# Complete quickly

$ /ship --complete

✅ Done!

Example 2: Fix Grows, Migrate to Worktree

$ /ship "Fix dark mode issues"

# Start on Main
# After 20 min: 8 files, 150 lines

⚠️  LARGE FIX DETECTED

$ /ship --to-worktree

# Migrated to worktree
# Continue safely

Example 3: Direct Worktree Usage (from Main)

$ /ship "Large refactor" --worktree

# Starts in worktree
# No limits
# Complete isolation

Example 4: Direct Worktree Usage (from Worktree) - NEW!

# Cursor window open on worktrees/hotfix/
$ pwd
~/Documents/watchora/worktrees/hotfix

$ /ship "Large refactor"

# Auto-detects worktree context
# No --worktree flag needed
# Works in current directory

Example 5: Urgent Fix During Active Fix

# Fix in progress in worktree
$ /ship "Critical bug" --worktree

❌ Worktree busy

# Use Main instead
$ /ship "Critical bug"

# Quick fix on Main
# Worktree unaffected

Best Practices

When to Use Main

✅ Typos, small text changes ✅ 1-2 file modifications ✅ < 50 lines changed ✅ < 15 minutes work ✅ Low risk, obvious fix

When to Use Worktree

✅ Refactors ✅ Multiple files (5+) ✅ > 100 lines changed ✅ > 30 minutes work ✅ Need isolation ✅ Want separate Cursor window

Tips

💡 Start on Main, migrate if it grows
💡 Use worktree for anything "refactor"
💡 One worktree fix at a time = simple
💡 Urgent fixes on Main = no blocking

Integration

Works seamlessly with:

/worktree - Manage worktrees
/context - Shows current fix
/cleanup - Cleans up after merge
/hotfix - Alias for /ship --worktree

Version: 0.4.4 Plugin: claude-prd-workflow v0.4.4 Changes:

v0.4.4: Added automatic context detection - run from Main OR worktree directly
v0.4.3: Added worktree support, intelligent sync, collision handling

Install ship and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# 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 ```bash # Working directory: ~/Documents/watchora $ /ship "Fix auth bug" → Behavior: Works on Main (default) → Optional: Add --worktree to use hotfix worktree ``` ### From Hotfix Worktree ```bash # 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 ```bash # 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 ```bash $ /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: ```bash # 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 ```bash $ /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 ```bash $ /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 ```bash $ /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 ```bash # One-time setup: Open dedicated Cursor window cd ~/Documents/watchora/worktrees/hotfix/ code . # Opens Cursor in worktree directory ``` ### Step 1: Start Fix (from Worktree) ```bash # 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) ```bash # Still in worktrees/hotfix/ $ /ship --complete ✅ Committed & pushed 📤 PR #236 created ⏳ Waiting for checks... ✅ Checks passed, auto-merging 🎉 Merged to main # AUTO-CLEANUP 🔄 Returning to parking branch... 🧹 Deleted branch hotfix/fix-authentication-bug 🔄 Syncing with main... ✅ Worktree ready for next fix 🔓 Unlocked worktree 📍 Still in: worktrees/hotfix/ (ready for next fix) ``` **Advantage**: You stay in the same Cursor window the entire time! ## Collision Handling **One fix at a time** in hotfix worktree: ```bash $ /ship "Fix autre" --worktree ❌ Fix already in progress in worktrees/hotfix/ Current fix: hotfix/refactor-auth-module Started: 25 minutes ago Files: 7 modified ⚠️ Only ONE fix at a time in hotfix worktree Options: 1. Finish current fix: /ship --complete 2. Work on Main instead: /ship "Fix autre" 3. Abort current fix: /ship --abort 💡 For urgent small fixes, use Main: /ship "Fix autre" Choose: _ ``` ## Migration: Main → Worktree Started on Main but fix is growing: ```bash # Working on Main... ⚠️ LARGE FIX DETECTED (warning appears) $ /ship --to-worktree 🔄 Migrating to worktree... # Process: 1. ✅ Commit WIP on Main git add . git commit -m "WIP: Large fix" 2. ✅ Setup worktree hotfix/ Auto-sync if needed 3. ✅ Cherry-pick WIP to worktree cd worktrees/hotfix/ git checkout -b hotfix/large-fix git cherry-pick <wip-commit> 4. ✅ Reset Main cd main-repo/ git reset --hard HEAD~1 5. ✅ Continue in worktree 💻 Open: code worktrees/hotfix/ Migration complete! Continue working in worktrees/hotfix/ ``` ## State Management ### Lock File `.claude-lock` in `worktrees/hotfix/`: ```json { "status": "in_progress", "type": "hotfix", "branch": "hotfix/refactor-auth", "started_at": "2025-01-13T10:30:00Z", "started_by": "/ship --worktree", "description": "Refactor authentication module", "files_changed": 7, "lines_changed": 234, "commits": 3, "last_commit": "a3f2c1d Improve auth flow" } ``` ### Status Check ```bash $ /ship --status 📊 Current Fix Status ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📍 Location: worktrees/hotfix/ 📝 Branch: hotfix/refactor-auth-module ⏱️ Started: 25 minutes ago 📊 Progress: - Files: 7 modified - Lines: +234 -87 - Commits: 3 Recent commits: - a3f2c1d Improve auth flow - 8d4e2a9 Add tests - 1c8f3b2 Refactor middleware ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Actions: - /ship --complete (finish) - /ship --pause (save for later) - /ship --abort (cancel) ``` ## Pause & Resume ### Pause Fix ```bash $ /ship --pause 💾 Pausing fix... ✅ Committed WIP state 📝 Updated lock file (status: paused) 🔄 Returned to parking branch Fix paused. Resume with: /ship --resume ``` ### Resume Fix ```bash $ /ship --resume 📋 Paused fixes: 1. hotfix/refactor-auth-module Started: 2 hours ago Files: 7 modified Last: Improve auth flow Resume which fix? (1): 1 🔄 Resuming fix... ✅ Checked out branch: hotfix/refactor-auth-module 📊 Fix status loaded Continue working! ``` ## Configuration Respects `.claude/config-worktrees.json`: ```json { "worktrees": { "hotfix": { "path": "worktrees/hotfix", "branch_parking": "hotfix" } }, "warnings": { "files_threshold": 5, "lines_threshold": 100, "time_threshold_minutes": 30 }, "auto_complete": { "auto_merge_if_checks_pass": true, "cleanup_after_merge": true } } ``` ## Examples ### Example 1: Simple Fix on Main ```bash $ /ship "Fix typo in error message" # Small fix, 1 file, 2 lines # No warnings # Complete quickly $ /ship --complete ✅ Done! ``` ### Example 2: Fix Grows, Migrate to Worktree ```bash $ /ship "Fix dark mode issues" # Start on Main # After 20 min: 8 files, 150 lines ⚠️ LARGE FIX DETECTED $ /ship --to-worktree # Migrated to worktree # Continue safely ``` ### Example 3: Direct Worktree Usage (from Main) ```bash $ /ship "Large refactor" --worktree # Starts in worktree # No limits # Complete isolation ``` ### Example 4: Direct Worktree Usage (from Worktree) - NEW! ```bash # Cursor window open on worktrees/hotfix/ $ pwd ~/Documents/watchora/worktrees/hotfix $ /ship "Large refactor" # Auto-detects worktree context # No --worktree flag needed # Works in current directory ``` ### Example 5: Urgent Fix During Active Fix ```bash # Fix in progress in worktree $ /ship "Critical bug" --worktree ❌ Worktree busy # Use Main instead $ /ship "Critical bug" # Quick fix on Main # Worktree unaffected ``` ## Best Practices ### When to Use Main ✅ **Typos, small text changes** ✅ **1-2 file modifications** ✅ **< 50 lines changed** ✅ **< 15 minutes work** ✅ **Low risk, obvious fix** ### When to Use Worktree ✅ **Refactors** ✅ **Multiple files (5+)** ✅ **> 100 lines changed** ✅ **> 30 minutes work** ✅ **Need isolation** ✅ **Want separate Cursor window** ### Tips - 💡 Start on Main, migrate if it grows - 💡 Use worktree for anything "refactor" - 💡 One worktree fix at a time = simple - 💡 Urgent fixes on Main = no blocking ## Integration Works seamlessly with: - `/worktree` - Manage worktrees - `/context` - Shows current fix - `/cleanup` - Cleans up after merge - `/hotfix` - Alias for `/ship --worktree` --- **Version**: 0.4.4 **Plugin**: claude-prd-workflow v0.4.4 **Changes**: - v0.4.4: Added automatic context detection - run from Main OR worktree directly - v0.4.3: Added worktree support, intelligent sync, collision handling

{ "prompt": "# Quick Ship Command\n\nShip small features/fixes fast without full PRD overhead, with optional worktree isolation.\n\n## Purpose\n\nFor small changes that don't need full PRD:\n- Bug fixes\n- Small UI tweaks\n- Dependency updates\n- Minor refactors\n- Quick experiments\n\n**NEW in v0.4.4**: Automatic context detection - run from Main OR from worktree directly!\n**v0.4.3**: Support for worktree isolation with `--worktree` flag.\n\n## Context Detection (Auto)\n\nThe `/ship` command **automatically detects** where you run it from:\n\n### From Main Repository\n```bash\n# Working directory: ~/Documents/watchora\n$ /ship \"Fix auth bug\"\n→ Behavior: Works on Main (default)\n→ Optional: Add --worktree to use hotfix worktree\n```\n\n### From Hotfix Worktree\n```bash\n# Working directory: ~/Documents/watchora/worktrees/hotfix\n$ /ship \"Fix auth bug\"\n→ Behavior: Automatically uses worktree (no --worktree needed!)\n→ Syncs, locks, creates branch, works in current directory\n```\n\n**Key Point**: If you have a dedicated Cursor window open on `worktrees/hotfix/`, you can use `/ship` directly from there!\n\n## When to Use\n\n**Use Quick Ship for**:\n- Features < 4 hours\n- Single developer work\n- Clear scope, no unknowns\n- Low risk changes\n\n**Use Full PRD for**:\n- Features > 1 day\n- Multiple developers\n- Unclear requirements\n- High-risk changes\n- Customer-facing features\n\n## Usage\n\n```bash\n# From Main: Work on Main (quick, simple)\n/ship \"Fix login button alignment\"\n\n# From Main: With worktree isolation (safer, larger fixes)\n/ship \"Refactor auth module\" --worktree\n\n# From Worktree: Auto-detects worktree context\ncd worktrees/hotfix/\n/ship \"Fix auth bug\" # Automatically uses worktree!\n\n# Manage active fix (works from anywhere)\n/ship --complete # Finish and merge\n/ship --abort # Cancel fix\n/ship --status # Show current status\n/ship --pause # Pause current fix\n/ship --resume # Resume paused fix\n\n# Migrate from Main to worktree\n/ship --to-worktree # Move current fix to worktree\n```\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--worktree` | Use hotfix worktree for isolation |\n| `--to-worktree` | Migrate current fix from Main to worktree |\n| `--complete` | Complete current fix (commit + PR + merge) |\n| `--abort` | Abort current fix without merging |\n| `--status` | Show current fix status |\n| `--pause` | Pause fix and save state |\n| `--resume` | Resume paused fix |\n\n## Workflow: Default (Main)\n\n### Step 1: Start Fix on Main\n\n```bash\n$ /ship \"Fix dark mode toggle\"\n\n✅ Quick fix on Main\n📝 Branch: quickship/fix-dark-mode-toggle\n\n💡 Working on Main - keep it small!\n```\n\n### Step 2: Guided Implementation\n\nAI provides inline guidance for the fix:\n- File locations\n- Code changes\n- Testing approach\n\n### Step 3: Smart Warnings\n\nAs you work, smart detection monitors:\n\n```bash\n# After 20 minutes, 8 files, 150 lines...\n\n⚠️ LARGE FIX DETECTED\n- 8 files changed\n- 150 lines modified\n- 22 minutes elapsed\n\n💡 This is getting large. Consider:\n 1. /ship --complete (finish on Main)\n 2. /ship --to-worktree (migrate to worktree)\n 3. Continue on Main (suppress warning)\n\nChoose: _\n```\n\n**Thresholds**:\n- Files: > 5 files\n- Lines: > 100 lines\n- Time: > 30 minutes\n\n### Step 4: Complete Fix\n\n```bash\n$ /ship --complete\n\n✅ Committed: fix: Dark mode toggle improvements\n📤 PR #234 created\n⏳ Waiting for checks...\n✅ Checks passed, auto-merged\n🎉 Merged to main\n🧹 Cleaned up branch\n```\n\n## Workflow: With Worktree (from Main)\n\n### Step 1: Start Fix in Worktree\n\n```bash\n$ /ship \"Refactor authentication module\" --worktree\n\n🔍 Checking worktree hotfix/...\n\n# AUTO-SYNC (Intelligent)\n🔄 Syncing worktree (3 commits behind)...\n\nRecent changes:\n - a3f2c1d fix: OAuth timeout\n - 8d4e2a9 feat: Better logging\n - 1c8f3b2 refactor: API cleanup\n\n✅ Synced with main\n\n# START FIX\n✅ Started in worktrees/hotfix/\n📝 Branch: hotfix/refactor-auth-module\n🔒 Locked worktree (one fix at a time)\n\n💻 Open in new window: code worktrees/hotfix/\n```\n\n**Auto-sync thresholds**:\n- 0 commits: ✅ No sync needed\n- 1-10 commits: 🔄 Silent auto-sync\n- 10-50 commits: ⚠️ Propose sync with preview\n- 50+ commits: ❌ Force sync (required)\n\n### Step 2: Isolated Development\n\nWork in `worktrees/hotfix/`:\n- No size limits\n- No time warnings\n- Complete isolation\n- Can open in separate Cursor window\n\n### Step 3: Complete Fix\n\n```bash\n$ /ship --complete\n\n✅ Committed & pushed\n📤 PR #235 created\n⏳ Waiting for checks...\n✅ Checks passed, auto-merging\n🎉 Merged to main\n\n# AUTO-CLEANUP\n🔄 Returning to parking branch...\n🧹 Deleted branch hotfix/refactor-auth-module\n🔄 Syncing with main...\n✅ Worktree ready for next fix\n🔓 Unlocked worktree\n\n↩️ Returned to Main\n```\n\n## Workflow: From Worktree Directly (NEW in v0.4.4)\n\n### Setup: Open Cursor Window on Worktree\n\n```bash\n# One-time setup: Open dedicated Cursor window\ncd ~/Documents/watchora/worktrees/hotfix/\ncode . # Opens Cursor in worktree directory\n```\n\n### Step 1: Start Fix (from Worktree)\n\n```bash\n# You're already in worktrees/hotfix/\n$ pwd\n~/Documents/watchora/worktrees/hotfix\n\n# Run /ship directly - no --worktree flag needed!\n$ /ship \"Fix authentication bug\"\n\n🔍 Detected: Running from worktree hotfix/\n🎯 Auto-enabling worktree mode\n\n# AUTO-SYNC (Intelligent)\n🔄 Checking sync status...\n✅ Synced with main (or auto-sync if needed)\n\n# START FIX\n✅ Started in current directory\n📝 Branch: hotfix/fix-authentication-bug\n🔒 Locked worktree (one fix at a time)\n\n💡 Working in worktree - no limits!\n```\n\n### Step 2: Development (Same Directory)\n\nYou work in the **same directory** where you launched `/ship`:\n- Already in `worktrees/hotfix/`\n- All your tools/extensions work normally\n- Commit as you go\n- No need to switch directories\n\n### Step 3: Complete Fix (from Worktree)\n\n```bash\n# Still in worktrees/hotfix/\n$ /ship --complete\n\n✅ Committed & pushed\n📤 PR #236 created\n⏳ Waiting for checks...\n✅ Checks passed, auto-merging\n🎉 Merged to main\n\n# AUTO-CLEANUP\n🔄 Returning to parking branch...\n🧹 Deleted branch hotfix/fix-authentication-bug\n🔄 Syncing with main...\n✅ Worktree ready for next fix\n🔓 Unlocked worktree\n\n📍 Still in: worktrees/hotfix/ (ready for next fix)\n```\n\n**Advantage**: You stay in the same Cursor window the entire time!\n\n## Collision Handling\n\n**One fix at a time** in hotfix worktree:\n\n```bash\n$ /ship \"Fix autre\" --worktree\n\n❌ Fix already in progress in worktrees/hotfix/\n\nCurrent fix: hotfix/refactor-auth-module\nStarted: 25 minutes ago\nFiles: 7 modified\n\n⚠️ Only ONE fix at a time in hotfix worktree\n\nOptions:\n1. Finish current fix: /ship --complete\n2. Work on Main instead: /ship \"Fix autre\"\n3. Abort current fix: /ship --abort\n\n💡 For urgent small fixes, use Main:\n /ship \"Fix autre\"\n\nChoose: _\n```\n\n## Migration: Main → Worktree\n\nStarted on Main but fix is growing:\n\n```bash\n# Working on Main...\n⚠️ LARGE FIX DETECTED (warning appears)\n\n$ /ship --to-worktree\n\n🔄 Migrating to worktree...\n\n# Process:\n1. ✅ Commit WIP on Main\n git add .\n git commit -m \"WIP: Large fix\"\n\n2. ✅ Setup worktree hotfix/\n Auto-sync if needed\n\n3. ✅ Cherry-pick WIP to worktree\n cd worktrees/hotfix/\n git checkout -b hotfix/large-fix\n git cherry-pick <wip-commit>\n\n4. ✅ Reset Main\n cd main-repo/\n git reset --hard HEAD~1\n\n5. ✅ Continue in worktree\n 💻 Open: code worktrees/hotfix/\n\nMigration complete!\nContinue working in worktrees/hotfix/\n```\n\n## State Management\n\n### Lock File\n\n`.claude-lock` in `worktrees/hotfix/`:\n\n```json\n{\n \"status\": \"in_progress\",\n \"type\": \"hotfix\",\n \"branch\": \"hotfix/refactor-auth\",\n \"started_at\": \"2025-01-13T10:30:00Z\",\n \"started_by\": \"/ship --worktree\",\n \"description\": \"Refactor authentication module\",\n \"files_changed\": 7,\n \"lines_changed\": 234,\n \"commits\": 3,\n \"last_commit\": \"a3f2c1d Improve auth flow\"\n}\n```\n\n### Status Check\n\n```bash\n$ /ship --status\n\n📊 Current Fix Status\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n📍 Location: worktrees/hotfix/\n📝 Branch: hotfix/refactor-auth-module\n⏱️ Started: 25 minutes ago\n📊 Progress:\n - Files: 7 modified\n - Lines: +234 -87\n - Commits: 3\n\nRecent commits:\n - a3f2c1d Improve auth flow\n - 8d4e2a9 Add tests\n - 1c8f3b2 Refactor middleware\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nActions:\n - /ship --complete (finish)\n - /ship --pause (save for later)\n - /ship --abort (cancel)\n```\n\n## Pause & Resume\n\n### Pause Fix\n\n```bash\n$ /ship --pause\n\n💾 Pausing fix...\n\n✅ Committed WIP state\n📝 Updated lock file (status: paused)\n🔄 Returned to parking branch\n\nFix paused. Resume with: /ship --resume\n```\n\n### Resume Fix\n\n```bash\n$ /ship --resume\n\n📋 Paused fixes:\n\n1. hotfix/refactor-auth-module\n Started: 2 hours ago\n Files: 7 modified\n Last: Improve auth flow\n\nResume which fix? (1): 1\n\n🔄 Resuming fix...\n✅ Checked out branch: hotfix/refactor-auth-module\n📊 Fix status loaded\n\nContinue working!\n```\n\n## Configuration\n\nRespects `.claude/config-worktrees.json`:\n\n```json\n{\n \"worktrees\": {\n \"hotfix\": {\n \"path\": \"worktrees/hotfix\",\n \"branch_parking\": \"hotfix\"\n }\n },\n \"warnings\": {\n \"files_threshold\": 5,\n \"lines_threshold\": 100,\n \"time_threshold_minutes\": 30\n },\n \"auto_complete\": {\n \"auto_merge_if_checks_pass\": true,\n \"cleanup_after_merge\": true\n }\n}\n```\n\n## Examples\n\n### Example 1: Simple Fix on Main\n\n```bash\n$ /ship \"Fix typo in error message\"\n\n# Small fix, 1 file, 2 lines\n# No warnings\n# Complete quickly\n\n$ /ship --complete\n\n✅ Done!\n```\n\n### Example 2: Fix Grows, Migrate to Worktree\n\n```bash\n$ /ship \"Fix dark mode issues\"\n\n# Start on Main\n# After 20 min: 8 files, 150 lines\n\n⚠️ LARGE FIX DETECTED\n\n$ /ship --to-worktree\n\n# Migrated to worktree\n# Continue safely\n```\n\n### Example 3: Direct Worktree Usage (from Main)\n\n```bash\n$ /ship \"Large refactor\" --worktree\n\n# Starts in worktree\n# No limits\n# Complete isolation\n```\n\n### Example 4: Direct Worktree Usage (from Worktree) - NEW!\n\n```bash\n# Cursor window open on worktrees/hotfix/\n$ pwd\n~/Documents/watchora/worktrees/hotfix\n\n$ /ship \"Large refactor\"\n\n# Auto-detects worktree context\n# No --worktree flag needed\n# Works in current directory\n```\n\n### Example 5: Urgent Fix During Active Fix\n\n```bash\n# Fix in progress in worktree\n$ /ship \"Critical bug\" --worktree\n\n❌ Worktree busy\n\n# Use Main instead\n$ /ship \"Critical bug\"\n\n# Quick fix on Main\n# Worktree unaffected\n```\n\n## Best Practices\n\n### When to Use Main\n\n✅ **Typos, small text changes**\n✅ **1-2 file modifications**\n✅ **< 50 lines changed**\n✅ **< 15 minutes work**\n✅ **Low risk, obvious fix**\n\n### When to Use Worktree\n\n✅ **Refactors**\n✅ **Multiple files (5+)**\n✅ **> 100 lines changed**\n✅ **> 30 minutes work**\n✅ **Need isolation**\n✅ **Want separate Cursor window**\n\n### Tips\n\n- 💡 Start on Main, migrate if it grows\n- 💡 Use worktree for anything \"refactor\"\n- 💡 One worktree fix at a time = simple\n- 💡 Urgent fixes on Main = no blocking\n\n## Integration\n\nWorks seamlessly with:\n- `/worktree` - Manage worktrees\n- `/context` - Shows current fix\n- `/cleanup` - Cleans up after merge\n- `/hotfix` - Alias for `/ship --worktree`\n\n---\n\n**Version**: 0.4.4\n**Plugin**: claude-prd-workflow v0.4.4\n**Changes**:\n- v0.4.4: Added automatic context detection - run from Main OR worktree directly\n- v0.4.3: Added worktree support, intelligent sync, collision handling", "variables": [], "notes": "Fast-track small features without full PRD process", "metadata": { "source": { "provider": "github-claude-commands", "repository": "https://github.com/Yassinello/claude-plugin-prd-workflow", "path": ".claude/commands/ship.md", "ref": "2cd4673b6e457e5e1be4fe8af8c7395438fd11da", "url": "https://github.com/Yassinello/claude-plugin-prd-workflow/blob/2cd4673b6e457e5e1be4fe8af8c7395438fd11da/.claude/commands/ship.md", "key": "Yassinello/claude-plugin-prd-workflow/.claude/commands/ship.md" } } }

About