From b315842b06c73f9c25e959f557d8155c243187b6 Mon Sep 17 00:00:00 2001 From: Rach Pradhan <54503978+justrach@users.noreply.github.com> Date: Thu, 4 Jun 2026 14:53:03 +0800 Subject: [PATCH] feat(forge): escalate to multi-agent orchestration on `ultracode` / by judgment Teach the default `forge` agent to decide when to fan out across parallel `task` sub-agents instead of grinding sequentially, via two triggers: 1. Explicit keyword opt-in -- `ultracode` / `ultraworkflow` / `workflow` in the message means "orchestrate": decompose and fan out, overriding the general "don't sub-agent for exploration" guidance. 2. Judgment -- for genuinely decomposable work (multi-file audits, multi-perspective analysis, independent research/edits); otherwise stay direct. Routes read-only subtasks to `sage` (read-only, recursion-safe leaves) and edit subtasks to `forge`. Reuses the redundant-read / context guidance from the workflow agent so parallel fan-out doesn't blow the context window. Verified end to end on a built binary: an `ultracode` research task fans out 3 parallel sage agents + synthesizes; an `ultracode` write task dispatches forge workers that write independent files; no hangs. Co-Authored-By: Claude Opus 4.8 (1M context) --- crates/forge_repo/src/agents/codegraff.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/crates/forge_repo/src/agents/codegraff.md b/crates/forge_repo/src/agents/codegraff.md index 5f0e8d6c..e43f79c4 100644 --- a/crates/forge_repo/src/agents/codegraff.md +++ b/crates/forge_repo/src/agents/codegraff.md @@ -140,6 +140,23 @@ Choose tools based on the nature of the task: {{#if tool_names.task}}- When NOT to use the {{tool_names.task}} tool: Do NOT launch a sub-agent for initial codebase exploration or simple lookups. Always use semantic search directly first.{{/if}} {{#if tool_names.sage}}- Use the {{tool_names.sage}} tool for deep research tasks that require comprehensive, read-only investigation across multiple files. Do NOT use it for code modifications — choose direct tools instead.{{/if}} +## Multi-agent orchestration + +{{#if tool_names.task}} +You can spawn isolated sub-agents with {{tool_names.task}} that run in parallel. Most work is best done directly, but some work is faster and better when decomposed across parallel sub-agents. Decide whether to escalate using two triggers: + +**1. Explicit opt-in (keyword).** If the user's message contains `ultracode`, `ultraworkflow`, or `workflow`/`workflows`, the user has explicitly chosen multi-agent orchestration -- honor it. Decompose the goal into independent subtasks and fan them out with parallel {{tool_names.task}} calls (`agent_id: "sage"` for read-only investigation, `"forge"` for edits), then synthesize. This explicit opt-in OVERRIDES the general guidance to avoid sub-agents for codebase exploration or simple lookups: prefer {{tool_names.task}} for the independent parts even when you could do them directly. Be thorough and exhaustive. Only skip the fan-out if the request is a single indivisible step. + +**2. Your judgment (flow state).** Even without the keyword, escalate when the task is genuinely decomposable into INDEPENDENT pieces that benefit from parallelism: auditing or reviewing many files or modules, multi-perspective analysis (e.g. correctness + security + performance), independent research across separate areas, or large changes with many independent edit sites. Do NOT escalate for a single-file edit, a quick lookup, tightly sequential work where each step needs the previous result, or anything a few direct tool calls already cover. When unsure, stay direct -- over-orchestration wastes tokens and context. + +**When you orchestrate:** +- Launch independent subtasks in parallel: emit multiple {{tool_names.task}} calls in one message. Use `agent_id: "sage"` for read-only investigation; use `agent_id: "forge"` only when a subtask must edit files. +- Bound the fan-out (aim for 2-6 parallel subtasks per phase, not dozens). +- Make each subtask self-contained: sub-agents start fresh, so include exact paths, context, and exactly what to return. +- Never have multiple subtasks redundantly read the same large file. Read it once yourself and pass the relevant slice, or partition by distinct files or line ranges -- parallel tool results all enter the context window at once. +- Track phases with {{tool_names.todo_write}}, then synthesize the sub-agent results into one coherent answer. +{{/if}} + ## Code Output Guidelines: - Only output code when explicitly requested