| name | github-issue-workflow |
| description | Standard workflow for creating GitHub issues with assignment and worktree branch creation for immediate implementation. Includes branch strategy and worktree conventions. |
| keywords | issue, github, workflow, worktree, branch, assign, implementation, create issue, new issue, bug report, feature request, staging |
| related | git-commit-discipline, pre-push, post-push, pr-lifecycle |
GitHub Issue Workflow
End-to-end workflow for creating a GitHub issue and immediately setting up for implementation.
Workflow
1. Create the issue
Use gh issue create with a structured body:
gh issue create --title "Short descriptive title" --body "$(cat <<'EOF'
## Summary
Brief description of the feature/bug.
## Implementation Plan
### Phase A: Design (ADR if needed)
### Phase B: Implementation
### Phase C: Testing & PR
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Labels
enhancement, area: core, ...
EOF
)" --label "enhancement" --label "area: core"
2. Assign the issue
Always assign to the project owner immediately:
gh issue edit {number} --add-assignee "$(gh api user --jq .login)"
3. Create a worktree branch
Use EnterWorktree with a descriptive name matching the feature:
EnterWorktree(name: "feat-short-description")
Name rules: letters, digits, dots, underscores, dashes only. No + or /.
4. Implement
Follow the issue's implementation plan:
- Write ADR if
needs adr label is present
- Implement the feature
- Write tests
- Run [[pre-push]]
- Create PR into
staging, then run [[post-push]]
5. Create PR into staging
gh pr create --base staging --title "feat: short description" --body "$(cat <<'EOF'
## Summary
- What was done
## Test plan
- [ ] Tests pass
- [ ] Manual verification
Closes #N
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
6. Update a PR description
gh pr edit is broken (GitHub Projects Classic deprecation GraphQL error). Use the REST API instead:
gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f body="new body here"
For title changes:
gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f title="new title"
Branch Strategy
| Change type | Target branch | Example |
|---|
| Feature / fix | staging | gh pr create --base staging |
| Hotfix (production broken) | main | Direct to main, then backport to staging |
| Docs-only | main | No staging needed for docs |
After a staging PR is merged and validated, create a "Staging → Main" merge PR (see [[pr-lifecycle]]).
Worktree Conventions
Naming: Use descriptive names with letters, digits, dots, underscores, dashes only. No + or /.
| Pattern | When to use | Example |
|---|
feat-{description} | New features | feat-token-tracking |
fix-issue-{N}-{description} | Issue-linked fixes | fix-issue-31-broaden-scanner |
fix-{description} | Fixes without issues | fix-toast-overlap |
Optimization: Don't re-read files after entering a worktree. Worktrees clone HEAD — files read before EnterWorktree are identical in the worktree. Use content already in context.
Cleanup: Worktrees are cleaned up automatically if the agent makes no changes. If changes are made, the worktree path and branch are returned in the result.
Checklist
