Add multi-agent orchestration docs, update integrations, install, best practices, and workflows (#3)

devin-ai-integration[bot] · MatthewDailey · web-flow · commit 57cef21169cc · 2026-03-22T10:31:42.000-07:00
* Add multi-agent orchestration docs, update integrations, install, best practices, and workflows

- Task 1: Create plans/workflows/multi-agent.mdx with full orchestration docs
- Task 2: Rewrite integrations overview with cloud vs launcher agent distinction
- Task 3: Add agent orchestration tools and GitHub tools to MCP install page
- Task 4: Update best practices with new Manual topics and MCP install guidance
- Task 5: Add Agent Orchestration workflow section to workflows overview

Co-Authored-By: Matt Dailey &lt;matt@ref.tools&gt;

* Fix indentation in docs.json Workflows group

Co-Authored-By: Matt Dailey &lt;matt@ref.tools&gt;

---------

Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
Co-authored-by: Matt Dailey &lt;matt@ref.tools&gt;
diff --git a/docs.json b/docs.json
@@ -127,6 +127,7 @@
             "group": "Workflows",
             "pages": [
               "plans/workflows/overview",
+              "plans/workflows/multi-agent",
               "plans/workflows/claude-code-hook"
             ]
           },
diff --git a/plans/getting-started/best-practices.mdx b/plans/getting-started/best-practices.mdx
@@ -46,10 +46,32 @@ Plans are collaborative documents. Use comments in the chat panel to:
 
 ## Using Manual tool topics
 
-Ref's agent has built-in knowledge about plan structure. You can use these topics in the chat panel:
+Ref's agent has built-in knowledge about plan structure and workflows. You can use these topics in the chat panel via the `Manual` tool:
 
 - **`structure-a-plan`** — Ask the agent to organize your rough notes into a well-structured plan
 - **`update-a-plan`** — Ask the agent to revise the plan based on new information or progress
+- **`read-code-or-docs`** — Guidance on researching code and documentation using Ref tools before writing or updating plans
+
+### Role-based topics
+
+These topics are primarily used by the system during [multi-agent orchestration](/plans/workflows/multi-agent), but you can reference them directly too:
+
+- **`role-orchestrator`** — Workflow guidance for orchestrator agents managing teams of implementation and review agents. Covers how to launch agents, coordinate via messaging, and update the plan after merges.
+- **`role-implementer`** — Workflow guidance for coding agents creating PRs. Covers rules for implementation agents: focus on code, message parent with PR URL when done, don't update the plan.
+- **`role-reviewer`** — Workflow guidance for agents reviewing PRs. Covers how to use GitHub tools (`ReadPR`, `ReviewPR`, `MergePR`) to review diffs, approve, and report results to the orchestrator.
+
+## Install the MCP server in all your agents
+
+For the best results, install the Ref Plans MCP server in every coding agent you use — Cursor, Claude Code, Devin, and any others. This ensures:
+
+- **Full plan context** — Agents can read the plan directly instead of relying on a pasted prompt snippet
+- **Progress updates** — Agents can update the plan with progress and mark tasks complete as they work
+- **Built-in guidance** — Agents can use the `Manual` tool for workflow guidance
+- **Orchestration support** — Agents can communicate with the orchestrator via `SendMessage` during multi-agent workflows
+
+Without the MCP server, agents only see the initial prompt you send them. With it, they have access to the full plan, can report back, and can coordinate with other agents.
+
+See the [installation guide](/plans/install/index) for setup instructions for each agent.
 
 <Columns cols={2}>
 <Card icon="arrow-right" title="Workflows" href="/plans/workflows/overview">
diff --git a/plans/install/index.mdx b/plans/install/index.mdx
@@ -56,6 +56,46 @@ https://api.plan.ref.tools/mcp?teamId=<TEAM_ID>
 - `List` — List your plans
 - `Create` — Create a new plan
 
+### Agent orchestration tools
+
+When agent orchestration is enabled in Factory Settings, these additional tools become available in both plan-specific and general mode:
+
+- `LaunchAgent` — Launch a sub-agent on Cursor, Devin, or ref-thread to work in parallel. Specify the harness type, a prompt with full context, and the plan IDs to associate the agent with.
+- `SendMessage` — Send messages to child agents or back to a parent agent. Used for coordination — child agents report completion (with PR URLs), and parents send follow-up instructions.
+
+These tools require:
+1. **Factory Settings enabled** — Go to **Settings > Factory MCP** at [plan.ref.tools](https://plan.ref.tools) and toggle on the master switch
+2. **Per-harness toggles** — Enable the specific harnesses you want to use (Cursor, Devin)
+3. **API keys configured** — Set up Cursor and/or Devin API keys in **Settings > Agent Settings**
+
+The Factory Settings page also provides a ready-to-paste MCP config snippet for connecting your orchestrating agent.
+
+See the [multi-agent orchestration guide](/plans/workflows/multi-agent) for full details on using these tools.
+
+### GitHub tools
+
+A separate set of MCP tools for working with GitHub issues and pull requests is available at:
+
+```
+https://api.plan.ref.tools/github-mcp
+```
+
+These tools are available when GitHub is connected and repos are indexed:
+
+- `GetIssue` — Get issue details and comments from an indexed repository
+- `CommentOnIssue` — Post a comment on a GitHub issue
+- `SearchIssues` — Search issues in an indexed repository
+- `ReadPR` — Read PR details, list changed files, and read diffs for specific files
+- `ReviewPR` — Submit a review (approve, request changes, comment) on a PR
+- `MergePR` — Merge a PR or mark a draft PR as ready for review
+- `SearchPRs` — Search pull requests in an indexed repository
+
+These tools require:
+1. **GitHub account connected** at [ref.tools/resources](https://ref.tools/resources)
+2. **Repos added** — Add the repositories you want to use with GitHub tools
+
+`ReviewPR` and `MergePR` availability depends on your GitHub permissions settings. See the [GitHub integration page](/plans/integrations/github) for setup details.
+
 ---
 
 ## Installation Guides
diff --git a/plans/integrations/overview.mdx b/plans/integrations/overview.mdx
@@ -5,22 +5,37 @@ description: "Connect Ref Plans to coding agents and external services."
 
 Ref Plans integrates with coding agents (where you send tasks for implementation) and context sources (where you pull planning context from).
 
-## Agent destinations
+## Cloud agents (API-based)
 
-When a task is ready, you can send it to one of these agents to implement the code:
+Cloud agents connect directly through API keys. Ref launches the agent and tracks its progress automatically — no manual intervention required. These agents can also be launched programmatically by an orchestrator agent via the [`LaunchAgent`](/plans/workflows/multi-agent) MCP tool as part of [multi-agent orchestration](/plans/workflows/multi-agent).
 
-| Agent | Type | Description |
-| --- | --- | --- |
-| [Cursor Background Agents](/plans/integrations/cursor) | API | Launches a Cursor background agent via API key |
-| [Devin](/plans/integrations/devin) | API | Launches a Devin session via API key |
-| [Claude Code Web](/plans/integrations/claude-code-web) | Webhook | Sends task to Claude Code in the cloud |
-| [Codex](/plans/integrations/codex) | Webhook | Sends task to OpenAI Codex |
-| Cursor Local | Webhook | Sends task to your local Cursor instance |
-| Copy & Paste | Webhook | Copies the task prompt for manual use in any agent |
+| Agent | Description |
+| --- | --- |
+| [Cursor Background Agents](/plans/integrations/cursor) | Launches a Cursor background agent via API key. Writes code, creates branches, and opens PRs. |
+| [Devin](/plans/integrations/devin) | Launches a Devin session via API key. Writes code, creates branches, and opens PRs. |
+
+Cloud agents provide:
+- **Automatic launch** — Ref starts the agent session for you
+- **Status tracking** — Progress updates flow back to Ref automatically
+- **Orchestration support** — Can be launched by an orchestrator agent via `LaunchAgent` with `harness: "cursor"` or `harness: "devin"`
+
+Configure API keys in **Settings > Agent Settings** at [plan.ref.tools](https://plan.ref.tools).
 
-**API-based agents** connect directly through API keys. Ref launches the agent and tracks its progress automatically.
+## Launcher agents (webhook-based)
+
+Launcher agents work by appending progress-reporting instructions (curl commands) to the task prompt. You initiate the agent session yourself, and the agent reports back to Ref by executing the webhook commands included in the prompt.
+
+| Agent | Description |
+| --- | --- |
+| [Claude Code Web](/plans/integrations/claude-code-web) | Sends task to Claude Code in the cloud |
+| [Codex](/plans/integrations/codex) | Sends task to OpenAI Codex |
+| Cursor Local | Sends task to your local Cursor instance |
+| Copy & Paste | Copies the task prompt for manual use in any agent |
 
-**Webhook-based agents** work by appending progress-reporting instructions to the task prompt. The agent reports back to Ref via curl commands included in the prompt.
+Launcher agents require you to:
+1. Click **Launch Agent** in the plan UI to generate the prompt
+2. Start the agent session yourself (or paste the prompt)
+3. The agent executes the embedded webhook commands to report progress back to Ref
 
 ## Context sources
 
diff --git a/plans/workflows/multi-agent.mdx b/plans/workflows/multi-agent.mdx
@@ -0,0 +1,108 @@
+---
+title: "Multi-Agent Orchestration"
+description: "Launch and coordinate multiple coding agents working in parallel from a single plan."
+---
+
+import GetHelp from '/snippets/get-help.mdx';
+
+Multi-agent orchestration lets a Ref agent (the orchestrator) spawn sub-agents on Cursor, Devin, or internal ref-threads, send them messages, and receive updates back — all via MCP tools. This is the most automated way to use Ref Plans.
+
+## How it works
+
+An orchestrator agent reads your plan, then launches child agents to implement and review tasks in parallel. The agents communicate through a parent/child messaging system — no polling required.
+
+```mermaid
+graph TD
+    A[Orchestrator Agent] -->|LaunchAgent: cursor| B[Cursor Agent - Task 1]
+    A -->|LaunchAgent: devin| C[Devin Agent - Task 2]
+    B -->|SendMessage: PR URL| A
+    C -->|SendMessage: PR URL| A
+    A -->|LaunchAgent: ref-thread| D[Reviewer Agent]
+    D -->|SendMessage: Review results| A
+```
+
+## The tools
+
+Two MCP tools power orchestration:
+
+### LaunchAgent
+
+Launches a sub-agent to work in parallel. Available harness types:
+
+| Harness | Use for | What it does |
+| --- | --- | --- |
+| `cursor` | Implementation tasks | Launches a Cursor background agent that writes code and creates PRs |
+| `devin` | Implementation tasks | Launches a Devin session that writes code and creates PRs |
+| `ref-thread` | Review and lightweight tasks | Launches an internal Ref agent that can read PRs, review diffs, approve, and merge |
+
+Key parameters:
+- **`planIds`** — Plan IDs the agent should be associated with
+- **`prompt`** — The complete task request with all context, requirements, and instructions
+- **`harness`** — Where to run the agent: `cursor`, `devin`, or `ref-thread`
+- **`taskShortDescription`** — Brief label for the agent (~10 words)
+- **`repo`** / **`branch`** / **`model`** — Optional overrides (Cursor only)
+
+### SendMessage
+
+Sends a message between parent and child agents. This is how agents communicate:
+
+- **Child agents** MUST message their parent when work is complete (including the PR URL) or when stuck
+- **Parent agents** use this to send follow-up instructions or course corrections
+
+Parameters:
+- **`agentId`** — The agent to send the message to
+- **`message`** — The message content
+
+## Typical workflow
+
+<Steps>
+  <Step title="Plan">
+    Research and iterate on your plan in the web client or via MCP. Break work into tasks that can be implemented independently.
+  </Step>
+  <Step title="Orchestrate">
+    An orchestrator agent reads the plan and launches implementation agents (Cursor, Devin) in parallel via `LaunchAgent`. Each agent gets a self-contained prompt with all the context it needs.
+  </Step>
+  <Step title="Review">
+    As implementation agents finish and report back with PR URLs, the orchestrator launches `ref-thread` agents to review each PR. Reviewers have access to GitHub tools (`ReadPR`, `ReviewPR`, `MergePR`) to inspect diffs and approve.
+  </Step>
+  <Step title="Merge and update">
+    Once reviewers approve, they merge the PRs (if permitted). The orchestrator updates the plan to mark tasks complete. Repeat until the plan is done.
+  </Step>
+</Steps>
+
+## Example session
+
+Here's what a typical orchestration session looks like:
+
+1. The orchestrator reads the plan and identifies three independent tasks
+2. It launches two Cursor agents for Task 1 and Task 2 in parallel, and a Devin agent for Task 3
+3. Task 1's agent finishes first and messages back: *"Task complete. PR: https://github.com/org/repo/pull/42"*
+4. The orchestrator launches a ref-thread reviewer to review PR #42
+5. Task 2's agent finishes and messages back with its PR URL
+6. The reviewer approves and merges PR #42, then messages the orchestrator with results
+7. The orchestrator updates the plan, marking Task 1 complete
+8. The process continues until all tasks are implemented, reviewed, and merged
+
+## Harness selection guide
+
+**Use `cursor` or `devin` for implementation** — these agents write code, create branches, and open PRs. Choose based on which service you have configured and prefer.
+
+**Use `ref-thread` for reviews** — ref-thread agents have access to GitHub PR tools (`ReadPR`, `ReviewPR`, `MergePR`, `SearchPRs`) that Cursor and Devin agents do not. Always use ref-thread for PR review tasks.
+
+## Requirements
+
+To use multi-agent orchestration, you need:
+
+1. **Ref Plans MCP server installed** in your orchestrating agent — see the [install guide](/plans/install/index)
+2. **Agent orchestration enabled** in [Factory Settings](https://plan.ref.tools/settings) — toggle on the master switch and enable the harnesses you want to use
+3. **API keys configured** for Cursor and/or Devin in [Agent Settings](https://plan.ref.tools/settings) — required for `cursor` and `devin` harnesses
+4. **GitHub connected** at [ref.tools/resources](https://ref.tools/resources) — required for ref-thread reviewers to access PR tools
+
+## Parent/child messaging rules
+
+- Child agents **must** message their parent when done (include the PR URL if one was created) or when stuck
+- Parents can send follow-up instructions or corrections to any child via `SendMessage`
+- Agents can only message their direct parent or their own children — no cross-communication
+- The workflow is message-driven: after launching agents, wait for messages rather than polling
+
+<GetHelp/>
diff --git a/plans/workflows/overview.mdx b/plans/workflows/overview.mdx
@@ -22,6 +22,21 @@ Use Ref as your main driver and orchestrator. This is a two-phase workflow:
   allowFullScreen
 ></iframe>
 
+## Agent Orchestration
+
+For fully automated multi-agent workflows. An orchestrator agent manages the entire cycle — launching implementation agents, coordinating reviews, and merging PRs — with minimal human intervention.
+
+1. **Plan** — Research and iterate on the plan in the web client or via MCP.
+2. **Orchestrate** — An orchestrator agent launches implementation agents (Cursor, Devin) in parallel via `LaunchAgent`. Each agent gets a self-contained prompt with all context.
+3. **Review** — The orchestrator launches `ref-thread` agents to review PRs. Reviewers read diffs, approve, and report back.
+4. **Merge** — Ref agents merge approved PRs. The orchestrator updates the plan and repeats until done.
+
+This builds on "Plan and Polish" by automating the launch, review, and merge phases. It requires the MCP server installed, agent API keys configured, and Factory Settings enabled.
+
+<Card icon="robot" title="Multi-Agent Orchestration Guide" href="/plans/workflows/multi-agent">
+Full guide to launching and coordinating multiple agents from a plan.
+</Card>
+
 ## Linear / GitHub-driven planning
 
 Pull context from your project management tools directly into your plans.

Original file line number	Diff line number	Diff line change
`@@ -127,6 +127,7 @@`
`127`	`127`	`"group": "Workflows",`
`128`	`128`	`"pages": [`
`129`	`129`	`"plans/workflows/overview",`
	`130`	`+ "plans/workflows/multi-agent",`
`130`	`131`	`"plans/workflows/claude-code-hook"`
`131`	`132`	`]`
`132`	`133`	`},`