athola When NOT To Use
- A single-file fix obvious enough to make directly
- Preparing the PR once the work is done (use
sanctum:pr-prep)
Table of Contents
Fix Issue(s)
Retrieves issue content from the detected git platform (GitHub, GitLab, or Bitbucket) and uses subagent-driven-development to systematically address requirements, executing tasks in parallel where dependencies allow.
Platform detection is automatic via the leyline:git-platform SessionStart hook. Check session context for git_platform: to determine which CLI to use.
Key Features
- Cross-Platform: Automatically detects GitHub/GitLab/Bitbucket and uses appropriate CLI
- Flexible Input: Single issue number, platform URL, or space-delimited list
- Parallel Execution: Independent tasks run concurrently via subagents
- One PR: All issues produce one consolidated PR (never per-issue PRs)
- Quality Gates: Code review between task groups
- Fresh Context: Each subagent starts with clean context for focused work
Workflow Overview
| Phase | Description | Module |
|---|---|---|
| 1. Discovery | Parse input, fetch issues, extract requirements | issue-discovery |
| 2. Planning | Analyze dependencies, create task breakdown | task-planning |
| 3. Execution | Dispatch parallel subagents for independent tasks | parallel-execution |
| 4. Quality | Code review gates between task batches | quality-gates |
| 5-6. Completion | Sequential tasks, final review, issue updates | completion |
Required TodoWrite Items
do-issue:discovery-completedo-issue:tasks-planneddo-issue:parallel-batch-completedo-issue:review-passeddo-issue:sequential-completedo-issue:issues-updated
Forge CLI Commands
Use the platform detected in session context (git_platform:). See Skill(leyline:git-platform) for full mapping.
| Operation | GitHub (gh) |
GitLab (glab) |
|---|---|---|
| Fetch issue | gh issue view <N> --json title,body,labels,comments |
glab issue view <N> |
| Comment | gh issue comment <N> --body "msg" |
glab issue note <N> --message "msg" |
| Close | gh issue close <N> --comment "reason" |
glab issue close <N> |
| Search | gh issue list --search "query" |
glab issue list --search "query" |
Verification: Run the command with --help flag to verify availability.
Agent Teams (Default Execution Mode)
Agent teams is the default parallel execution backend for do-issue. Teammates coordinate via filesystem-based messaging, enabling real-time communication when shared files or dependencies are discovered mid-implementation.
Automatic downgrade: For single issues with --scope minor, agent teams is skipped (Task tool or inline execution is used instead). Use --no-agent-teams to force Task tool dispatch for any invocation.
Requires: Claude Code 2.1.32+, tmux, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. If prerequisites are missing, silently falls back to Task tool dispatch.
# Agent teams configuration
fix_issue:
agent_teams:
enabled: true # on by default; --no-agent-teams to disable
max_teammates: 4 # limit concurrent workers
model: sonnet # teammate model (lead uses current model)
auto_downgrade: true # skip agent teams for --scope minor
See modules/parallel-execution.md for detailed agent teams patterns.
Configuration
fix_issue:
parallel_execution: true
max_parallel_subagents: 3
review_between_batches: true
auto_close_issues: false
commit_per_task: true
Verification: Run the command with --help flag to verify availability.
Detailed Resources
- Phase 1: See modules/issue-discovery.md for input parsing and requirement extraction
- Phase 2: See modules/task-planning.md for dependency analysis
- Phase 3: See modules/parallel-execution.md for subagent dispatch
- Phase 4: See modules/quality-gates.md for review patterns
- Phase 5-6: See modules/completion.md for finalization
- Errors: See modules/troubleshooting.md for common issues
Exit Criteria
- All 6 required TodoWrite items (
do-issue:discovery-completethroughdo-issue:issues-updated) are created before execution starts and each marked complete when its phase finishes - Issue requirements fetched using the correct forge CLI (
ghfor GitHub,glabfor GitLab) as detected in session context - Exactly one consolidated PR is opened covering all issues; no per-issue PRs are created
- Code review gate runs between parallel task batches and must pass before the next batch is dispatched
- All specified issues are commented on or closed with a reference to the PR after it is ready for review