@pleaseai/gh-please-docs
Workflows

Issue Development Workflow

Best practices for issue-driven development with gh-please

Issue Development Workflow

Follow this standardized workflow for all feature development and bug fixes using gh-please.

Overview

┌─────────────────────────────────────┐
│ 1. Create issue branch              │
│    gh please issue develop <number> │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ 2. Work in isolated worktree        │
│    cd ~/.please/worktrees/...       │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ 3. Follow TDD cycle                 │
│    Red → Green → Refactor → Commit  │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│ 4. Commit, Push, and Create PR      │
│    git commit → git push → gh pr    │
└─────────────────────────────────────┘

Step 1: Create Issue Branch

Start working on an issue with automatic worktree creation:

gh please issue develop <issue-number>

This command:

  1. Checks if bare repo exists at ~/.please/repositories/{owner}/{repo}.git
  2. If not, prompts to clone as bare repository
  3. Creates worktree at ~/.please/worktrees/{repo}/{branch}
  4. Links branch to issue via gh issue develop

Example:

# Start working on issue #123
gh please issue develop 123

# Output shows where to go
# cd ~/.please/worktrees/gh-please/feat-123-awesome-feature

# Navigate to worktree
cd ~/.please/worktrees/gh-please/feat-123-awesome-feature

Options:

# Use custom base branch
gh please issue develop 123 --base develop

# Use custom branch name
gh please issue develop 123 --name my-custom-branch

# From outside git repo
gh please issue develop 123 --repo owner/repo

Step 2: Work in Isolated Worktree

Benefits of worktree-based development:

✅ Isolated workspace - Each issue has its own directory ✅ No branch switching - Work on multiple issues simultaneously ✅ Clean state - No risk of mixing changes ✅ Efficient disk usage - Shared Git objects

Example workflow:

# Terminal 1: Work on feature
cd ~/.please/worktrees/gh-please/feat-123-feature
code .

# Terminal 2: Fix urgent bug
cd ~/.please/worktrees/gh-please/fix-124-bug
code .

# No branch switching needed!

Step 3: Follow TDD Cycle

Implement changes following Test-Driven Development:

Red Phase: Write Failing Test

# Write test that defines desired behavior
bun test --watch

Green Phase: Implement Minimum Code

# Make the test pass with simplest solution

Refactor Phase: Improve Code

# Improve structure while keeping tests passing
bun run lint:fix
bun run type-check

Commit Phase: Save Progress

# Small, focused commits
git add .
git commit -m "feat: add validation logic"

Key commands:

# Run tests continuously
bun test --watch

# Run all quality checks
bun run lint:fix && bun run type-check && bun test

Step 4: Commit, Push, and Create PR

Once implementation is complete:

# Stage changes
git add .

# Create commit following conventional commit format
git commit -m "feat: brief description"

# Push to remote
git push -u origin <branch-name>

# Create pull request
gh pr create --title "Title" --body "Description"

Or use the shorthand:

# Commit, push, and create PR in one command
/commit-commands:commit-push-pr

Step 5: Cleanup After Merge

Once PR is merged and branch is deleted:

# Remove worktree interactively
gh please issue cleanup

# Or remove all prunable worktrees
gh please issue cleanup --all

Working with Sub-Issues

Break down large issues into manageable sub-tasks:

# Create parent issue #100: "Implement user authentication"

# Create sub-issues
gh please issue sub-issue create 100 --title "Add login form"
gh please issue sub-issue create 100 --title "Add session management"
gh please issue sub-issue create 100 --title "Add password reset"

# List all sub-issues
gh please issue sub-issue list 100

# Work on each sub-issue separately
gh please issue develop 101  # Login form
gh please issue develop 102  # Session management

Managing Dependencies

Handle dependencies between issues:

# Issue #200 depends on #199
gh please issue dependency add 200 --blocked-by 199

# Check blockers before starting work
gh please issue dependency list 200

# Remove dependency when blocker is resolved
gh please issue dependency remove 200 199

Best Practices

1. Small, Focused Issues

  • Break large tasks into sub-issues
  • Each issue should be completable in 1-3 days
  • Clear acceptance criteria

2. Descriptive Branch Names

Let gh issue develop create branches automatically with issue context:

  • feat-123-add-authentication
  • fix-456-validation-error

3. Regular Commits

  • Commit after each red-green-refactor cycle
  • Use conventional commit messages
  • Keep commits small and focused

4. Clean Worktrees

  • Remove worktrees after PR merge
  • Run gh please issue cleanup regularly
  • Keep ~/.please/worktrees/ organized

5. Link Issues and PRs

  • Create PR with gh pr create
  • Reference issue in PR description: "Closes #123"
  • Link sub-issues to parent

Troubleshooting

Worktree Already Exists

# Error: worktree already exists

# Option 1: Navigate to existing worktree
cd ~/.please/worktrees/gh-please/feat-123-feature

# Option 2: Remove and recreate
gh please issue cleanup
gh please issue develop 123

Bare Repo Not Found

# First run will prompt to clone
gh please issue develop 123
# Would you like to clone? (y/n)

Want to Use Checkout Instead

# Use traditional checkout in current repo
gh please issue develop 123 --checkout

Related

Plugin System

Extend gh-please with custom plugins

PR Review Workflow

Handle code review feedback efficiently with gh-please