radimsem/forge-skills/blacksmith-orchestrate

Blacksmith Orchestrate

Schedule related tasks across worktrees, then dispatch one forge run per task.

Overview

Each dispatched task runs forge's twelve-step workflow. This skill decides which tasks can run together, what model and review depth each needs, and which worktree holds its changes.

Nine numbered steps, split by one gate, deliberately mirroring forge's shape:

Part 1 — Plan (1–5):     normalize → materialize → analyze → schedule → [GATE] battle plan
Part 2 — Execute (6–9):  provision → dispatch waves → relay → close-out
 
  gate held: no worktree is created and no forge Part 2 runs until "yes, forge them"

Every dispatched run must verify its Step 12 /goal before preparing a commit. No run writes back to its source issue or ticket, even with afk. Step 2 may file new issues through /to-tickets for plan and free-form routes, including under automode; forge Step 10 may likewise file spin-off issues. See references/entry-routes.md.

The Step 5 "yes, forge them" approval also selects commit and PR creation for every task named in the approved battle plan (see Step 7). With automode alone, no one makes that selection, so dispatched runs stop with a plan at Step 12 and push nothing. afk is the single sanctioned exception: it authorizes unattended commits, PRs, and blocking-PR merges. Terminal PRs and worktree cleanup remain with the user under every flag combination.

"The agent" means whatever agent runs this skill, and "one agent per task" means whatever subagent or parallel-run mechanism the runtime exposes. Adapt every reference (config directory, agent guide, interview UI, host CLI) to your runtime, exactly as forge does. If the runtime cannot run work in parallel at all, say so and fall back to running the waves sequentially rather than pretending to fan out.

Runtime

Use each runtime tool below when the host provides it. On other hosts, run the workflow sequentially.

On a non-Claude-Code runtime, give a one-line warning and analyze tasks inline. Run forge tasks sequentially in dependency order, with one worktree per component and no afk.

Parameters

Parse the invocation as /blacksmith-orchestrate <work-source> [orchestrator-flags] [forge-flags]. Flag words are orthogonal and can appear anywhere in the request, exactly as in forge. The <work-source> is one of five routes (one or more issue refs, a tracker container such as a milestone or epic or label, plan <path>, a quoted free-form goal, or resume) and routes may combine in a single invocation, so every task carries the route it arrived by. Read [references/entry-routes.md](references/entry-routes.md) for the route table, how the routes normalize into one task list, and how containers expand.

Full flag matrix (effects, composition rules, conflicts): [references/flags.md](references/flags.md).

Orchestrator flags

These are consumed by the orchestrator and are never passed through to a forge run. Each row's detail file owns that flag's behavior.

Every other flag forge understands passes through unchanged to every dispatched run: automode, docs, tdd, lookup, secure, changelog, ci-watch, compress, implement, codex, codex challenge, codex impl, coderabbit, and code-review. Two of forge's flags are overridden rather than passed through as written. worktree is always implied and orchestrator-managed, because Step 6 provisions, names and tracks every worktree itself and a run-level worktree decision cannot be delegated to the individual runs; passing it explicitly is accepted with a one-line note rather than treated as an error, since the user is asking for what already happens. automode lifts the Step 5 battle-plan gate exactly as it lifts forge's Step 6 gate, and still passes through to each dispatched run; it does not lift any hard floor named in the Overview.

When to Use

• /blacksmith-orchestrate <refs> with two or more issue or ticket refs.
• "ship this milestone", "implement this plan", "fix these five issues".
• A written implementation plan whose tasks should all land in one sitting.
• Any request to run several forge-shaped pieces of work together, where the ordering between them matters.
• Work too large even for one battle plan (more than one agent session can hold) goes to `/wayfinder` first: it maps the destination as decision tickets on the tracker, and the resulting ticket set comes back into this skill through the ordinary refs or container route, blocking edges included.

Don't use when:

• A single issue, ticket or PR is in scope. Use /forge <ref>: with one task there is no collision graph, no wave to schedule and no topology to choose, so the wrapper adds a second gate and buys nothing.
• No work source is given. Ask which issues, milestone or plan is meant rather than inferring a task list from the repo, for the reason in Step 1.

Step 1: Parse the invocation and normalize the work source

Split the invocation into three parts: the work source, the orchestrator flags from the Parameters table, and every remaining flag, which is forge pass-through. A token that matches neither the orchestrator flag table nor forge's own flag list is not assumed to be a pass-through flag: stop, name the token back to the user, and suggest the near miss when there is an obvious one: strct almost certainly meant strict. Forge lives with the same open-world assumption and pays for it once; here an unrecognized token is forwarded to every dispatched run and silently dropped by each, so a user who typed strct gets depth triage applied across the whole batch and finds out at close-out, which is the one place the cost of a typo scales with the wave. Route the work source into one canonical task list in which each task records the route it came from, because Step 3 chooses its analysis path per task rather than per run; the five routes, their combination rules and deduplication are in [references/entry-routes.md](references/entry-routes.md). If no work source resolves, a bare invocation, or flags with nothing to act on, stop and ask which issues, milestone or plan is meant; inferring a batch from the repo would dispatch work nobody asked for across several worktrees at once, which is far more expensive to undo than one question is to ask. If both unified and split are present, stop and report the conflict instead of applying a precedence, because the two ask for opposite PR topologies and silently honouring one would hide from the user which shape actually shipped.

Step 2: Materialize refs

Every task needs a stable identifier before analysis, because the battle plan, the ledger, the worktree names and each dispatched forge run all address tasks by ref. Ref and container routes already have one; the plan and free-form routes do not, so file real issues for those tasks with `/to-tickets` and adopt the returned refs, or fall back to synthetic T1..Tn IDs when the user declines filing. A synthetic ID is local to this run and never reaches a tracker, so any later step that would write to a tracker for such a task skips that write and names the skip in the Step 9 report. The free-form route carries one exception: under automode its tasks are never filed, unless the user named the split themselves, for example by enumerating the tasks in the goal, or by re-invoking with refs once they have seen the recorded split, because otherwise the split is the agent's own assumption rather than a detail of a human-written request; see the free-form decomposition section of [references/entry-routes.md](references/entry-routes.md). If a ref does not resolve to something its tracker can return, name it and ask whether to continue without it; under automode, drop it and record the omission in Step 9, because a silently missing task is indistinguishable from one that was never requested, and that is the single failure a batch run must never hide. Route mechanics, the /to-tickets handoff, container expansion and which trackers are supported, are in [references/entry-routes.md](references/entry-routes.md).

Scouts never interview

This rule is stated here because it governs every ref Step 2 hands onward. A scout dispatched in Step 3 that hits a forge Step 4 context gap returns the open question rather than asking it, and never blocks waiting for an answer. The orchestrator batches every task's open questions into one consolidated interview attached to the Step 5 gate, using forge's proposed-answer format with the most likely option marked (Recommended) and "Other" implicit. A scout that interviewed on its own would stall a parallel fan-out behind N separate prompts and would split into N approvals the single approval the gate exists to collect. Under automode the (Recommended) answer is taken for every open question and the assumption is recorded in the battle plan, exactly as forge does at its own Step 4.

Step 3: Analyze