GitHub Workflow

A structured four-phase workflow for feature development.

When to use

Follow this four-phase process when starting a new feature or fix that benefits from a structured plan-implement-review-merge workflow with reviewer collaboration.

The pattern

Quick reference

Phase	Trigger	Output
Plan	"plan issue #N"	GitHub issue with plan
Implement	"implement issue #N"	PR with incremental commits
Review	"review PR #N"	All comments addressed
Merge	"merge PR #N"	Clean merge, cleanup done

Phase 1: Plan in GitHub issue

Collaborate with the user on a plan in a GitHub issue before writing any code.

Identifying the issue

Get the issue number from arguments, chat history, or ask the user.

Rules

• Do ALL work in the GitHub issue
• Do NOT create branches or worktrees
• Do NOT modify any files in the codebase
• Stay in the issue until the user approves the plan

Structure the plan

Structure it as a target convergence prompt with clear acceptance criteria.

Do not proliferate comments

When iterating on the plan:

• Do NOT create new comments for every iteration
• MODIFY existing comments using gh api -X PATCH
• Create new comments only to separate topics

Carefully modify comments

1. Read the existing comment completely first
2. Understand what's already there
3. Make surgical edits to specific sections
4. Preserve everything that doesn't need to change
5. Only do a full rewrite if the user explicitly asks

After every round

Share the issue link with the user.

When done

Tell the user the plan is ready and ask if they want to proceed to implementation (Phase 2).

Phase 2: Implement

Implement the plan from the GitHub issue in a dedicated worktree branch.

Setup

Check if a worktree exists for this issue. If not, create one following git-worktrees guidance. Work in the worktree, not in main.

Implementation

1. Read the plan from the GitHub issue
2. Implement each acceptance criterion
3. Test your implementation
4. Commit your changes

When done (Phase 2)

Automatically create a pull request:

1. Push the branch
2. Create the PR
3. Share the PR link with the user

Rules (Phase 2)

• Work in the worktree, never in main
• Create the PR automatically when done
• Share the PR link

Phase 3: Review via pull request

Address ALL review comments on the pull request.

Finding all comments

Use GraphQL reviewThreads query to find ALL comments. This includes outdated comments — never ignore them.

Addressing each comment

For each comment:

1. View the code context (diff hunk)
2. Read the full conversation thread
3. Make the requested change
4. Reply to the comment with "Done"

After every round (Phase 3)

1. Commit your changes
2. Push
3. Share the PR link and provide:
   • Brief summary of changes made
   • Confirmation you replied to all comments

Rules (Phase 3)

• Address ALL comments including outdated ones
• Reply to EVERY comment you addressed
• Share the PR link after EVERY round
• Use GraphQL to find ALL comments

Phase 4: Merge and clean up

Merge the branch and clean up.

Merge

Use gh pr merge to merge the PR. This properly marks the PR as merged in GitHub (not just closed).

If there's no PR, navigate to main and use git merge.

If merge conflicts occur

Follow conflict resolution patterns:

• Patch Replay — regenerate changes on updated base
• Commit Replay — replay commits one by one

Clean up

After merge succeeds:

1. Remove the worktree: git worktree remove .worktrees/<name>
2. Delete the local branch: git branch -d <name>
3. Delete the remote branch: git push origin --delete <name>
4. Pull main: git pull (from the main worktree)

Do not rely on gh pr merge --delete-branch to delete branches — it often fails silently when a worktree is attached. Always delete explicitly.

Rules (Phase 4)

• Use gh pr merge (not git merge) so GitHub tracks it as merged
• Merge first, clean up after
• Use conflict resolution patterns if conflicts occur

When done (Phase 4)

Confirm with user that merge and cleanup are complete.