parallel-issues

Files (3)

• SKILL.md
• prompt.md · assets/
• parallel_issues.py · scripts/

SKILL.md (first lines)

# Parallel Issues

Plan a batch of GitHub issues with the user, then launch one coding agent per group of
issues that depend on each other or touch the same files. Each agent works unattended
in its own worktree and delivers its group as a stack of pull requests, one per issue,
each signed, checked, and reviewed locally before it is committed. The maintainer
review and the merge are the user's, once they are back.

The point of a batch is that the user starts it and goes off to do something else. So
ask for everything the run will need while the user is still there, and always tell
them plainly whether they can leave now and what will call them back.

The launcher is `scripts/parallel_issues.py` (path relative to this skill directory).
Run it from the repository's main checkout. The agents follow `assets/prompt.md`, the
`github-workflow` and `git-commit` skills, and the repository's agent instruction files
(AGENTS.md, CLAUDE.md). Keep repository-specific rules, such as tests that must not
run concurrently, in those instruction files rather than in the prompt.

## Terms

A **batch** is the issues the user approves in one planning session, taken from a
milestone or from a list the user gives. A **wave** is the groups launched together;
the user merges between waves, so in practice one wave runs per night. Waves are
numbered 1 to n. A **group** is the issues one agent delivers in one worktree as one
stack, one pull request per issue, bottom first. A **layer** is one branch and pull
request of a stack. A group is named after its issues, never with a letter: `#185`
for one issue, `#185/#187/#180` for three.

## When the user is needed

Gather every question before the first unattended step, ask them together, and start
only once all are answered. A question that surfaces after the user has left blocks
the work until they return, which defeats the batch.

- **Planning and launch: needed.** Approving the plan, labels or exclusions to fix,
  and the 1Password prompt that reads the signing key, once per 24 hours (see Signing
  key).
- **While the agents run: not needed.** Agents never ask; they take the conservative
  option and note it in the pull request.
- **After the run: needed only for decisions.** Merging, approving the rejected-layer
  procedure (the only force push the workflow allows), pushing a change only the user
  may push, and anything a `keep` or `leftover` line from `clean` asks them to resolve.
  Ask these together as well, before a long merge, release, or cleanup sequence.

End every turn with one of these, stated in so many words:

- "I need you for: …", listing each item and why; or
- "You can go AFK now. Nothing needs you until …", naming what will need them next
  (the agents finishing, a merge decision, the next 1Password prompt), or "until I
  report back" when nothing will.

Say it right after the launch prints every group as started, and again whenever a
step that needed the user is done.

Notifications come from this session only, and only when the user is needed. Whenever
a turn ends with "I need you for: …" while the user may be away, also send that list:
`parallel_issues.py notify "<short title>"` with the list on standard input. Never let
the watcher or the agents ping the user: the watcher runs with `--no-notify` (see
While it runs), and the agents' own notifications are off through `agent.ompConfig`.

Ask the user to send decisions for an agent through this session, not by typing in
the agent's Herdr pane: this session cannot see those messages, and an agent's pane is
removed by `clean`.

## Before the first run

Check each item and fix what is missing with the user; the launcher refuses to start
otherwise.

- The repository works through branches and pull requests. When its agent instruction
  files allow or require committing straight to the default branch, do not launch:
  the agents only open pull requests, and commits on the default branch land as they
  are. Tell the user why and work those issues in an interactive session. The launcher
  does not check this one.
- This session runs in a Herdr pane (`HERDR_ENV=1`). For agent status to be accurate,
  Herdr's integration for the agent must be installed (`herdr integration status`).
- `gh extension list` shows `github/gh-stack`.
- `gh auth status` lists the `workflow` scope: agents push changes under
  `.github/workflows/` like any other, and GitHub rejects such a push without it
  (`gh auth refresh -h github.com -s workflow` adds it). The launcher does not check
  this one.
- Agents sign every commit with their own key, never the user's:
  - `git config commit.gpgsign` is `true` in the repository.
  - `git config agent.signingKey` holds a 1Password reference to the agent's SSH
    private key, such as `op://Private/Agent signing/private key`. It can differ per
    directory tree through `includeIf`.
  - The agent's public key is in `gpg.ssh.allowedSignersFile` for the repository's
    `user.email`, and is added to the user's GitHub account as a **Signing** key.
  - The user is present when the key is read from 1Password (see Signing key).
- The default branch should require signed commits (a ruleset), so an unverified
  commit fails the push instead of landing.
- Optional, through git config:
  - `agent.ompConfig`: an omp config overlay that the launcher passes to every omp
    agent with `--config`, for settings only unattended agents should get, such as a
    model from another family for their local reviewer, so that review does not share
    the author's blind spots. It should also set `completion.notify`, `ask.notify` and
    `error.notify` to `"off"` (quoted), or every agent notifies the user at the end of
    each turn.
  - `agent.notifyCommand`: a command that sends the user a notification, with a title
    as its argument and the message on standard input, for example a script that
    sends a phone notification. `parallel_issues.py notify` runs it, and so does
    `status --wait` when no session supervises the run.
  - `agent.sshProgram`: the program agents sign with, in place of `ssh-keygen`. It
    takes `ssh-keygen`'s arguments, so it can be a wrapper that runs an extra check
    before signing. The agents and `env` get it as `gpg.ssh.program`.

## Plan the batch

Planning happens with the user, before anything runs.

1. Collect the candidate issues: a milestone's open issues (`gh issue list --milestone
   <name>`, a milestone being one release) or the list the user gives. Read each one.
   Check its labels as well. Each issue needs exactly one change-type label from the
   repository's baseline: the launcher takes the branch type from it, following the
   `git-branch` skill's label table (see Launch), and falls back to `fix` when there
   is none. Fix a missing or misleading label with the user. Never create a label
   outside the repository's baseline; ask instead. The baseline, and the rule for
   deviations, are in the `github-workflow` skill's `references/repository-setup.md`
   (if installed).

From jmfontaine/agent-skills, Apache-2.0.

More from jmfontaine/agent-skills