# Publish Issue

> Publish a plan as a GitHub Issue and create a branch to start implementation

- Skill: `majiayu000/publish-issue-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/publish-issue-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/publish-issue-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/publish-issue-2

---


# 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

```bash
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

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

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

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

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

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

Example configurations:
- `PROJECT_PREFIX=myapp`
- `PROJECT_PREFIX=builtby-win-web`