/orchestrate

description: Orchestrate several issues in parallel — launches one lean work-on lane per issue (background shell or agent), GitHub is the register
argument-hint: "<#1 #2 #3 | milestone <slug> | label <name>> [--parallel K] [--path full]"

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/orchestrate — parallel lean work-on lanes

**Input**: $ARGUMENTS

You are the orchestrator. Resolve the issues, order them, and run each one in its own lane. Each lane runs the lean work-on (validate → plan → implement → fix/regression review → PR → merge), which records every step on the issue. You triage and order the set yourself (no sub-agent investigations), but never implement an issue yourself.

1. Legacy path

If the input contains `--path full`, stop: read `${CLAUDE_PLUGIN_ROOT}/commands/orchestrate/legacy.md` and follow it instead (the previous multi-phase orchestrator).

2. Resolve, triage and build the DAG

Do this yourself from issue text and the code. Spawn no sub-agents here.

1. **Resolve.**

• Explicit numbers (`#12 13 14`) are used as given.
• `milestone <slug>` uses `gh issue list --milestone "<slug>" --state open --json number --jq '.[].number'`.
• `label <name>` uses the same with `--label`.

Keep only plain integers and drop closed issues. 2. **Pre-filter already-fixed issues** (when `forgedock` is on PATH). Before reading anything else, run once for the whole set:

   forgedock triage <N...> --parallel <K>

It closes, with the evidence on the issue and no lane, every issue that a merged PR already fixed (one short read-only validation on a small model) or an auto-filed CI failure whose workflow is green again (the green run link), unless it is flaky (wording or `flaky` label), was reopened after a pre-filter close, or the workflow failed and passed at the same SHA. It checks K issues at a time. Its last line is `lanes: #A #B ...`: continue with only those issues. This is the only pre-filter in this command: lanes run `forgedock run-issue`, which does not pre-filter again. Keep its `pre-filter:` line for the report. 3. **Triage.** For each issue, read it once (`gh issue view N --json title,body,labels`) and record:

• **Ready / skip.** Skip when it is labelled `needs-human` or `workflow:merged`, or an open PR already

closes it (`gh pr list --search "Closes #N" --state open`). Say why.

• **Files.** The files or areas it will likely touch: paths named in the issue, or a quick

`git grep` of the symbols it names. Keep this to a few greps per issue, not an investigation.

• **Size.** S, M or L, from the scope the issue describes.

4. **Build the DAG.** Edge X → N means N waits until X merges:

• **Explicit:** `Depends on #X` / `Blocked by #X` where X is in the set. Match it case-insensitively and

also in bold or list form (`**Depends on** #X`, `- Depends on: #X, #Y`). An open X outside the set means N is skipped as blocked.

• **Logical:** one issue's fix is needed by another (for example, it adds the helper the other uses).

These are the only edges. File overlap is **never** an edge: two issues that touch the same file or function still run in parallel, because each lane merges `origin/<lane>` into a conflicting PR and resolves the conflict itself. Note the overlap in the plan table as a warning only.

If you find a cycle, break it at the weakest (logical) edge and say so. 5. **Show the plan** as one table: issue, title, size, likely files, waits-on (explicit/logical only), overlaps (warning). There are no waves. Then proceed without asking.

`K` = `--parallel` if given, otherwise `orchestration.max_concurrent` from the repo's `forge.yaml` (`yq '.orchestration.max_concurrent' forge.yaml`), otherwise 3. State the value of K and where it came from in the plan.

**Lanes (base branches).** Each issue has its own lane, and ForgeDock works it out: an issue with a milestone goes to forge.yaml `branches.feature_pattern` (`milestone/<slug>`, which must exist on origin), any other issue to `branches.staging`. The default (production) branch is never a lane. Do not pass `--lane`; a `--lane` that differs from the issue's lane is refused (`lane-refused`, `lane.mismatch`). A dependency edge between two lanes (for example a milestone issue waiting on a staging-lane fix) never gets that fix on its base: list it in the plan and either re-milestone the dependency or wait for a milestone sync. Never mix lanes silently.

3. Launch lanes

Schedule from the DAG, not in waves. An issue is **ready** when every issue it waits on has merged (or it waits on nothing). Keep at most K lanes running. Whenever a lane is free, start the highest-priority ready issue right away (priority label first, then the smaller size). Never hold a ready issue back until other lanes finish. To reduce simultaneous base-syncs, don't start two lanes that name the same function within the same minute; start another ready issue first instead of waiting.

**Maintenance budget** (off unless forge.yaml `maintenance.enabled: true`). The runner pulls open issues carrying a `maintenance.labels` label into the batch and admits in this order: P0/P1 features > maintenance, while maintenance starts stay within `maintenance.share` of all starts (0.2 = 1 lane in 5) > P2+ features. With `when_idle` it drains the remaining maintenance once no feature is pending; otherwise the rest ends `held (maintenance share)` for a later batch.

• **Batch runner (default, when `forgedock` is on PATH).** Launch the whole set as one durable batch in a single

`Bash` call with `run_in_background: true`. Do NOT write a scheduler, wrapper or queue script, and do not launch one `run-issue` per issue yourself: the runner schedules from the issues' `Depends on` / `Blocked by` lines.

  forgedock orchestrate <N...> --parallel K

Its first line is `batch: <id> (...)`. T