Pickup

Pickup Issue

Overview

Pick up a GitHub issue created by brainstorming. Creates a worktree, loads context, and automatically continues to execution if a plan exists.

Announce at start: "I'm using pickup to implement issue #."

Arguments

Process

Step 1: Fetch Issue Details

gh issue view <issue-number> --json title,body,labels,state

Parse the response to extract:

• Title (for branch naming)
• Body (for linked spec path)
• Labels (for context)
• State (to verify it's open)

Step 2: Set Issue to In Progress

Mark the issue as being actively worked on:

# Add "in progress" label (create if doesn't exist)
gh issue edit <issue-number> --add-label "in progress"

# If your project uses GitHub Projects, move to "In Progress" column
# gh project item-edit --project-id <id> --id <item-id> --field-id <status-field> --single-select-option-id <in-progress-id>

# Add a comment to track when work started
gh issue comment <issue-number> --body "🚀 Started working on this issue in branch \`feature/$TOPIC\`"

Step 3: Extract Feature Branch

Look for the "Feature Branch" section in the issue body:

## Feature Branch

`feature/42-add-user-authentication` — spec is committed here, ready for implementation

Extract the branch name: feature/42-add-user-authentication

Also extract the spec path from the "Linked Spec" section (points to file on the branch).

Step 4: Fetch Feature Branch

The feature branch was created by brainstorming and contains the spec. Fetch it:

# Fetch the feature branch from remote
git fetch origin feature/<issue-number>-<topic>

# Extract topic for worktree directory name
TOPIC="<issue-number>-<topic>"
BRANCH="feature/$TOPIC"

Step 5: Create Worktree from Existing Branch

Use using-git-worktrees. Worktrees are ALWAYS created in .worktrees/ — no exceptions.

# Ensure .worktrees/ is gitignored
grep -q "^\.worktrees/$" .gitignore 2>/dev/null || echo ".worktrees/" >> .gitignore

# Create worktree from EXISTING remote branch (not -b for new branch)
# ALWAYS in .worktrees/ - never use /tmp or other locations
git worktree add .worktrees/$TOPIC origin/$BRANCH

# Copy Claude settings to worktree
cp -r .claude .worktrees/$TOPIC/

Note: We use origin/$BRANCH without -b because the branch already exists on remote (created by brainstorming).

Step 5b: Merge Permissions (REQUIRED)

After copying .claude/, merge Required permissions into the worktree's settings.

Read .worktrees/$TOPIC/.claude/settings.local.json and ensure these permissions exist in allow:

{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(**)",
      "Edit(**)",
      "Write(**)",
      "Grep",
      "Glob",
      "WebFetch",
      "WebSearch",
      "Task",
      "Skill(*)",
      "mcp__chrome-devtools__*"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/.env)",
      "Read(**/.env.*)"
    ]
  }
}

Merge logic:

1. Read existing settings.local.json if present
2. For each permission above, check if it exists in allow
3. If missing, add it to the allow array
4. Preserve all existing user permissions (don't remove anything)
5. Merge deny arrays (union of both)
6. Write the merged result back

This ensures workflows work while keeping user customizations.

# Navigate to worktree
cd .worktrees/$TOPIC

Step 6: Load Context

1. Read the linked spec document — Contains both design AND implementation tasks
2. Detect project stack — Auto-load relevant stack profiles
3. Check for Implementation Plan section — Verify spec has tasks to execute

Step 7: Report Ready State and Continue

"Workspace ready for issue #:

The spec was created during brainstorming and is already committed to the feature branch."

Step 8: Auto-Continue to Execution

If spec has Implementation Plan section AND not --plan-only:

• Announce: "Spec has implementation tasks. Continuing with execution..."
• Invoke executing-plans with the spec path
• Continue through the full implementation

If spec has no Implementation Plan section:

• Stop and report: "Spec has no implementation tasks. Add them first: writing-plans <spec-path>"

If --plan-only flag:

• Stop after setup, let user decide next step

Error Handling

Issue Not Found

Issue #<number> not found.

Check:
- Is the issue number correct?
- Do you have access to the repository?

Run `gh issue list` to see available issues.

No Feature Branch

Issue #<number> has no feature branch specified.

This issue may not have been created with brainstorming.

Options:
1. Create spec and branch manually:
   brainstorming (start fresh)

2. Work directly from issue description:
   git checkout -b feature/<number>-<topic>
   git worktree add .worktrees/<topic> feature/<number>-<topic>

Feature Branch Not Found on Remote

Feature branch not found: feature/<number>-<topic>

The branch may have been deleted or not pushed.

Check:
- git branch -r | grep <topic>
- Was the brainstorming completed successfully?

To create the branch manually:
  git checkout -b feature/<number>-<topic>
  git push -u origin feature/<number>-<topic>

Worktree Already Exists

Worktree for this issue already exists at: .worktrees/<topic>

To continue working:
  cd .worktrees/<topic>

To start fresh:
  git worktree remove .worktrees/<topic>
  Then run pickup <number> again

Spec File Not Found

Linked spec not found: <path>

The spec may have been moved or deleted. Check:
- `docs/plans/` for similar files
- Git history for the file

Or create a new spec with brainstorming.

Spec Has No Implementation Tasks

Spec found but has no Implementation Plan section: <path>

The spec only contains design, not implementation tasks.

To add tasks:
  writing-plans <spec-path>

Stack Detection and Loading

After creating the worktree, detect and load stack profiles:

Step 1: Run Detection Script

# Stack detection is handled automatically by instruction file applyTo globs

Or manually detect by checking for:

Step 2: Read Detected Stack Profiles

For each detected stack, read the profile from .github/instructions/<stack-name>.md:

# Example: If dotnet, react, postgresql detected
cat .github/instructions/dotnet.instructions.md
cat .github/instructions/react.instructions.md
cat .github/instructions/postgresql.instructions.md

Step 3: Extract Key Information

From each stack profile, note:

• Common mistakes — Avoid these during implementation
• Best practices — Follow these patterns
• Review checklist — Will be checked during review

Keep this context loaded for the implementation phase.