---
name: parallel-tickets
description: Legacy, being replaced by ship. Use only when the user names parallel-tickets or asks for in-session subagents instead of worker sessions; otherwise use ship for working several issues at once.
---

# Parallel Tickets (orchestrator)

Run up to **3** GitHub issues concurrently. This session is the **orchestrator**; it never
implements a ticket itself. Each ticket is handled by one background subagent running the
full `next-issue` workflow on a **single pre-assigned issue**.

## Why this is safe

Distinct issues are pre-claimed (`in-progress` label) **before** dispatch, so no selection
race. Each agent works in its own fresh worktree off latest `main`; overlapping edits are
handled by the `next-issue` pre-merge rebase check. Background agents have no human in their
loop, so real ambiguity is resolved with the user **up front** (scout phase → clarification
gate, steps 4–5) — only then are agents told to "proceed without asking." Skipping the scout
phase means genuine questions get silently assumed away inside invisible agents.

## Workflow

### 1. Confirm the two decisions that change outcomes

Use AskUserQuestion (skip any the user already specified):

- **Batch size** — how many issues (cap at 3).
- **Autonomy depth** — per agent: (a) stop at open PR, (b) PR + Copilot loop then ask before
  merge, or (c) full end-to-end incl. auto-merge. (c) means N parallel auto-merges with no
  human gate — only when the user explicitly opts in.

### 2. Pre-select N distinct, implementation-ready issues

Rank and exclude per `../next-issue/references/ticket-selection.md`. On top of that:

- **Conflict-aware selection**: within a batch, prefer issues touching disjoint surfaces. If
  two candidates would edit the same page/component/context concurrently, take the
  higher-ranked one and swap the other for the next non-overlapping candidate — tell the user
  which issue you skipped and why.
- Pick the top N. Show the user which issues you chose.

### 3. Pre-claim (kills the race)

Claim every selected issue up front with the REST claim command in
`../next-issue/references/ticket-selection.md`, before any scout runs.

### 4. Scout phase — surface clarifying questions (parallel, READ-ONLY)

Dispatch one short-lived scout per selected issue (foreground / blocking; `subagent_type: Plan`
or `Explore`, or `general-purpose` told explicitly **not to edit, commit, or branch**). Each
scout:

- Reads its assigned issue + the relevant codebase.
- **Verifies the issue's technical premises against the code** — issue bodies often go stale
  or guess wrong. Corrections go in `planSummary` and get baked into the implementation prompt.
- Returns a **proposed implementation plan**, a **context pack**, AND a list of **genuine
  clarifying questions** — only questions a reasonable engineer truly cannot resolve from the
  issue + code (product intent, ambiguous scope, conflicting requirements, OR a significant
  hard-to-reverse architecture-shape call the user may have a directional preference on — e.g.
  extract a new shared abstraction vs. duplicate per call-site). NOT questions answerable by
  reading code.

Build the scout prompt from `references/scout-prompt.md`: the question format, the return
shape, and where the context pack is written. The implementer starts from that pack instead
of re-exploring the codebase.

Run scouts concurrently and wait for all (this is a barrier — you need every question before
you can batch them to the user).

### 5. Clarification gate (the user)

- Pool all questions across all tickets. De-duplicate overlapping ones.
- If **zero** real questions surfaced, skip straight to dispatch — note that you did.
- Otherwise ask the user in **batched `AskUserQuestion` rounds** (max 4 per call). Put the
  scout's one-line `q` as the question, fold its `example` into the question text (e.g.
  `... (currently: "Achievements" tab → only a Recalculate button)`), and use the scout's
  `options` verbatim with the recommendation first + "(recommended)". Keep it skimmable — the
  user should grasp each question in one read without you pasting plan rationale.
- Record each answer against its issue. These answers + the scout's plan become the contract
  baked into the implementation prompt. Do NOT dispatch implementation until this gate clears.

### 6. Dispatch one implementation subagent per issue

Launch all N in a single message, each `run_in_background: true`, `subagent_type: general-purpose`.
Each prompt is a short kickoff for the `ticket-worker` skill, mode `subagent`. It MUST contain:

- "You are a ticket worker. Invoke the `ticket-worker` skill and follow it. Mode: subagent."
- **The assigned issue number + title.**
- **The context pack path** from the scout phase.
- **The agreed plan + the user's clarification answers for THIS issue**, stated explicitly as
  settled decisions. This is what makes "proceed without asking" safe.
- **Standing user rules that apply to this ticket type** — check memory/feedback for durable
  rules and bake the applicable ones into the prompt; agents don't inherit them. Never delete
  `assets/*` branches during cleanup.
- **Spike/doc-only tickets** adapt the same flow: deliverable is an ADR (+ plan doc) on a
  branch → PR; follow-up implementation issues are DRAFTED in the final report for
  orchestrator confirmation, never self-filed.
- **Residual overlap heads-up**: if any selected issues still touch a shared file despite
  conflict-aware selection, name the file(s) and sibling issue(s) in each affected agent's
  prompt so it keeps that edit minimal and expects pre-merge rebases onto sibling merges.
  Generated-file collisions (migrations, codegen) are the common case: tell BOTH siblings up
  front, per `stack-notes`.
- **The chosen autonomy depth** (push-only / ask-before-merge / full auto-merge).
- **Plan file**: where the repo ships plans on the branch, the worker commits the settled plan
  to `docs/superpowers/plans/<YYYY-MM-DD>-<issue-slug>.md`; elsewhere global AGENTS.md applies.

### 7. Orchestrate

- **Completion is push-based** — the harness notifies you when each agent finishes; relay its
  report to the user immediately. Do NOT tail the subagent output file (it's the full JSONL
  transcript and will overflow context). Do NOT run a tight polling loop — you're re-invoked
  automatically on completion.
- **Mid-flight check-ins are pull-based** — when the user asks "check in", poll observable
  GitHub signals (`gh pr list`, `gh pr checks`, Copilot review state) for the assigned issues
  and give a snapshot. Never read transcripts for this.
- **Handle the escape hatch** — if an agent returns `ABORTED-NEEDS-CLARIFICATION`, it hit a new
  question the scout phase missed. Surface that question to the user, get the answer, then
  re-dispatch a fresh implementation agent for that issue (re-claim the label) with the answer
  added to the contract.
- **Handle a mid-flight "monitoring" return** — an agent may still open its PR, arm a
  background CI monitor, and return. Don't dispatch a finisher: SendMessage the SAME agent
  (worktree context intact) with orders to wait inline, handle Copilot, rebase-check, merge,
  clean up — and not return until MERGED or ABORTED. The notification firing means no live
  monitor exists, so the resume is safe. The FIRST resume message must already spell out
  ticket-worker section 6's mechanism: forbid the Monitor tool by name and give the foreground
  wait command; a generic "poll inline" order lets the agent re-arm a monitor and return again.
- **Stranded PR or deleted `assets/*` branch** — see `references/recovery.md`.

### 8. Verify clean exit

After all agents complete:
```
git branch --show-current        # main
git worktree list                # only the main worktree should remain
gh issue list --label in-progress --state open   # none of your issues should linger
```
Report final table (issue → PR → merge SHA → state). Flag any pre-existing stale
`in-progress` labels you didn't create rather than removing them silently.

### 9. Retrospective — improve this skill (run after EVERY batch)

After the final table, do a short retrospective and fold durable lessons back into this skill.
Do not skip it, even on a clean run ("what went smoothly that's worth locking in?" counts).

**Collect signals from the run:**
- Any `ABORTED-NEEDS-CLARIFICATION` → a question the scout phase should have caught. The single
  highest-value signal.
- Any constraint violation, rework, or near-miss (agent ran `git add -A`, wrong worktree, lint
  reached CI, re-litigated a settled decision, format too verbose/terse).
- Any new gotcha (a command that errors-but-succeeds, a flaky check, a race).
- Repeated friction across agents (all three hit the same review finding → bake the fix
  into the implementation prompt so it never recurs).

**Turn each signal into the smallest durable edit:**
- Scout missed a question type → add that pattern to Step 4 or `references/scout-prompt.md`.
- Constraint violated → strengthen the rule in the ticket-worker skill (worker-side) or the
  Step 6 kickoff (ticket-specific).
- New gotcha → add a bullet to `## Notes`. Recurring rework → pre-empt it in the relevant step.

Follow the global AGENTS.md "Improving skills and memory" rules (run `skill-budget`, edit
before adding, show the diff first, history in `CHANGELOG.md`). Only generalizable lessons; a
one-off detail about a specific ticket is not a skill edit. If nothing generalizable surfaced,
say so and add nothing.

## Notes

- `gh pr merge --delete-branch` errors on the local step when `main` is checked out in the
  outer worktree, but the remote merge + branch delete still land. Verify, don't retry.
- Cap concurrency at 3: more parallel auto-merges against one `main` increases mid-flight
  rebase churn with diminishing return.
- With 3 agents + orchestrator polling, the GraphQL quota (`gh ... --json`, `gh issue edit`,
  `gh label create`) runs out and is often already gone at session start. Use REST for
  selection and claiming (per `../next-issue/references/ticket-selection.md`) and for poll loops (`gh api .../check-runs`).
  For orchestrator check-ins use git protocol (`git ls-remote`, `git fetch` + `git log
  origin/main`): zero API cost, and "branch gone + main advanced" still answers "did it merge?".
- Never run two agents on one worktree (see `references/recovery.md` for stranded PRs).
- The permission classifier may deny `gh api -X POST .../issues` (filing follow-ups) as an
  out-of-scope write. Don't work around it: collect follow-ups and present them for user
  confirmation at the retrospective.
- A completed agent's task-id can fire a second, stale completion notification. If that agent
  was already reported done, ignore it.