# Github Swarm Orchestration

> Coordinates multi-agent research work through GitHub issues, branches, and PRs with explicit review and verifier gates. Use when running a swarm, parallel issues, orchestration log, feat/issue-N branches, merge order, consistency pass before merge, or Day 3-style lab workflow.

- Skill: `meleantonio/github-swarm-orchestration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add meleantonio/github-swarm-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/meleantonio/github-swarm-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: meleantonio (https://skillmd.com/u/meleantonio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/meleantonio/github-swarm-orchestration

---


# GitHub Swarm Orchestration

## When to use

- User mentions: swarm, parallel agents, orchestration log, one issue one branch, Cloud Agent per issue, merge order, or `materials/day3` workflow.
- You need a **repeatable** captain loop: plan → issues → branches → PRs → review → verify → merge → follow-on issues.

## Preconditions

1. If work is spec-driven: `spec/tasks.md` should be approved (use `sdd-orchestrator` / SDD skill first).
2. Git remote exists; `gh auth status` succeeds when using GitHub CLI.

## Workflow

### 1. Choose spine

- **Spec-first:** Read `spec/tasks.md` and map checkboxes to GitHub issues (delegate drafting to `spec-tasks-to-github` skill for issue bodies).
- **Issue-first:** Use `.github/ISSUE_TEMPLATE/swarm-task.md` fields directly.

### 2. Build the issue DAG

- Label independent work `parallel`.
- Label ordered work `sequential` and add `blocked-by:<N>` for the prerequisite issue number.
- Never start a worker on a blocked issue until the blocker is merged.

### 3. Initialize or update the log

- Open `notes/orchestration_log.md`.
- Add one row per active stream/issue: branch, issue, status, PR (when opened), reviewer.

### 4. Dispatch workers

- Branch: `feat/issue-<N>-short-slug` unless the milestone declares `rig/<stream>` (then log it).
- Optional creative **worker name** for commits and PR description (per project convention).
- Use handoff files `notes/handoff_<from>_to_<to>.md` when streams consume each other's outputs.

### 5. Review gate

- Invoke **`pr-reviewer`** subagent on each PR (readonly review first; then apply fixes on the branch).
- If labels include `domain:*`, invoke the matching domain reviewer agent.

### 6. Verifier gate

- **`replication-verifier`:** when replication paths, deps, or run instructions change.
- **`artifact-coherence-auditor`:** when paper text, tables/figures, and replication must agree.

### 7. Merge gate

- **`integration-coordinator`** (or human): enforce dependency order, rebase if needed, resolve conflicts.
- **Automerge** only if issue has `automerge-ok` and CI + review requirements are satisfied.

### 8. Follow-on work

- Verifier blockers → **open new issues** linked from the audit; do not silently expand an already-approved PR scope.

## Guardrails

- Follow `.cursor/rules/research-reproducibility.mdc`: relative paths, traceable outputs.
- Keep `notes/orchestration_log.md` the durable state mirror alongside GitHub.
- See `reference.md` in this folder for labels, `gh` snippets, and phase detail.

## Output

At end of each captain iteration, report:

- Updated issue/PR links
- Current `notes/orchestration_log.md` row states
- Pending blockers and next merge order