Subissue Orchestration

What problem does it solve?

Subissue Orchestration tackles the complexity of managing large epics by automatically creating and linking subissues under a parent issue. It leverages GitHub's native sub-issues API (GA 2025) for accurate parent-child relationships that surface in the GitHub UI and Projects, with a markdown checklist fallback for compatibility.

Core Features & Use Cases

• Native Sub-Issues API: create and link subissues to a parent epic, visible in the UI and Projects, supporting up to 100 subissues per parent and 8 levels of nesting, with cross-repository support.
• Subissue Creation: use the sync-task-to-subissue workflow to automatically link created subissues via the native API.
• Checklist Fallback: when native sub-issues are unavailable, maintain a checklist in the parent issue and keep it synchronized.
• Bulk Creation & PR Coordination: spawn multiple subissues from a list and coordinate with stacked PRs so merging closes the appropriate subissues.
• Auto-Sync & Lifecycle: keep parent and subissues in sync as work progresses, including status updates and re-linking when needed.

Quick Start

Create a parent epic and then generate subissues linked to it.

PARENT=$(gh issue create --title "Authentication System" --label "epic" --body "## Subtasks\n\n- [ ] OAuth\n- [ ] Email auth\n- [ ] Password reset" --json number -q .number)

gh issue create --title "OAuth integration" --label "task" --body "Parent Issue: #$PARENT" gh api repos/{owner}/{repo}/issues/$PARENT/sub_issues -X POST -f sub_issue_id=$SUBISSUE_ID