github-next-wave-orchestrator

name	github-next-wave-orchestrator
description	Analyze a GitHub repo’s current issue/PR/code state, produce a concise status report, and propose/execute the next wave of work using parallel agents when useful.
requiredSources	["github"]
alwaysAllow	["Read","Bash"]

GitHub Next Wave Orchestrator

Use this skill when the user asks for:

• “Where is this repo right now?”
• “Summarize issues and tell me what to do next”
• “Run the next wave”
• Ongoing delivery orchestration from GitHub issues

---

Core Outcome

Produce two things:

1. Status Report — current reality of the repository (issues, PRs, velocity, risks)
2. Next Wave Plan — the highest-impact, executable batch of work (parallel where possible)

If user asks to execute, run the approved next wave and report progress.

---

Mandatory Skill Stack

Before doing work, activate and follow in order:

1. using-superpowers — meta-skill gating; if unavailable, proceed but note it.
2. executing-plans — batch and checkpoint discipline; required.
3. dispatching-parallel-agents — use for independent tasks; if unavailable, execute sequentially and note ordering rationale explicitly.

Priority rule: correctness and safety over speed. If a sub-skill is missing, fall back to its documented behavior inline and call it out in the execution log.

---

Inputs to Confirm (if missing)

• Repository owner/name
• Branch strategy (default branch, release branch if any)
• Time horizon for status (last 7/14/30 days)
• Definition of “next wave” (bugfixes, roadmap, reliability, debt, launch)

If these are not provided, proceed with sensible defaults and state assumptions.

---

Execution Protocol

Phase 1 — Repo Reality Scan

Gather evidence (do not guess):

• Open/closed issues, priority labels, age distribution
• Open PRs, merge queue, blocked PRs, stale PRs
• Recent commit activity and release tags
• CI/check run health on active PRs
• Dependency/risk signals from issue text and labels
• Copilot bootstrap state — presence of .github/copilot-instructions.md, .github/workflows/copilot-setup-steps.yml, .github/workflows/copilot-agent-dispatch.yml, and existence of the agent-ready and agent-blocked labels. Record as copilot_bootstrapped: true|false. See the Copilot Dispatch Awareness section below.
• Existing Copilot activity — count of open PRs authored by copilot-swe-agent[bot], count of issues currently assigned to that bot, and count of issues carrying the agent-ready label (awaiting dispatch).

Always anchor conclusions to observable data.

If the repo has zero open issues and zero open PRs, note this explicitly and skip to Phase 3 — propose seed issues based on the codebase state (missing tests, stale deps, undocumented APIs).

Phase 2 — Status Synthesis

Generate a concise Status Report with:

• Repo Pulse: current throughput and momentum
• Issue Landscape: grouped by severity, theme, owner, staleness
• Delivery Risks: blockers, bottlenecks, missing ownership, CI instability
• Readiness Score: Green / Yellow / Red with rationale.
  • Green: no blocking PRs, CI passing, <3 P0 issues open, active commits in last 7 days.
  • Yellow: any one of — CI flaky, 1–2 blocking PRs, 3–6 P0 issues, stale >14 days.
  • Red: CI broken, merge queue blocked, >6 P0 issues, or no commits in >14 days.

Phase 3 — Next Wave Design

Create a prioritized execution wave using this ranking order:

1. Unblocks other work (dependency chains)
2. Fixes broken CI or a P0 bug
3. High impact, reversible (safe to ship fast)
4. High impact, irreversible (needs review gate)
5. Low impact — defer unless trivial

Pick the top 3–7 by this ranking; aim for at least 2 that can run in parallel.

• Define success criteria and verification per task
• Include dependencies and ordering constraints
• Keep blast radius minimal

Worker Lane Assignment

For each selected task, assign one of two worker lanes:

Lane	Assigned when
human	Task touches secrets/infra, requires architectural judgment, has no clear acceptance criteria, or the repo is not Copilot-bootstrapped
copilot-swe-agent[bot]	Task is well-scoped (Goal + Acceptance criteria + Files of interest explicit), copilot_bootstrapped: true, repo policy allows, and work fits the one-branch/one-PR Copilot constraint

Eligibility checklist for the copilot lane (all must be true):

• Issue body follows the agent-ready-task.md template (has ### Goal, ### Acceptance criteria, ### Files of interest, ### Out of scope).
• Scope fits in one branch and one PR (Copilot cannot fan out).
• No secret-reading, no production-credential writes, no destructive infra steps.
• Not labeled agent-blocked (explicit opt-out).
• A second reviewer is available (issue creator cannot approve the resulting PR — GitHub-enforced).

Emit the wave as a ranked-wave.md artifact (see Output Contract §2). Each row declares its lane so downstream dispatch is unambiguous.

Phase 4 — Parallel Dispatch (when executing)

For independent tasks assigned to the human lane:

• Dispatch parallel agents/subtasks with full context per task
• Use one focused prompt per task (objective, constraints, validation)
• Collect outputs
• Run mandatory spotcheck for consistency/completeness

For independent tasks assigned to the copilot-swe-agent[bot] lane:

• Confirm copilot_bootstrapped: true for the target repo (from Phase 1). If not, stop and surface the bootstrap step from templates/.github/ (see Copilot Dispatch Awareness).
• For each issue, apply the agent-ready label. This is the dispatch — the repo's copilot-agent-dispatch.yml workflow runs the two GraphQL calls and assigns copilot-swe-agent[bot].
• Do NOT attempt to assign the bot directly from this skill's session — automation relies on the PAT stored as COPILOT_ASSIGN_PAT inside the target repo, which the orchestrator does not hold.
• After labeling, Copilot reacts 👀 and opens a draft PR within minutes. Capture PR numbers for the Phase 5 checkpoint.

For dependent tasks:

• Execute sequentially with checkpoints, regardless of lane.
• Cross-lane dependencies (e.g., human task must land before Copilot task) must be stated explicitly in the ranked wave.

Phase 5 — Review Checkpoint

After each batch, report:

• Completed items (with worker lane)
• Verification evidence (tests/checks/logs/diffs)
• Copilot PR numbers (if any) and their current state: draft / ready / merged
• Remaining risks
• Recommended next batch

For Copilot-authored draft PRs needing iteration, deliver review feedback via a single @copilot <instruction> comment on the PR — this resumes the agent on that branch. The issue creator cannot be the final approver (GitHub-enforced), so route approval to a second reviewer.

Say: ”Ready for feedback.”

---

Output Contract

Use this structure:

1) Status Report

• Scope and assumptions
• Repo Pulse
• Issue Landscape
• Active PR & CI Health
• Top Risks / Blockers
• Readiness Score

2) Next Wave

For each item:

• Priority
• Why now
• Worker lane: human or copilot-swe-agent[bot]
• Owner / agent lane (sub-role within the worker lane)
• Execution type: Parallel or Sequential
• Done criteria
• Verification steps
• Dispatch action: "apply agent-ready label" (copilot lane) or "assign to " (human lane)

Also report a Dispatch Readiness line immediately under the wave, in the form: Dispatch: X human · Y copilot · Z blocked (agent-blocked or not bootstrapped).

3) Execution Log (if executed)

• What ran
• What passed/failed
• Follow-ups

---

Guardrails

• Never fabricate repository state.
• Never close/edit issues or merge PRs without explicit user approval.
• If evidence is incomplete, call it out and proceed with confidence levels.
• Prefer elegant, minimal-impact solutions over broad refactors.
• Do not mark done without verification evidence.

Copilot-specific guardrails

• Never attempt direct bot assignment from this skill's session. The default GITHUB_TOKEN cannot assign copilot-swe-agent[bot] (returns HTTP 422). Dispatch only by labeling; the target repo's workflow holds the PAT and does the assignment.
• Never auto-approve a Copilot-authored PR. The issue creator is blocked from final approval by GitHub; a second human reviewer is required.
• Refuse to dispatch to copilot lane when: body lacks Acceptance criteria, scope exceeds one branch, issue is labeled agent-blocked, or copilot_bootstrapped: false. Fall back to human lane with an explicit note.
• Do not paste PATs or secrets into issue bodies, PR comments, ranked-wave output, or the execution log. The only PAT reference is the secret name COPILOT_ASSIGN_PAT (always by name, never by value).
• Respect agent-blocked. If an issue carries this label, skip Copilot dispatch even if all other criteria are met.

---

Copilot Dispatch Awareness

This skill can route eligible next-wave items to GitHub's Copilot coding agent (copilot-swe-agent[bot]) instead of to a human worker. The mechanism is label-based and requires a one-time per-repo bootstrap. The orchestrator does not perform the bootstrap itself — it surfaces the gap in Phase 1, consumes the bootstrap state in Phase 3, and dispatches via label in Phase 4.

Pinned constants

Both this skill and cooperating planner skills (e.g., swarm-architect) must use these exact strings:

Constant	Value
Bot login	copilot-swe-agent[bot] (the literal copilot / copilot-swe-agent return HTTP 422)
Opt-in label	agent-ready
Opt-out label	agent-blocked
PAT secret name (in target repo)	COPILOT_ASSIGN_PAT
Required job name in setup workflow	copilot-setup-steps
Required issue body sections	### Goal, ### Context, ### Acceptance criteria, ### Files of interest, ### Out of scope

Trigger mechanism

1. The orchestrator (or a planner) opens an issue in the target repo using the agent-ready body contract above.
2. The orchestrator applies the label agent-ready.
3. The target repo's .github/workflows/copilot-agent-dispatch.yml fires on issues: [labeled], authenticates with the repo secret COPILOT_ASSIGN_PAT, runs two GraphQL calls (suggestedActors → replaceActorsForAssignable), and assigns copilot-swe-agent[bot].
4. Copilot reacts 👀 and opens a draft PR on a new branch.
5. Iteration is via @copilot <instruction> comments on the PR.
6. A second human (not the issue creator) approves and merges.

Bootstrap files (shipped in templates/.github/)

For a target repo to accept Copilot dispatch, these files must exist on its default branch:

File	Purpose
.github/copilot-instructions.md	Repo-wide guidance for the agent (stack, build/test commands, conventions). Plain Markdown, no frontmatter.
.github/instructions/tests.instructions.md	Path-scoped rail: no new .skip / .only / xit without approval. Requires applyTo: frontmatter.
.github/workflows/copilot-setup-steps.yml	Preinstalls deps into the agent's ephemeral VM. Job MUST be named copilot-setup-steps; timeout-minutes: ≤59; Ubuntu or Windows only (macOS unsupported).
.github/workflows/copilot-agent-dispatch.yml	Label-to-assign workflow. Fires on issues: [labeled] for agent-ready. Uses COPILOT_ASSIGN_PAT (not GITHUB_TOKEN).
.github/actions/assign-copilot/action.yml	Composite action wrapping the two GraphQL calls. Single source of truth for the bot login + mutation shape.
.github/ISSUE_TEMPLATE/agent-ready-task.md	Enforces the issue body contract.

Canonical copies ship in this repository under templates/.github/ and can be copied wholesale into any target repo. See templates/README.md for the bootstrap procedure.

Eligibility & preflight (Business / Enterprise org)

Before any dispatch can succeed on an org-owned repo:

1. Enterprise policy: admin enables third-party coding agents at the enterprise Agents page.
2. Org policy: owner enables Copilot coding agent under Settings → Copilot → Policies (disabled by default on Business/Enterprise).
3. Repo opt-in: owner opts the target repo in under the same settings page.
4. Repo secret: COPILOT_ASSIGN_PAT is set (fine-grained PAT with RW on Actions, Contents, Issues, Pull requests; scoped to the target repo only; rotation documented).
5. Approver: a second reviewer is identified. Issue author cannot approve.

If any preflight check fails, the orchestrator MUST fall back to the human lane for all wave items and surface the failing check in the Dispatch Readiness line.

Known quirks (pinned against GitHub Copilot coding agent docs, April 2026)

• Default GITHUB_TOKEN cannot assign the bot (422). PAT is mandatory. Billing attaches to the PAT owner's Copilot seat.
• gh issue edit <n> --add-assignee "copilot-swe-agent[bot]" is flaky for the bot login — the dispatch workflow uses gh api graphql instead.
• actions/checkout fetch-depth is silently overridden inside the agent VM.
• Setup-step failures do not abort the agent — it starts with partial env and produces confusing diffs. The dispatch action fails loudly instead.
• Custom MCP servers must be whitelisted in repo Settings → Copilot → Coding agent. .vscode/mcp.json alone is not honored by the cloud agent.
• Copilot opens exactly one PR per task and works one branch at a time — cannot fan out.

---

Definition of Done

All three sections of the Output Contract delivered, with verification evidence for any executed work, and — when any wave item is routed to copilot-swe-agent[bot] — the Dispatch Readiness line reports the expected lane split, label application is confirmed via gh api, and captured draft-PR numbers appear in the Execution Log. End with: "Ready for feedback."