github-issue-workflow

Starting work on a GitHub issue

One issue → one owner → one draft PR, linked both ways. The point is that ownership and in-flight work are visible to everyone from the moment work starts, so two people never unknowingly build the same thing.

1. Before starting: is it already taken?

Never open a second branch or PR for an issue someone already owns. Check first:

gh issue view N                                              # assignee + linked PRs
gh pr list --state open --search "N in:body" \
  --json number,title,isDraft,url,headRefName

If the issue is already assigned, or an open PR (draft or not) already references it, it is taken. Stop — report what you found and coordinate with the owner, or pick a different issue. Do not start parallel work.

2. Claim the issue

Assignment is the ownership signal:

gh issue edit N --add-assignee @me      # or the relevant GitHub login

3. Set up an isolated worktree, then open a draft PR immediately

Work in a dedicated git worktree, never the shared root checkout: another Claude session may drive this checkout concurrently, and a stray checkout between two of your commands silently moves HEAD — your commit then lands on main instead of your branch. Branching from a freshly fetched origin/main into a new worktree also gives you a clean, up-to-date starting point in one move.

Open the PR before the work is finished, so the issue↔PR link exists from the start. GitHub needs at least one commit on the branch to open a PR:

git fetch origin
git branch <type>/<short-slug> origin/main                            # feat/ fix/ docs/ chore/ refactor/
git worktree add .claude/worktrees/<type>+<slug> <type>/<short-slug>  # slug = branch with / → +
cd .claude/worktrees/<type>+<slug>   # stay here: run all edits, git, and builds from inside

git commit --allow-empty -m "chore: start #N"     # or your first real commit
git push -u origin <type>/<short-slug>
gh pr create --draft --base main \
  --title "<type>: <summary>" \
  --body "Closes #N"