oh-task
Like mouse, but for GitHub issues instead of ba tasks. Claims an issue, works it to completion in an isolated branch, PR for human review.
Invocation
/oh-task <issue-number> [branch]
<issue-number> - the GitHub issue number (e.g., 123 or #123)
[branch] - optional base branch (default: origin/main)
Use [branch] for stacked PRs where this issue depends on another in-flight PR.
Flow
Determine the target branch:
- If
[branch] specified: use that branch (strip origin/ prefix if present)
- Otherwise: use
main
Sync with target branch from origin:
git fetch origin
git checkout -B <target-branch> origin/<target-branch>
Fetch and validate issue:
gh issue view <issue-number> --json number,title,body,state,assignees
Abort if issue is closed or already assigned to someone else.
Claim issue (assign to self):
gh issue edit <issue-number> --add-assignee @me
No commit needed - state is on GitHub.
Read dive context (if available) for project background:
cat .wm/dive_context.md 2>/dev/null || echo "No dive context"
Read and understand the issue:
- Review issue title and body
- Think through the approach
- Ask clarifying questions if requirements are ambiguous
- Only proceed when confident in the approach
Create worktree from base branch:
git fetch origin
git worktree add .worktrees/issue-<number> -b issue/<number> --no-track origin/<target-branch>
cd .worktrees/issue-<number>
sg init
Work until issue is resolved
Stage changes (git add)
Run code checks (cargo check, npm/pnpm build, go build, etc. based on project type).
Fix any errors, re-stage, re-run until clean.
Run sg review on staged changes (do NOT use code-reviewer agent)
Handle review findings:
- P1-P3 trivial: fix inline, re-stage, re-review
- P1-P3 non-trivial: create child issue with
gh issue create --title "..." --body "Parent: #<issue-number>"
- P4: discard (nitpick)
Commit code changes
CRITICAL: Complete ALL child issues before PR.
Any gh issue create during this session = child that blocks PR.
No "follow-ups" - if you create it, you work it now.
While ANY unclosed issues created in this session:
- Claim:
gh issue edit <child-number> --add-assignee @me
- Work until complete
- Stage changes
- Run code checks, fix errors until clean
- Run
sg review (each issue gets its own review!)
- Handle findings (may spawn more children)
- Commit
- Loop until zero unclosed children
ALL issues addressed -> push and create PR:
git push -u origin issue/<number>
gh pr create --base <target-branch> --title "<issue-title>" --body "$(cat <<'EOF'
Closes #<issue-number>
## Also Closes
- #<child-1>
- #<child-2>
## Summary
<brief description of changes>
EOF
)"
The "Closes #N" syntax auto-closes issues when PR merges.
Wait for CodeRabbit review, then iterate:
gh pr view <pr-number> --comments to check for CodeRabbit feedback
- Handle like sg findings:
- Trivial: fix inline
- Non-trivial: create child issue
- Nits: ignore
- For each fix or new issue:
- Stage changes
- Run code checks, fix errors until clean
- Run
sg review (CodeRabbit fixes get sg reviewed too!)
- Handle any new findings
- Commit
- Push all changes
- Repeat until CodeRabbit has no new comments
Verify CI is green:
gh pr checks <pr-number> --watch --fail-on-error
If CI fails:
- Read the failing check logs
- Attempt to fix the issue
- Stage changes, run code checks, run
sg review
- Commit and push
- Wait for CI again:
gh pr checks <pr-number> --watch --fail-on-error
- Max 3 CI fix attempts. If still failing, signal
status: "error" with the failure reason.
Return to main repo and signal completion:
cd <original-dir>
Call signal_completion(status: "success", pr: "<pr-url>") to notify the orchestrator.
CRITICAL: Signal BEFORE cleanup.
Cleanup worktree:
git worktree remove .worktrees/issue-<number>
Exit and report PR URL
Git Workflow
- Create isolated worktree in
.worktrees/issue-<number>
- All work happens on
issue/<number> branch
- Branch from main/master at start
- Each issue = one or more commits
- Keep commits focused and atomic
- PR encompasses entire issue tree (parent + children)
- Worktree cleaned up after PR created
Review Handling
- P1-P3 findings: Create as GitHub issues, work them in this session
- P4 findings: Discard as nitpicks (don't create issues)
Human Touchpoint
The PR is the only human review point.
Everything before is autonomous.
Exit Conditions
- Success: PR created, CI green, all issues in tree will close on merge
- Blocked: An issue needs human decision - stop and report
- Safety: Max 10 issue iterations (prevent runaway)
Completion Signaling (MANDATORY)
CRITICAL: You MUST signal completion when done. Call the signal_completion tool as your FINAL action.
Signal based on outcome:
| Outcome |
Call |
| PR created, reviewed, CI green |
signal_completion(status: "success", pr: "<pr-url>") |
| Unrecoverable failure |
signal_completion(status: "error", error: "<reason>") |
| Needs human decision |
signal_completion(status: "blocked", blocker: "<reason>") |
| If you do not signal, the orchestrator will not know you are done and the session becomes orphaned. |
|
Fallback: If the signal_completion tool is not available, output your completion status as your final message in the format: COMPLETION: status=<status> pr=<url> or COMPLETION: status=<status> error=<reason>.
Example
$ /oh-task 42
Fetching issue #42...
Issue: "Fix validation bug in auth module"
State: open, unassigned
Claiming issue #42...
Assigned to @me
Reading dive context...
No dive context found.
Reading issue details...
Issue: Input validation fails silently on empty strings
Approach: Add explicit empty string check before processing
No clarifying questions needed, proceeding.
Creating worktree .worktrees/issue-42 on branch issue/42
Initializing superego...
Working on issue...
Staging changes...
Running sg review...
Found 2 issues:
- P3: Add test for edge case -> non-trivial, created issue #43 (Parent: #42)
- P4: Consider renaming variable -> discarded (nitpick)
Review clean (P3 spawned as issue, P4 discarded)
[commit] fix: validate input before processing
Working on child issue #43...
Claiming issue #43...
Staging changes...
Running sg review...
No issues found.
[commit] test: add edge case coverage
All issues complete.
Pushing issue/42...
Creating PR...
PR created: https://github.com/org/repo/pull/99
Body includes: Closes #42, Closes #43
Waiting for CodeRabbit review...
CodeRabbit found 2 issues:
- "Add nil check before dereferencing" -> trivial, fixing inline
- "Consider refactoring to reduce complexity" -> nit, ignoring
[commit] fix: add nil check per CodeRabbit
Pushing...
CodeRabbit review passed.
Waiting for CI checks...
CI passed (3/3 checks green).
Returning to main repo...
signal_completion(status: "success", pr: "https://github.com/org/repo/pull/99")
Cleaning up worktree...
Done.
Stacked PRs Example
$ /oh-task 42
# Claims issue #42 on main
# Creates PR #99: issue/42 -> main (Closes #42)
$ /oh-task 43 issue/42
# Checks out issue/42, claims issue #43
# Creates PR #100: issue/43 -> issue/42 (Closes #43)
$ /oh-task 44 issue/43
# Checks out issue/43, claims issue #44
# Creates PR #101: issue/44 -> issue/43 (Closes #44)
$ /drummer
# Merges in order: #99 -> main, rebases #100 -> main, rebases #101 -> main
1---2name: oh-task-23description: Work a GitHub issue to completion in a branch, including review follow-ups, then PR for human review4---56# oh-task78Like mouse, but for GitHub issues instead of ba tasks. Claims an issue, works it to completion in an isolated branch, PR for human review.910## Invocation1112`/oh-task <issue-number> [branch]`1314- `<issue-number>` - the GitHub issue number (e.g., `123` or `#123`)15- `[branch]` - optional base branch (default: `origin/main`)1617Use `[branch]` for stacked PRs where this issue depends on another in-flight PR.1819## Flow20211. Determine the target branch:22 - If `[branch]` specified: use that branch (strip `origin/` prefix if present)23 - Otherwise: use `main`242. Sync with target branch from origin:25 ```bash26 git fetch origin27 git checkout -B <target-branch> origin/<target-branch>28 ```293. Fetch and validate issue:30 ```bash31 gh issue view <issue-number> --json number,title,body,state,assignees32 ```33 Abort if issue is closed or already assigned to someone else.344. Claim issue (assign to self):35 ```bash36 gh issue edit <issue-number> --add-assignee @me37 ```38 No commit needed - state is on GitHub.395. Read dive context (if available) for project background:40 ```bash41 cat .wm/dive_context.md 2>/dev/null || echo "No dive context"42 ```436. Read and understand the issue:44 - Review issue title and body45 - Think through the approach46 - Ask clarifying questions if requirements are ambiguous47 - Only proceed when confident in the approach487. Create worktree from base branch:49 ```bash50 git fetch origin51 git worktree add .worktrees/issue-<number> -b issue/<number> --no-track origin/<target-branch>52 cd .worktrees/issue-<number>53 sg init54 ```558. Work until issue is resolved569. Stage changes (`git add`)5710. Run code checks (cargo check, npm/pnpm build, go build, etc. based on project type).58 Fix any errors, re-stage, re-run until clean.5911. Run `sg review` on staged changes (do NOT use code-reviewer agent)6012. Handle review findings:61 - P1-P3 trivial: fix inline, re-stage, re-review62 - P1-P3 non-trivial: create child issue with `gh issue create --title "..." --body "Parent: #<issue-number>"`63 - P4: discard (nitpick)6413. Commit code changes6514. **CRITICAL: Complete ALL child issues before PR.**66 Any `gh issue create` during this session = child that blocks PR.67 No "follow-ups" - if you create it, you work it now.6869 While ANY unclosed issues created in this session:70 - Claim: `gh issue edit <child-number> --add-assignee @me`71 - Work until complete72 - Stage changes73 - Run code checks, fix errors until clean74 - Run `sg review` (each issue gets its own review!)75 - Handle findings (may spawn more children)76 - Commit77 - Loop until zero unclosed children7815. ALL issues addressed -> push and create PR:79 ```bash80 git push -u origin issue/<number>81 gh pr create --base <target-branch> --title "<issue-title>" --body "$(cat <<'EOF'82 Closes #<issue-number>8384 ## Also Closes85 - #<child-1>86 - #<child-2>8788 ## Summary89 <brief description of changes>90 EOF91 )"92 ```93 The "Closes #N" syntax auto-closes issues when PR merges.9416. Wait for CodeRabbit review, then iterate:95 - `gh pr view <pr-number> --comments` to check for CodeRabbit feedback96 - Handle like sg findings:97 - Trivial: fix inline98 - Non-trivial: create child issue99 - Nits: ignore100 - For each fix or new issue:101 - Stage changes102 - Run code checks, fix errors until clean103 - Run `sg review` (CodeRabbit fixes get sg reviewed too!)104 - Handle any new findings105 - Commit106 - Push all changes107 - Repeat until CodeRabbit has no new comments10817. Verify CI is green:109 ```bash110 gh pr checks <pr-number> --watch --fail-on-error111 ```112 If CI fails:113 - Read the failing check logs114 - Attempt to fix the issue115 - Stage changes, run code checks, run `sg review`116 - Commit and push117 - Wait for CI again: `gh pr checks <pr-number> --watch --fail-on-error`118 - Max 3 CI fix attempts. If still failing, signal `status: "error"` with the failure reason.11918. Return to main repo and signal completion:120 ```bash121 cd <original-dir>122 ```123 Call `signal_completion(status: "success", pr: "<pr-url>")` to notify the orchestrator.124 **CRITICAL:** Signal BEFORE cleanup.12519. Cleanup worktree:126 ```bash127 git worktree remove .worktrees/issue-<number>128 ```12920. Exit and report PR URL130131## Git Workflow132133- Create isolated worktree in `.worktrees/issue-<number>`134- All work happens on `issue/<number>` branch135- Branch from main/master at start136- Each issue = one or more commits137- Keep commits focused and atomic138- PR encompasses entire issue tree (parent + children)139- Worktree cleaned up after PR created140141## Review Handling142143- **P1-P3 findings**: Create as GitHub issues, work them in this session144- **P4 findings**: Discard as nitpicks (don't create issues)145146## Human Touchpoint147148The PR is the **only** human review point.149Everything before is autonomous.150151## Exit Conditions152153- **Success**: PR created, CI green, all issues in tree will close on merge154- **Blocked**: An issue needs human decision - stop and report155- **Safety**: Max 10 issue iterations (prevent runaway)156157## Completion Signaling (MANDATORY)158**CRITICAL: You MUST signal completion when done.** Call the `signal_completion` tool as your FINAL action.159**Signal based on outcome:**160| Outcome | Call |161|---------|------|162| PR created, reviewed, CI green | `signal_completion(status: "success", pr: "<pr-url>")` |163| Unrecoverable failure | `signal_completion(status: "error", error: "<reason>")` |164| Needs human decision | `signal_completion(status: "blocked", blocker: "<reason>")` |165**If you do not signal, the orchestrator will not know you are done and the session becomes orphaned.**166167**Fallback:** If the `signal_completion` tool is not available, output your completion status as your final message in the format: `COMPLETION: status=<status> pr=<url>` or `COMPLETION: status=<status> error=<reason>`.168169## Example170171```172$ /oh-task 42173174Fetching issue #42...175Issue: "Fix validation bug in auth module"176State: open, unassigned177178Claiming issue #42...179Assigned to @me180181Reading dive context...182No dive context found.183184Reading issue details...185Issue: Input validation fails silently on empty strings186Approach: Add explicit empty string check before processing187No clarifying questions needed, proceeding.188189Creating worktree .worktrees/issue-42 on branch issue/42190Initializing superego...191Working on issue...192Staging changes...193Running sg review...194Found 2 issues:195 - P3: Add test for edge case -> non-trivial, created issue #43 (Parent: #42)196 - P4: Consider renaming variable -> discarded (nitpick)197Review clean (P3 spawned as issue, P4 discarded)198[commit] fix: validate input before processing199200Working on child issue #43...201Claiming issue #43...202Staging changes...203Running sg review...204No issues found.205[commit] test: add edge case coverage206207All issues complete.208Pushing issue/42...209Creating PR...210PR created: https://github.com/org/repo/pull/99211Body includes: Closes #42, Closes #43212213Waiting for CodeRabbit review...214CodeRabbit found 2 issues:215 - "Add nil check before dereferencing" -> trivial, fixing inline216 - "Consider refactoring to reduce complexity" -> nit, ignoring217[commit] fix: add nil check per CodeRabbit218Pushing...219CodeRabbit review passed.220Waiting for CI checks...221CI passed (3/3 checks green).222Returning to main repo...223signal_completion(status: "success", pr: "https://github.com/org/repo/pull/99")224Cleaning up worktree...225Done.226```227228### Stacked PRs Example229230```231$ /oh-task 42232# Claims issue #42 on main233# Creates PR #99: issue/42 -> main (Closes #42)234235$ /oh-task 43 issue/42236# Checks out issue/42, claims issue #43237# Creates PR #100: issue/43 -> issue/42 (Closes #43)238239$ /oh-task 44 issue/43240# Checks out issue/43, claims issue #44241# Creates PR #101: issue/44 -> issue/43 (Closes #44)242243$ /drummer244# Merges in order: #99 -> main, rebases #100 -> main, rebases #101 -> main245```