docs: reorganize (#9310)

2026-05-18 13:38:14 -05:00
parent badb97a01e
commit bc9c1fc11a
54 changed files with 458 additions and 101 deletions
@@ -50,11 +50,11 @@ Beyond projects, global .goosehints files (`~/.config/goose/.goosehints`) apply

 ## 4. Choose the Right Mode for Your Workflow

-goose offers [different modes](/docs/guides/goose-permissions) that determine how much autonomy it has when modifying files, using extensions, and performing automated actions. 
+goose offers [different modes](/docs/guides/managing-tools/goose-permissions) that determine how much autonomy it has when modifying files, using extensions, and performing automated actions. 

 * ⚡️ **Auto Mode (Default):** goose can modify, create, and delete files, as well as use extensions, without requiring approval. Best for users who want seamless automation.

-* ✅ **Approve Mode:** goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/goose-permissions#permission-modes) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.
+* ✅ **Approve Mode:** goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/managing-tools/goose-permissions#permission-modes) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.

 * 💬 **Chat Mode:** goose operates in chat-only mode, without modifying files or using extensions. Ideal for users who want AI assistance without automation.

@@ -65,7 +65,7 @@ This is especially useful for tasks that span multiple files, involve side effec

 ### 3. Choose the Right Mode for the Job

-While letting your AI agent take the lead is fun, not every moment calls for full autonomy. Sometimes, you need to pause, review, or plan before any code changes. Goose offers several [modes](https://goose-docs.ai/docs/guides/goose-permissions) that help you stay in control without breaking your momentum. Here's how to use them intentionally during your sessions:
+While letting your AI agent take the lead is fun, not every moment calls for full autonomy. Sometimes, you need to pause, review, or plan before any code changes. Goose offers several [modes](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions) that help you stay in control without breaking your momentum. Here's how to use them intentionally during your sessions:

 * **Chat Mode**  
  Goose will only respond with text so that you can brainstorm together.
@@ -8,7 +8,7 @@ authors:
 ---

 :::danger Outdated
-Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
+Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/context-engineering/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
 :::

 ![blog cover](multi-model-ai-agent.png)
@@ -84,7 +84,7 @@ export GOOSE_MODEL="claude-4-sonnet"

 From there, Goose takes care of the hand off, the fallback, and the recovery. You just... keep vibing.

-If you're curious how it all works under the hood, see the [planning guide](/docs/guides/creating-plans).
+If you're curious how it all works under the hood, see the [planning guide](/docs/guides/context-engineering/creating-plans).

 ---

@@ -36,7 +36,7 @@ I decided to create a digital resource that teaches foundational concepts like A

 ## Meet the Subagents

-[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.
+[Subagents](/docs/guides/context-engineering/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:

@@ -56,7 +56,7 @@ As of version 1.10.0, subagents are no longer experimental and don't require ena

 ## 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/guides/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/context-engineering/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:
  
@@ -171,7 +171,7 @@ What will you build with subagents?

 [Download Goose](/)

-[Learn about subagents](/docs/guides/subagents)
+[Learn about subagents](/docs/guides/context-engineering/subagents)

 <head>
  <meta property="og:title" content="Orchestrating 6 Subagents to Build a Collaborative API Playground for Kids" />
@@ -406,7 +406,7 @@ Angie's Diner shows exceptional performance with premium order values and strong
 </details>


-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?
+What a fun experiment! This gave me a better understanding of how agent-to-agent and [subagent](/docs/guides/context-engineering/subagents) workflows may work behind the scenes. Makes you wonder, what else could happen when AIs start talking to each other without us?

 ---

@@ -7,7 +7,7 @@ authors:
 ---

 :::danger Outdated
-Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
+Lead/Worker mode has been removed from goose. It has been replaced by [Planning Mode](/docs/guides/context-engineering/creating-plans), which uses a dedicated planner model with the `/plan` command. See the [multi-model guide](/docs/guides/multi-model/) for current workflows.
 :::

 ![blog cover](header-image.png)
@@ -42,7 +42,7 @@ This is where it gets really cool - you can use Claude for reasoning and OpenAI
 - 🏃‍♂️ Handle Long Dev Sessions
 Perfect for those marathon coding sessions where you need sustained performance without breaking the bank.

-## [Setting It Up](/docs/guides/creating-plans)
+## [Setting It Up](/docs/guides/context-engineering/creating-plans)

 Getting started with the Lead/Worker model is surprisingly straightforward. In the Goose desktop app, you just need to:

@@ -104,7 +104,7 @@ The best part? The models made smart decisions we hadn't even thought of, like a

 ## Ready to Try Multi-Model Workflows?

-Lead/Worker mode has been removed, but goose now supports [Planning Mode](/docs/guides/creating-plans) for multi-model workflows. Whether you're working on documentation, building features, or tackling complex refactoring, pairing a strong planner model with a fast execution model can be a game changer.
+Lead/Worker mode has been removed, but goose now supports [Planning Mode](/docs/guides/context-engineering/creating-plans) for multi-model workflows. Whether you're working on documentation, building features, or tackling complex refactoring, pairing a strong planner model with a fast execution model can be a game changer.

 Want to see it in action? Check out the full stream where we built this feature live:

@@ -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/guides/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/context-engineering/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.

@@ -36,7 +36,7 @@ Think lone developer grinding through the ticket.

 ## The Subagent Setup: Orchestrator With a Crew

-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.
+With [subagents](/docs/guides/context-engineering/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:

@@ -81,7 +81,7 @@ The [Memory extension](https://goose-docs.ai/docs/mcp/memory-mcp) stores importa

 **5. Subagents**

-[Subagents](https://goose-docs.ai/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.
+[Subagents](https://goose-docs.ai/docs/guides/context-engineering/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**

@@ -89,7 +89,7 @@ Keep individual sessions focused on specific tasks. When you complete a task or

 **7. Planner model + focused execution**

-Use a dedicated [planner model](/docs/guides/creating-plans) for complex reasoning and keep your default model focused on execution. This gives you control over cost and quality while keeping model behavior explicit and predictable.
+Use a dedicated [planner model](/docs/guides/context-engineering/creating-plans) for complex reasoning and keep your default model focused on execution. This gives you control over cost and quality while keeping model behavior explicit and predictable.

 ---

@@ -55,7 +55,7 @@ Browse and select from a wide range of options, including:
 - **Specialized models** optimized for different use cases

 :::tip Protip 
- Want the best of both worlds? Use a dedicated [planner model](/docs/guides/creating-plans) for complex strategy and a faster default model for execution. Pair this with `/plan` to get strong reasoning only when you need it—saving both time and credits.
+ Want the best of both worlds? Use a dedicated [planner model](/docs/guides/context-engineering/creating-plans) for complex strategy and a faster default model for execution. Pair this with `/plan` to get strong reasoning only when you need it—saving both time and credits.
 :::

 ---
@@ -7,7 +7,7 @@ authors:

 ![Subagents vs Subrecipes](subrecipes-vs-subagents.png)

-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.
+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/context-engineering/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.

@@ -30,13 +30,13 @@ Rather than picking one philosophy, [goose](https://github.com/aaif-goose/goose)
 ### For The Architect
 **`/plan` Mode**

-When you enter [plan mode](/docs/guides/creating-plans) in the goose CLI, goose shifts into an interactive dialogue. Instead of immediately executing, it asks clarifying questions to understand your project deeply. It might ask about your tech stack preferences, authentication requirements, deployment targets, or how you want to handle error cases. This back and forth continues until goose has enough context to generate a comprehensive, actionable plan.
+When you enter [plan mode](/docs/guides/context-engineering/creating-plans) in the goose CLI, goose shifts into an interactive dialogue. Instead of immediately executing, it asks clarifying questions to understand your project deeply. It might ask about your tech stack preferences, authentication requirements, deployment targets, or how you want to handle error cases. This back and forth continues until goose has enough context to generate a comprehensive, actionable plan.

 Plan mode uses a separate planner configuration that you can customize. By setting **`GOOSE_PLANNER_PROVIDER`** and **`GOOSE_PLANNER_MODEL`** [environment variables](/docs/guides/environment-variables), you can use one model for strategic planning and a different model for execution. When you're satisfied with the plan, goose asks if you want to clear the message history and act on it, giving you a clear checkpoint before any code changes happen.

 I used this approach recently when converting a static Vite/React project to Next.js. I understood the scope clearly since it's a common migration pattern, so I asked goose to make a comprehensive plan before starting any work. It produced an 11 phase migration plan with specific checkboxes for each step, covering everything from dependency updates to routing changes to component boundaries. Once I approved, I said "yes start" and goose executed methodically, committing after each phase.

-[Learn more about creating plans →](/docs/guides/creating-plans)
+[Learn more about creating plans →](/docs/guides/context-engineering/creating-plans)

 ### For The Director
 **Instruction Files**
@@ -69,7 +69,7 @@ Here's a real Town Wall snippet from a session where parallel researchers conver
 * **[10:14] researcher-endpoints** - 💡 Found: native endpoint already exists with minimal deps. Alternative path viable.   
 * **[10:15] researcher-source** - ✅ Done. Confirmed: native path requires zero new dependencies. Recommending pivot.

-Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/using-skills), [subagents](/docs/guides/subagents), [beads](https://github.com/steveyegge/beads), and a [gtwall](https://github.com/aaif-goose/goosetown/blob/main/gtwall).
+Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/using-skills), [subagents](/docs/guides/context-engineering/subagents), [beads](https://github.com/steveyegge/beads), and a [gtwall](https://github.com/aaif-goose/goosetown/blob/main/gtwall).

 ### Skills

@@ -77,7 +77,7 @@ Goosetown operates on 4 components: [skills](/docs/guides/context-engineering/us

 ### Subagents

-Instead of doing everything in one long conversation that eventually hits a "context cliff," Goosetown uses [subagents](/docs/guides/subagents), ephemeral agent instances. These are triggered by the [summon extension](/docs/mcp/summon-mcp), using `delegate()` to hand off work to a fresh agent instance. They do the work in their own clean context and return a summary, keeping your main session fast and focused.
+Instead of doing everything in one long conversation that eventually hits a "context cliff," Goosetown uses [subagents](/docs/guides/context-engineering/subagents), ephemeral agent instances. These are triggered by the [summon extension](/docs/mcp/summon-mcp), using `delegate()` to hand off work to a fresh agent instance. They do the work in their own clean context and return a summary, keeping your main session fast and focused.

 ### Beads

@@ -7,6 +7,8 @@ authors:

 Quick highlight: [Sentient AGI](https://x.com/SentientAGI/status/2046967422004154739) recently shared with us some results with a challenge called "Grounded Reasoning" where teams tackled the Databricks OfficeQA benchmark using the MiniMax (2.5) open model.

+<!-- truncate -->
+
 Highlights from the linked article:

 > * Using goose with [MiniMax M2.5](https://www.minimax.io/) on the [OfficeQA benchmark from Databricks](https://www.databricks.com/blog/officeqa), we're seeing results approaching frontier model performance for **1/30th of the cost**.
@@ -16,7 +16,7 @@ That's what orchestration gives you. Instead of feeding goose one task at a time

 ## What is orchestration?

-If you've used [subagents](/docs/guides/subagents) before, you already know how to delegate work to independent AI instances. Orchestration is the layer above that — the part that decides _who_ does _what_ and _when_. Instead of one goose session doing everything sequentially, orchestration lets you:
+If you've used [subagents](/docs/guides/context-engineering/subagents) before, you already know how to delegate work to independent AI instances. Orchestration is the layer above that — the part that decides _who_ does _what_ and _when_. Instead of one goose session doing everything sequentially, orchestration lets you:

 - **Decompose** a complex task into independent subtasks
 - **Delegate** each subtask to a separate agent (subagent, ACP provider, or another goose instance)
@@ -43,7 +43,7 @@ Orchestration doesn't replace subagents or subrecipes — it builds on them:

 | Layer | What it does |
 |-------|-------------|
-| [Subagents](/docs/guides/subagents) (delegate) | Spin up independent sub-tasks |
+| [Subagents](/docs/guides/context-engineering/subagents) (delegate) | Spin up independent sub-tasks |
 | Async delegates | Run subagents in the background, collect results later |
 | [ACP providers](/docs/guides/acp-providers) | Bring in external agents (Claude Code, Codex, Amp) |
 | **Orchestration** | Coordinate all of the above into structured workflows |