Load a GitHub issue, create an isolated worktree, plan the implementation, and submit a PR. Use when asked to fix, implement, or work on a GitHub issue by number...
Plan, implement, and submit a PR for a GitHub issue using git worktrees for isolation.
Codex note: This skill references Claude Code subagents (Task(...)). In Codex, run the equivalent steps with tool calls (for example functions.shell_command and multi_tool_use.parallel) or run them sequentially. See ../../COMPATIBILITY.md.
Before anything else, create an isolated worktree for this issue:
scripts/setup-worktree.sh $ISSUE_NUMBER
This will:
.worktrees/issue-$ISSUE_NUMBERissue-$ISSUE_NUMBERAll subsequent work happens in the worktree, keeping your main repo clean.
Options:
--no-worktree: Work directly on a branch without creating a worktree (useful for simple changes)Note: The script auto-adds .worktrees/ to .gitignore.
If setup fails:
gh auth logingit remote add origin <url>scripts/load-issue.sh $ISSUE_NUMBER
Fetches issue details, comments, labels, and related PRs.
From the output, identify:
Locate affected files and review current implementation. Identify integration points, dependencies, and side effects.
Analyse the issue and produce a plan using templates/plan.md:
Example plan output:
# Plan: Fix null pointer in user service
**Issue:** #123 - https://github.com/org/repo/issues/123
## Summary
User service crashes when processing requests with missing optional fields.
## Analysis
The `processUser` function at `src/services/user.ts:45` accesses `user.profile.name`
without checking if `profile` exists. This was introduced in commit abc123.
## Implementation Plan
1. Add null check for `user.profile` in `processUser`
2. Add fallback default values for optional fields
3. Add unit test for the null case
## Testing/Validation
- [ ] Unit test: processUser with null profile
- [ ] Unit test: processUser with partial profile
- [ ] Integration test: API endpoint with minimal payload
## Risks/Edge Cases
- Other callers may rely on the exception being thrown
- Profile field is used in 3 other places (checked: all safe)
## Complexity
**Low** - Single file change with clear fix
Issues with dependencies:
Issues with multiple related issues:
Ask: "Would you like me to start working on this now?"
Wait for confirmation.
Write the code changes as planned. Test locally.
Follow the repository's coding standards and conventions.
From the worktree (already on the correct branch):
git add -A
git commit -m "Brief description
Closes #$ISSUE_NUMBER"
git push -u origin HEAD
gh pr create --title "Brief description" --body-file templates/pr-body.md
Or use the automated script:
scripts/create-pr.sh $ISSUE_NUMBER "Brief description"
Confirm the PR shows Closes #N and the issue appears in the Development sidebar.
| Keyword | Effect |
|---|---|
Closes #N |
Links PR and closes issue on merge |
Fixes #N |
Same as Closes |
Resolves #N |
Same as Closes |
Ref #N |
Links without closing |
| Script | Purpose |
|---|---|
scripts/setup-worktree.sh |
Pulls main, creates worktree and branch |
scripts/load-issue.sh |
Fetches issue details, comments, and related PRs |
scripts/create-pr.sh |
Commits, pushes, and opens PR |
Use subagents to offload codebase exploration from the main context.
After loading issue context, launch an Explore agent to find relevant files without bloating main context:
Launch Explore agent:
"Find all files related to issue #{number}: {issue_title}
Issue description:
{issue_body}
Search for:
1. Files explicitly mentioned in the issue
2. Files matching keywords from the issue title and body
3. Similar existing implementations (if this is a new feature)
4. Test files that cover the affected areas
5. Configuration files that might need updates
6. Related type definitions or interfaces
For each relevant file found:
- Explain why it's relevant
- Note the key functions/classes to modify
- Identify integration points with other code
Return:
- List of affected files with explanations
- Existing patterns to follow
- Test files to update or add
- Potential side effects to consider"
Benefits:
After exploration, optionally launch a Plan agent for complex issues:
Launch Plan agent:
"Design implementation for issue #{number}: {issue_title}
Context from exploration:
{exploration_results}
Issue requirements:
{issue_body}
Create a detailed implementation plan covering:
1. Root cause analysis (for bugs) or feature breakdown (for features)
2. Step-by-step implementation order
3. Testing approach
4. Risks and edge cases
5. Complexity assessment"
When to use Plan agent:
For straightforward PRs, create in background while reporting to user:
Launch background agent:
"Create PR for issue #{number}.
Branch: {branch_name}
Title: {pr_title}
Body: {pr_body}
Steps:
1. git push -u origin HEAD
2. gh pr create --title '...' --body '...'
3. Return PR URL"
User sees immediate confirmation while PR creates in background.
When to use subagents:
When to skip subagents:
