new-gh-issue-orchestration

name	new-gh-issue-orchestration
description	Orchestrates a GitHub-issue-driven delivery workflow from issue intake to PR creation using reviewer-first then worker execution. Invoked when the user provides a GitHub issue link/number and asks to start end-to-end delivery.
version	1.0.0
tags	["workflow","github","issue","orchestration","automation"]
resources	["resources/workflow-checklist.md"]
vendor_support	{"claude":"native","opencode":"native","copilot":"prompt-inject","codex":"prompt-inject","gemini":"prompt-inject"}

New GitHub Issue Orchestration Skill

Trigger Contract

Use this skill when the user input matches one of these patterns:

• new-gh-issue: https://github.com/<org>/<repo>/issues/<number>
• new-gh-issue: <number>

Important:

• new-gh-issue: is a workflow trigger phrase, not a shell command.
• Never try to execute new-gh-issue in a terminal.
• Parse the value after new-gh-issue: as issue identifier input.

Step 1 - Preflight Checks

Run:

git status --short
git branch --show-current

Rules:

• If working tree is dirty, stop and ask whether to stash/commit before proceeding.
• If issue identifier is missing/invalid, ask for a valid GitHub issue URL or number.

Step 2 - Resolve Issue Context

Run:

gh issue view <issue> --repo <owner>/<repo> --comments

Extract:

• issue title, number, and intent
• implementation constraints
• any prior planning comments

Step 3 - Create Proper Branch from Rebased Main

Run:

git checkout main
git fetch origin main
git rebase origin/main
git checkout -b <type>/<issue-number>-<scope-slug>

Branch naming rules:

• Use Conventional Commit type prefix (feat/, fix/, docs/, chore/).
• Include issue number and short kebab-case slug from issue scope.

Step 4 - Reviewer-First Analysis

Delegate to reviewer agent to:

• identify scope risks and blockers
• tighten file-level boundaries
• produce a worker-ready checklist

If reviewer finds blocking ambiguity, resolve it before coding.

Step 5 - Worker Agent Execution

Delegate to worker with reviewer-constrained checklist:

• implement requested scope
• run required validations
• report changed files and tradeoffs

Step 6 - Reviewer Agent Validation Gate

After worker delivery, delegate to reviewer agent for a second-pass validation gate.

Loop policy:

• Maximum automatic iterations: 3.
• If reviewer reports no blocking findings, proceed.
• If reviewer reports blocking findings:
  • acknowledge the developer with a concise findings summary
  • if mitigation is possible, in-scope, and absolutely needed, pass a mitigation plan back to worker
  • after worker fixes, run reviewer again
• If still unresolved after 3 automatic iterations, stop and ask developer for clear next instructions.

Agent Orchestration Rules

• Wait for delegated agents to complete before advancing to dependent steps.
  • Do not continue to commit/push/PR steps while required reviewer/worker tasks are still running.
  • If an agent is still running, keep polling until completion or explicit timeout/escalation.
• If work is parallelizable, spawn more than one agent.
  • Use multiple agents only for independent subtasks with non-overlapping outputs.
  • Avoid parallelizing tightly coupled or blocking subtasks where sequencing is required.

Step 7 - Validation Gates

Run the repository's required quality gates before commit/push.

Examples (use only what the target repo defines):

• lint/static analysis
• tests (unit/integration/e2e as applicable)
• type/schema/index generation checks when relevant to changed files

Rule:

• Do not push if required validation fails.

Then:

git add <files>
git commit -m "<conventional-commit-message>"
git push -u origin <branch>

Step 8 - Open PR and Verify Body

Create PR with a real body (summary, changed files, validation, issue link):

gh pr create --base main --head <branch> --title "<title>" --body-file <body-file>

Immediately verify PR description is not empty:

gh pr view <pr-number-or-branch> --json url,body,title

If body is empty, repair with gh pr edit --body-file ... and verify again.

Failure Handling

• Network/API failure: retry with appropriate permissions and surface exact failure.
• Existing branch collision: derive a new branch slug and retry.
• Missing gh auth: stop and request authentication.
• Validation failure: fix, rerun checks, then continue.