Publish Issue

Ship - Publish Plan to GitHub Issue

Convert a finalized plan into a GitHub Issue and set up the branch for implementation.

When to Use

• After plan mode is complete and user approves the plan
• Claude should run this AUTOMATICALLY when a plan is approved
• Can also be invoked manually with /ship

Workflow

Step 1: Find the Plan File

Look for the current plan file in ~/.claude/plans/ or check the conversation context for the plan content.

Step 2: Determine Issue Title

Extract a concise title from the plan. Format: feat: {brief description} or fix: {brief description}

Step 3: Create GitHub Issue

gh issue create \
  --title "feat: {title}" \
  --body "## Summary
{brief 1-2 sentence summary}

## Implementation Plan
{plan content - files to modify, approach, etc.}

## Files to Modify
- path/to/file1.ts
- path/to/file2.ts
" \
  --assignee @me \
  --label "status:in-progress"

Step 4: Parse Issue Number

The gh issue create command outputs the issue URL. Extract the issue number from it.

Step 5: Create Branch

# Create branch with naming convention
git checkout -b {PROJECT_PREFIX}/issue-{N}-{slug}

# Push to remote
git push -u origin {PROJECT_PREFIX}/issue-{N}-{slug}

Branch naming:

• Format: {PROJECT_PREFIX}/issue-{number}-{brief-slug}
• Slug: lowercase, hyphens, max 30 chars
• Example: myproject/issue-15-dark-mode

Step 6: Create Worktree (If Available)

Check if the project has worktree management installed:

# Check if scripts/manage-worktree.ts exists
if [ -f "scripts/manage-worktree.ts" ]; then
  # Detect package manager
  if [ -f "pnpm-lock.yaml" ]; then
    PKG_MANAGER="pnpm"
  elif [ -f "yarn.lock" ]; then
    PKG_MANAGER="yarn"
  else
    PKG_MANAGER="npm"
  fi

  # Extract slug from branch name
  SLUG=$(echo "{PROJECT_PREFIX}/issue-{N}-{slug}" | sed 's/.*issue-[0-9]*-//')

  # Create worktree with dev server
  case $PKG_MANAGER in
    pnpm) pnpm worktree create {N} ${SLUG} --start-server ;;
    yarn) yarn worktree create {N} ${SLUG} --start-server ;;
    npm) npm run worktree create {N} ${SLUG} --start-server ;;
  esac

  WORKTREE_CREATED=1
fi

If worktree was created, it will:

• Create .worktrees/issue-{N}-{slug}/ directory
• Snapshot SQLite database(s) for isolated state
• Assign next available port (e.g., 4322)
• Start dev server automatically
• Symlink node_modules to save disk space

Step 7: Clean Up Plan File

# Delete the local plan file (now lives in GitHub)
rm ~/.claude/plans/{plan-file}.md

Step 8: Announce

Output:

Created issue #{N}: feat: {title}
{Issue URL}

Branch: {PROJECT_PREFIX}/issue-{N}-{slug}
Status: in-progress

Ready to implement!

If worktree was created, also include:

Worktree created:
  Path: .worktrees/issue-{N}-{slug}
  Port: {PORT}
  Dev server: http://localhost:{PORT} (started)
  Database: {N} snapshot(s)

Navigate to worktree:
  cd .worktrees/issue-{N}-{slug}

If worktree was NOT created (no scripts/manage-worktree.ts), suggest installation:

💡 Tip: Install worktree management for parallel development with isolated databases.
   Run: /setup-worktree

For Existing Issues

If working on an existing issue (user said "work on #N"), update that issue instead:

# Append plan to existing issue body
gh issue edit {N} --body "$(gh issue view {N} --json body -q '.body')

---

## Implementation Plan (added by Claude)
{plan content}

## Files to Modify
- path/to/file1.ts
"

# Add in-progress label
gh issue edit {N} --add-label "status:in-progress"

# Create branch
git checkout -b {PROJECT_PREFIX}/issue-{N}-{slug}
git push -u origin {PROJECT_PREFIX}/issue-{N}-{slug}

# Create worktree (if project supports it)
# Project-specific command here

Output:

Updated issue #{N} with implementation plan.
Branch: {PROJECT_PREFIX}/issue-{N}-{slug}
Status: in-progress

Ready to implement!

Configuration

In your project's CLAUDE.md, set:

## GitHub Workflow Configuration
PROJECT_PREFIX=your-project-name

Example configurations:

• PROJECT_PREFIX=myapp
• PROJECT_PREFIX=builtby-win-web