From 937c75bc51ae9ac6daae693d8dc03bc98058ac90 Mon Sep 17 00:00:00 2001
From: dianed-square <73617011+dianed-square@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:32:48 -0700
Subject: [PATCH] docs: remove subagents from experimental (#4907)
---
.../index.md | 6 +++---
.../blog/2025-07-28-ai-to-ai/index.md | 2 +-
.../index.md | 2 +-
.../index.md | 2 +-
.../index.md | 2 +-
.../index.md | 2 +-
documentation/docs/experimental/index.md | 10 +++++-----
documentation/docs/guides/acp-clients.md | 2 +-
documentation/docs/guides/allowlist.md | 2 +-
documentation/docs/guides/cli-providers.md | 2 +-
documentation/docs/guides/config-file.md | 4 ++--
.../docs/guides/enhanced-code-editing.md | 1 +
.../docs/guides/environment-variables.md | 4 ++--
documentation/docs/guides/file-management.md | 2 +-
.../docs/guides/goose-cli-commands.md | 2 +-
.../docs/guides/goose-permissions.md | 2 +-
.../handling-llm-rate-limits-with-goose.md | 2 +-
.../guides/interactive-chat/_category_.json | 2 +-
documentation/docs/guides/logs.md | 2 +-
.../docs/guides/managing-projects.md | 2 +-
.../guides/managing-tools/_category_.json | 2 +-
.../docs/guides/multi-model/_category_.json | 2 +-
.../docs/guides/recipes/_category_.json | 2 +-
documentation/docs/guides/running-tasks.md | 2 +-
.../{experimental => guides}/subagents.md | 20 +------------------
documentation/docs/guides/tips.md | 2 +-
documentation/docs/guides/updating-goose.md | 2 +-
documentation/docs/guides/using-goosehints.md | 2 +-
.../docs/guides/using-gooseignore.md | 2 +-
.../plan-feature-devcontainer-setup.md | 2 +-
documentation/docusaurus.config.ts | 4 ++++
31 files changed, 42 insertions(+), 55 deletions(-)
rename documentation/docs/{experimental => guides}/subagents.md (94%)
diff --git a/documentation/blog/2025-07-21-orchestrating-subagents/index.md b/documentation/blog/2025-07-21-orchestrating-subagents/index.md
index dd7449d3..987f06f6 100644
--- a/documentation/blog/2025-07-21-orchestrating-subagents/index.md
+++ b/documentation/blog/2025-07-21-orchestrating-subagents/index.md
@@ -36,7 +36,7 @@ I decided to create a digital resource that teaches foundational concepts like A
## Meet the Subagents
-[Subagents](/docs/experimental/subagents) are individual AI instances that take on specific tasks. Each one runs in its own session, which helps preserve the main context window and keeps your primary Goose conversation uncluttered and focused on high-level orchestration. I think of subagents as temporary teammates. Goose assigns each subagent a job and deallocates it when the work is complete.
+[Subagents](/docs/guides/subagents) are individual AI instances that take on specific tasks. Each one runs in its own session, which helps preserve the main context window and keeps your primary Goose conversation uncluttered and focused on high-level orchestration. I think of subagents as temporary teammates. Goose assigns each subagent a job and deallocates it when the work is complete.
For this project, I turned my subagents into an on-demand dev squad, and I assigned them the following roles:
@@ -58,7 +58,7 @@ export GOOSE_ALPHA_FEATURES=true
## Instructing My Team
-There are a few ways to create subagents in Goose. You can use natural language prompts, define them through [recipes](/docs/guides/recipes/), or even spin up [external subagents](/docs/experimental/subagents/#external-subagents) like Codex or Claude Code.
+There are a few ways to create subagents in Goose. You can use natural language prompts, define them through [recipes](/docs/guides/recipes/), or even spin up [external subagents](/docs/guides/subagents/#external-subagents) like Codex or Claude Code.
I took the natural language prompt approach because it felt convenient to directly configure a subagent through one prompt. Here’s the prompt I used:
@@ -173,7 +173,7 @@ What will you build with subagents?
[Download Goose](/)
-[Learn about subagents](/docs/experimental/subagents)
+[Learn about subagents](/docs/guides/subagents)
diff --git a/documentation/blog/2025-07-28-ai-to-ai/index.md b/documentation/blog/2025-07-28-ai-to-ai/index.md
index 233b8e44..6eff5357 100644
--- a/documentation/blog/2025-07-28-ai-to-ai/index.md
+++ b/documentation/blog/2025-07-28-ai-to-ai/index.md
@@ -406,7 +406,7 @@ Angie's Diner shows exceptional performance with premium order values and strong
-What a fun experiment! This gave me a better understanding of how agent-to-agent and [subagent](/docs/experimental/subagents) workflows may work behind the scenes. Makes you wonder, what else could happen when AIs start talking to each other without us?
+What a fun experiment! This gave me a better understanding of how agent-to-agent and [subagent](/docs/guides/subagents) workflows may work behind the scenes. Makes you wonder, what else could happen when AIs start talking to each other without us?
---
diff --git a/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md b/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md
index 3d9aadb4..228fda9d 100644
--- a/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md
+++ b/documentation/blog/2025-08-13-pulse-mcp-automates-recipe/index.md
@@ -21,7 +21,7 @@ Every week, the PulseMCP team faced the same time-consuming workflow: sourcing r
## The Solution: Why Sequential Beats Monolithic
-Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [subrecipes](/docs/guides/recipes/subrecipes) and [subagents](/docs/experimental/subagents) with clear inputs, outputs, and a single job.
+Instead of building one massive "do-everything" agent (which inevitably fails on complex tasks), PulseMCP broke their workflow into six distinct phases. Each phase gets handled by focused [recipes](/docs/guides/recipes/session-recipes), [subrecipes](/docs/guides/recipes/subrecipes) and [subagents](/docs/guides/subagents) with clear inputs, outputs, and a single job.
This approach has three main benefits: debugging becomes easier when agents have single responsibilities, results become more predictable with clear handoffs between stages, and humans stay in control of the editorial process while automating the tedious work.
diff --git a/documentation/blog/2025-08-14-agent-coordination-patterns/index.md b/documentation/blog/2025-08-14-agent-coordination-patterns/index.md
index c868cebc..919afdfc 100644
--- a/documentation/blog/2025-08-14-agent-coordination-patterns/index.md
+++ b/documentation/blog/2025-08-14-agent-coordination-patterns/index.md
@@ -36,7 +36,7 @@ Think lone developer grinding through the ticket.
## The Subagent Setup: Orchestrator With a Crew
-With [subagents](/docs/experimental/subagents), you still have one "main" agent, but instead of doing everything, it plays tech lead and delegates pieces of the work to other specialized agents.
+With [subagents](/docs/guides/subagents), you still have one "main" agent, but instead of doing everything, it plays tech lead and delegates pieces of the work to other specialized agents.
The main agent says:
diff --git a/documentation/blog/2025-08-18-understanding-context-windows/index.md b/documentation/blog/2025-08-18-understanding-context-windows/index.md
index 4ed2107e..bcbad557 100644
--- a/documentation/blog/2025-08-18-understanding-context-windows/index.md
+++ b/documentation/blog/2025-08-18-understanding-context-windows/index.md
@@ -81,7 +81,7 @@ The [Memory extension](https://block.github.io/goose/docs/mcp/memory-mcp) stores
**5. Subagents**
-[Subagents](https://block.github.io/goose/docs/experimental/subagents) handle specific tasks in their own isolated sessions. This prevents your main conversation from getting cluttered with implementation details and tool outputs. You delegate work to subagents and only see the final results, keeping your primary context window clean and focused.
+[Subagents](https://block.github.io/goose/docs/guides/subagents) handle specific tasks in their own isolated sessions. This prevents your main conversation from getting cluttered with implementation details and tool outputs. You delegate work to subagents and only see the final results, keeping your primary context window clean and focused.
**6. Short sessions**
diff --git a/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md b/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md
index ada98657..cfab1883 100644
--- a/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md
+++ b/documentation/blog/2025-09-26-subagents-vs-subrecipes/index.md
@@ -7,7 +7,7 @@ authors:
-When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/experimental/subagents/) and [subrecipes](/docs/tutorials/subrecipes-in-parallel/). Both can run multiple AI instances in parallel, but they work differently. Picking which one to use can be confusing, so we're going to guide you to a decision.
+When you're working on complex projects with goose, you'll often need to break work into multiple tasks and run them with AI agents. Goose gives you two powerful ways to do this: [subagents](/docs/guides/subagents/) and [subrecipes](/docs/tutorials/subrecipes-in-parallel/). Both can run multiple AI instances in parallel, but they work differently. Picking which one to use can be confusing, so we're going to guide you to a decision.
I've been using both approaches, and the choice between them depends on what you're trying to accomplish. Let me break down when to use each method and show you real examples.
diff --git a/documentation/docs/experimental/index.md b/documentation/docs/experimental/index.md
index 57e18936..d5a155d9 100644
--- a/documentation/docs/experimental/index.md
+++ b/documentation/docs/experimental/index.md
@@ -19,11 +19,6 @@ The list of experimental features may change as Goose development progresses. So
🧪 Experimental Features
-
+
diff --git a/documentation/docs/guides/acp-clients.md b/documentation/docs/guides/acp-clients.md
index 1840f5b9..0f072d9e 100644
--- a/documentation/docs/guides/acp-clients.md
+++ b/documentation/docs/guides/acp-clients.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 25
+sidebar_position: 105
title: Using Goose in ACP Clients
sidebar_label: Goose in ACP Clients
---
diff --git a/documentation/docs/guides/allowlist.md b/documentation/docs/guides/allowlist.md
index 5a1f3081..d6154088 100644
--- a/documentation/docs/guides/allowlist.md
+++ b/documentation/docs/guides/allowlist.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 19
+sidebar_position: 90
title: Goose Extension Allowlist
sidebar_label: Extension Allowlist
---
diff --git a/documentation/docs/guides/cli-providers.md b/documentation/docs/guides/cli-providers.md
index 0d336443..5d99d41e 100644
--- a/documentation/docs/guides/cli-providers.md
+++ b/documentation/docs/guides/cli-providers.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 8
+sidebar_position: 45
title: CLI Providers
sidebar_label: CLI Providers
description: Use Claude Code, Cursor Agent, or Gemini CLI subscriptions in Goose
diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-file.md
index 0361d386..b5789135 100644
--- a/documentation/docs/guides/config-file.md
+++ b/documentation/docs/guides/config-file.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 15
+sidebar_position: 85
title: Configuration File
sidebar_label: Configuration File
---
@@ -47,7 +47,7 @@ These settings enable experimental features that are in active development. Thes
| Setting | Purpose | Values | Default | Required |
|---------|---------|---------|---------|-----------|
-| `ALPHA_FEATURES` | Enables experimental alpha features like [subagents](/docs/experimental/subagents) | true/false | false | No |
+| `ALPHA_FEATURES` | Enables access to experimental alpha features—check the feature docs to see if this flag is required | true/false | false | No |
Additional [environment variables](/docs/guides/environment-variables) may also be supported in config.yaml.
diff --git a/documentation/docs/guides/enhanced-code-editing.md b/documentation/docs/guides/enhanced-code-editing.md
index 6c894f68..59345976 100644
--- a/documentation/docs/guides/enhanced-code-editing.md
+++ b/documentation/docs/guides/enhanced-code-editing.md
@@ -2,6 +2,7 @@
title: Enhanced Code Editing with AI Models
sidebar_label: Enhanced Code Editing
description: Use AI models to intelligently apply code changes
+sidebar_position: 110
---
The [Developer extension](/docs/mcp/developer-mcp) supports using AI models for enhanced code editing through the `str_replace` command. When configured, it intelligently applies code changes using an AI model instead of simple string replacement.
diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 2906b0fb..043a10da 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 20
+sidebar_position: 95
title: Environment Variables
sidebar_label: Environment Variables
---
@@ -319,7 +319,7 @@ These variables enable experimental features that are in active development. The
| Variable | Purpose | Values | Default |
|----------|---------|---------|---------|
-| `ALPHA_FEATURES` | Enables experimental alpha features like [subagents](/docs/experimental/subagents) | "true", "1" (case insensitive) to enable | false |
+| `ALPHA_FEATURES` | Enables experimental alpha features—check the feature docs to see if this flag is required | "true", "1" (case insensitive) to enable | false |
**Examples**
diff --git a/documentation/docs/guides/file-management.md b/documentation/docs/guides/file-management.md
index d210782a..391a11df 100644
--- a/documentation/docs/guides/file-management.md
+++ b/documentation/docs/guides/file-management.md
@@ -1,6 +1,6 @@
---
title: File Access and Management
-sidebar_position: 10
+sidebar_position: 70
sidebar_label: File Management
description: Efficiently find and reference files in Goose Desktop and follow best practices for safe file operations
---
diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md
index 01aa660b..80e7d85b 100644
--- a/documentation/docs/guides/goose-cli-commands.md
+++ b/documentation/docs/guides/goose-cli-commands.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 7
+sidebar_position: 35
title: CLI Commands
sidebar_label: CLI Commands
toc_max_heading_level: 4
diff --git a/documentation/docs/guides/goose-permissions.md b/documentation/docs/guides/goose-permissions.md
index 1756e3a5..b842c26c 100644
--- a/documentation/docs/guides/goose-permissions.md
+++ b/documentation/docs/guides/goose-permissions.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 6
+sidebar_position: 25
title: Goose Permission Modes
sidebar_label: Goose Permissions
---
diff --git a/documentation/docs/guides/handling-llm-rate-limits-with-goose.md b/documentation/docs/guides/handling-llm-rate-limits-with-goose.md
index 4fed152b..34d7e4e3 100644
--- a/documentation/docs/guides/handling-llm-rate-limits-with-goose.md
+++ b/documentation/docs/guides/handling-llm-rate-limits-with-goose.md
@@ -1,7 +1,7 @@
---
title: Set LLM Rate Limits
sidebar_label: LLM Rate Limits
-sidebar_position: 9
+sidebar_position: 60
---
import Tabs from '@theme/Tabs';
diff --git a/documentation/docs/guides/interactive-chat/_category_.json b/documentation/docs/guides/interactive-chat/_category_.json
index 488d3ef1..77f153aa 100644
--- a/documentation/docs/guides/interactive-chat/_category_.json
+++ b/documentation/docs/guides/interactive-chat/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Rich Interactive Chat",
- "position": 8,
+ "position": 55,
"link": {
"type": "doc",
"id": "guides/interactive-chat/index"
diff --git a/documentation/docs/guides/logs.md b/documentation/docs/guides/logs.md
index 471b23b9..3521af31 100644
--- a/documentation/docs/guides/logs.md
+++ b/documentation/docs/guides/logs.md
@@ -1,7 +1,7 @@
---
title: Goose Logging System
sidebar_label: Logging System
-sidebar_position: 9
+sidebar_position: 65
---
diff --git a/documentation/docs/guides/managing-projects.md b/documentation/docs/guides/managing-projects.md
index c566739c..f8c9d055 100644
--- a/documentation/docs/guides/managing-projects.md
+++ b/documentation/docs/guides/managing-projects.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 15
title: Managing Projects
sidebar_label: Managing Projects
---
diff --git a/documentation/docs/guides/managing-tools/_category_.json b/documentation/docs/guides/managing-tools/_category_.json
index c079497e..42511b34 100644
--- a/documentation/docs/guides/managing-tools/_category_.json
+++ b/documentation/docs/guides/managing-tools/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Managing Tools",
- "position": 4,
+ "position": 15,
"link": {
"type": "doc",
"id": "guides/managing-tools/index"
diff --git a/documentation/docs/guides/multi-model/_category_.json b/documentation/docs/guides/multi-model/_category_.json
index 85bc7259..93914bf5 100644
--- a/documentation/docs/guides/multi-model/_category_.json
+++ b/documentation/docs/guides/multi-model/_category_.json
@@ -1,5 +1,5 @@
{
"label": "Multi-Model Config",
- "position": 20,
+ "position": 100,
"description": "Configure multiple models and providers for model-switching strategies."
}
diff --git a/documentation/docs/guides/recipes/_category_.json b/documentation/docs/guides/recipes/_category_.json
index d2c9819d..80cd80ec 100644
--- a/documentation/docs/guides/recipes/_category_.json
+++ b/documentation/docs/guides/recipes/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Recipes",
- "position": 2,
+ "position": 5,
"link": {
"type": "doc",
"id": "guides/recipes/index"
diff --git a/documentation/docs/guides/running-tasks.md b/documentation/docs/guides/running-tasks.md
index 10dd3596..e0fb2400 100644
--- a/documentation/docs/guides/running-tasks.md
+++ b/documentation/docs/guides/running-tasks.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 13
+sidebar_position: 75
title: Running Tasks
sidebar_label: Run Tasks
---
diff --git a/documentation/docs/experimental/subagents.md b/documentation/docs/guides/subagents.md
similarity index 94%
rename from documentation/docs/experimental/subagents.md
rename to documentation/docs/guides/subagents.md
index 34982c97..59863e9b 100644
--- a/documentation/docs/experimental/subagents.md
+++ b/documentation/docs/guides/subagents.md
@@ -1,15 +1,11 @@
---
title: Subagents
-sidebar_position: 1
+sidebar_position: 50
sidebar_label: Subagents
---
Subagents are independent instances that execute tasks while keeping your main conversation clean and focused. They bring process isolation and context preservation by offloading work to separate instances. Think of them as temporary assistants that handle specific jobs without cluttering your chat with tool execution details.
-:::warning
-Subagents are an experimental feature in active development. Behavior and configuration may change in future releases.
-:::
-
## How to Use Subagents
To use subagents, ask Goose to delegate tasks using natural language. Goose automatically decides when to spawn subagents and handles their lifecycle. You can:
@@ -30,20 +26,6 @@ You can run multiple subagents sequentially or in parallel.
If a subagent fails or times out (5-minute default), you will receive no output from that subagent. For parallel execution, if any subagent fails, you get results only from the successful ones.
:::
-
-## Prerequisites
-To use subagents, you need to enable alpha features first. You can do this by setting an [environment variable](/docs/guides/environment-variables#experimental-features) or adding it to your [config file](/docs/guides/config-file#experimental-features):
-
-**Environment Variable:**
-```bash
-export ALPHA_FEATURES=true
-```
-
-**Config File** (`~/.config/goose/config.yaml`):
-```yaml
-ALPHA_FEATURES: true
-```
-
## Internal Subagents
Internal subagents spawn Goose instances to handle tasks using your current session's context and extensions. There are two ways to configure and execute internal subagents:
diff --git a/documentation/docs/guides/tips.md b/documentation/docs/guides/tips.md
index b6b1bc09..a5e4a1f9 100644
--- a/documentation/docs/guides/tips.md
+++ b/documentation/docs/guides/tips.md
@@ -1,6 +1,6 @@
---
title: Quick Goose Tips
-sidebar_position: 6
+sidebar_position: 30
sidebar_label: Quick Tips
description: Best practices for working with Goose
---
diff --git a/documentation/docs/guides/updating-goose.md b/documentation/docs/guides/updating-goose.md
index 2dc9c033..d7447920 100644
--- a/documentation/docs/guides/updating-goose.md
+++ b/documentation/docs/guides/updating-goose.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 5
+sidebar_position: 20
title: Updating Goose
sidebar_label: Updating Goose
---
diff --git a/documentation/docs/guides/using-goosehints.md b/documentation/docs/guides/using-goosehints.md
index aa94f120..abb11e22 100644
--- a/documentation/docs/guides/using-goosehints.md
+++ b/documentation/docs/guides/using-goosehints.md
@@ -1,6 +1,6 @@
---
title: Providing Hints to Goose
-sidebar_position: 7
+sidebar_position: 40
sidebar_label: Using Goosehints
---
diff --git a/documentation/docs/guides/using-gooseignore.md b/documentation/docs/guides/using-gooseignore.md
index 3d5095f1..bf9f476b 100644
--- a/documentation/docs/guides/using-gooseignore.md
+++ b/documentation/docs/guides/using-gooseignore.md
@@ -1,7 +1,7 @@
---
title: Prevent Goose from Accessing Files
sidebar_label: Using Gooseignore
-sidebar_position: 14
+sidebar_position: 80
---
diff --git a/documentation/docs/tutorials/plan-feature-devcontainer-setup.md b/documentation/docs/tutorials/plan-feature-devcontainer-setup.md
index c3f59dbf..89c1a246 100644
--- a/documentation/docs/tutorials/plan-feature-devcontainer-setup.md
+++ b/documentation/docs/tutorials/plan-feature-devcontainer-setup.md
@@ -452,6 +452,6 @@ The key is treating Goose as a planning partner, not just a code generator. Give
- Try this approach with your own complex setup challenges
- Experiment with different types of planning prompts
- Share your planning successes with the [Goose community](https://discord.gg/block-opensource)
-- Explore how planning integrates with [Lead/Worker mode](/docs/tutorials/lead-worker) or [Subagents](/docs/experimental/subagents) for even more sophisticated workflows
+- Explore how planning integrates with [Lead/Worker mode](/docs/tutorials/lead-worker) or [Subagents](/docs/guides/subagents) for even more sophisticated workflows
Remember, the goal is to get the right approach, in the right order, with the right safeguards. That's what makes the difference between a quick fix and a robust, maintainable solution.
\ No newline at end of file
diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts
index c8629c23..2a59272b 100644
--- a/documentation/docusaurus.config.ts
+++ b/documentation/docusaurus.config.ts
@@ -302,6 +302,10 @@ const config: Config = {
{
from: '/docs/guides/isolated-development-environments',
to: '/docs/tutorials/isolated-development-environments'
+ },
+ {
+ from: '/docs/experimental/subagents',
+ to: '/docs/guides/subagents'
}
],
},