feat(opencode): restore build and plan modes

FORK_CHANGELOG.md

@@ -13,7 +13,8 @@ When a change is suspicious, unproven, not clearly fork-specific, or not clearly
 - `/auth` is the credentials flow, not a product mode switch.
 - `/models` chooses the LLM config passed to Agency Swarm, not a product mode switch.
 - Upstream OpenCode provider/model state may still exist internally for auth and LLM choice, but it must not pull the user out of Run mode by accident.
-- Agent Builder and Plan still exist conceptually, but they are currently hidden or disabled in Run mode and continue to rely on the native OpenCode backbone plus fork-specific instructions.
+- `/mode` is the product mode switch. It exposes Build, Plan, and Run without adding `/build` or `/plan` commands.
+- Build and Plan rely on native OpenCode behavior plus fork-specific Agent Swarm instructions. Run is the Agency Swarm server-backed mode.
 - Bug-like changes are not product features. Compare them against upstream, find the root cause, reduce divergence, and avoid fork-only workarounds.
 - Install, launcher, and package behavior count as user experience and belong in this file when they are intentional fork behavior.
 - `USER_FLOWS.md` is the single source of truth for full QA before every release; implementation-level file paths and symbols stay in this changelog.
@@ -27,7 +28,7 @@ Use this index with `USER_FLOWS.md` when a QA row needs the owning fork implemen
 - Downstream product profile: `packages/opencode/src/agency-swarm/product.ts`, `packages/opencode/src/agency-swarm/npx.ts`, `packages/opencode/src/cli/cmd/tui/util/env-file.ts`, `packages/opencode/src/agency-swarm/server-launcher.ts`, `packages/opencode/src/installation/distribution.ts`, `packages/opencode/script/build.ts`.
 - Local project setup, starter creation, and onboarding auto-launch: `packages/opencode/src/agency-swarm/npx.ts`, `packages/opencode/src/cli/cmd/tui/thread.ts`, `packages/opencode/src/cli/cmd/tui/app.tsx`, `packages/opencode/src/cli/cmd/tui/routes/home.tsx`.
 - Agency session resume and bridge recovery: `packages/opencode/src/agency-swarm/run-session.ts`, `packages/opencode/src/agency-swarm/npx.ts`, `packages/opencode/src/session/agency-swarm.ts`, `packages/opencode/src/cli/cmd/tui/session-error.ts`, `packages/opencode/src/cli/cmd/tui/context/agency-swarm-connection.tsx`.
-- Connection, auth, and provider dialogs: `packages/opencode/src/cli/cmd/tui/app.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-provider.tsx`, `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx`, `packages/opencode/src/cli/cmd/tui/session-error.ts`.
+- Connection, auth, mode, and provider dialogs: `packages/opencode/src/cli/cmd/tui/app.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-mode.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-provider.tsx`, `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx`, `packages/opencode/src/cli/cmd/tui/session-error.ts`.
 - Run-mode routing, add-ons, models, and attachments: `packages/opencode/src/agency-swarm/adapter.ts`, `packages/opencode/src/session/agency-swarm.ts`, `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-model.tsx`, `packages/opencode/src/cli/cmd/tui/context/local.tsx`, `packages/opencode/src/cli/cmd/tui/util/agency-target.ts`.
 - Run-mode local models: `packages/opencode/src/agency-swarm/ollama.ts`, `packages/opencode/src/agency-swarm/litellm-provider.ts`, `packages/opencode/src/agency-swarm/client-config.ts`, `packages/opencode/src/provider/provider.ts`, `packages/opencode/src/cli/cmd/tui/component/download-ollama-model.tsx`, `packages/opencode/src/cli/cmd/tui/component/dialog-model.tsx`, `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx`, `packages/opencode/src/cli/cmd/tui/session-error.ts`.
 - Builder and Plan preservation: `packages/opencode/src/session/agent-builder.ts`, `packages/opencode/src/session/agent-planner.ts`, `packages/opencode/src/session/prompt/agent-builder.txt`, `packages/opencode/src/session/prompt/agent-planner.txt`.
@@ -228,15 +229,16 @@ Use this index with `USER_FLOWS.md` when a QA row needs the owning fork implemen
   - Implementation: `agentPlannerInstructions` in `packages/opencode/src/session/agent-planner.ts` with `packages/opencode/src/session/prompt/agent-planner.txt`.
   - Added by: `7643fcde`
 
-- **Builder and Plan switching are hidden in Run mode**
-  - Intent: keep Run mode focused on connected Agency Swarm execution while Builder and Plan stay conceptually preserved but currently hidden.
-  - Behavior: in Run mode, the picker becomes a run-target picker instead of a Builder or Plan mode switcher.
-  - Implementation: `frameworkMode` and `cycleAgencyRunTarget` in `packages/opencode/src/cli/cmd/tui/app.tsx` plus `DialogAgent` in `packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx`.
+- **`/mode` exposes Build, Plan, and Run**
+  - Intent: let users move between native Build, native Plan, and server-backed Run inside one project without adding parallel Build or Plan behavior.
+  - Behavior: `/mode` switches product mode. Build selects the native `build` agent, Plan selects the native `plan` agent, and Run keeps prompts server-backed through Agency Swarm. `/build` and `/plan` are not slash commands.
+  - Behavior: leaving Run stops prompt routing through the Agency Swarm backend; returning to Run reconnects to or keeps using the configured Agency Swarm server.
+  - Implementation: product mode state in `packages/opencode/src/cli/cmd/tui/context/local.tsx`, `DialogMode` in `packages/opencode/src/cli/cmd/tui/component/dialog-mode.tsx`, and framework-mode gates in `packages/opencode/src/cli/cmd/tui/session-error.ts`.
   - Added by: `d6b9ed38`
 
-- **Tab switches agents in Run mode**
-  - Intent: speed up agent switching during run sessions.
-  - Behavior: pressing Tab in Run mode cycles through available agents.
+- **Tab switches native agents outside Run and swarm agents in Run**
+  - Intent: preserve upstream native agent cycling while keeping fast target switching during run sessions.
+  - Behavior: pressing Tab in Run mode cycles through available Agency Swarm targets. In Build and Plan, Tab keeps the native OpenCode local-agent cycle behavior.
   - Implementation: `cycleAgencyRunTarget` in `packages/opencode/src/cli/cmd/tui/app.tsx` and `cycleAgencyTargetSelection` in `packages/opencode/src/cli/cmd/tui/util/agency-target.ts`.
   - Added by: `d6b9ed38`
 
@@ -253,8 +255,8 @@ Use this index with `USER_FLOWS.md` when a QA row needs the owning fork implemen
   - Added by: `PR #51`
 
 - **Run mode hides native OpenCode menus and limits model selection**
-  - Intent: keep Run mode on the connected Agency Swarm surface while preserving native OpenCode menus for Builder and Plan when those modes are available again.
-  - Behavior: Run mode hides native `/editor`, `/variants`, `/init`, and `/review`; model-selection and provider-auth surfaces remain as support flows for LLM choice and credentials, and are limited to intended Agent Swarm / Agency Swarm providers.
+  - Intent: keep Run mode on the connected Agency Swarm surface while preserving native OpenCode menus for Build and Plan.
+  - Behavior: Run mode hides native `/editor`, `/variants`, `/init`, and `/review`; those commands return in Build and Plan. Model-selection and provider-auth surfaces remain as Run support flows for LLM choice and credentials, and are limited to intended Agent Swarm / Agency Swarm providers.
   - Implementation: framework-mode command gating in `packages/opencode/src/cli/cmd/tui/app.tsx`, `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx`, `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx`, and `packages/opencode/src/cli/cmd/tui/component/dialog-model.tsx`.
   - Added by: `PR #81`
 
@@ -329,10 +331,10 @@ Use this index with `USER_FLOWS.md` when a QA row needs the owning fork implemen
 
 ## Web/App Surface
 
-- **README mode overview explains Builder, Plan, and Run**
+- **README mode overview explains Build, Plan, and Run**
   - Intent: document the fork's mode model clearly at the top level.
-  - Behavior: the README explains Agent Builder, Plan, and Run, with Run as the connected Agency Swarm path and Builder or Plan preserved conceptually even if hidden in current Run mode.
-  - Implementation: the `### Agents` section in `README.md`.
+  - Behavior: the README explains `/mode`, Build, Plan, and Run, with Run as the connected Agency Swarm path and Build or Plan as native OpenCode modes under the Agent Swarm umbrella.
+  - Implementation: the `Main TUI Flows` section in `README.md`.
   - Added by: `1df2f455`
 
 - **Canonical flow map and QA source of truth**

README.md

@@ -3,7 +3,7 @@
 Agent Swarm CLI is a terminal app for running and testing Agency Swarm projects.
 It is built on the OpenCode codebase, with Agent Swarm-specific packaging, branding, auth, and TUI flows.
 
-The main user path is **Run mode**: start the TUI from an Agency Swarm project, authenticate a model provider, connect to the local Agency Swarm server, and send prompts to your agency.
+The main user path is **Run mode**: start the TUI from an Agency Swarm project, authenticate a model provider, connect to the local Agency Swarm server, and send prompts to your swarm.
 
 ## Install
 
@@ -36,13 +36,15 @@ On startup, the CLI can detect the project, prepare the project Python environme
 
 ## Main TUI Flows
 
+- `/mode` switches between Build, Plan, and Run.
+- Build uses native OpenCode build behavior with Agent Swarm guidance.
+- Plan is native OpenCode Plan mode for preparing work before Build.
+- Run connects to or starts an Agency Swarm FastAPI server and sends prompts to the active swarm.
 - `/auth` manages OpenAI and Anthropic credentials used by Agency Swarm runs.
 - `/connect` chooses a local or external Agency Swarm server.
-- `/agents` switches the active swarm or agent from live Agency Swarm metadata.
+- `/agents` switches native agents in Build and Plan. In Run, it switches the active swarm or agent from live Agency Swarm metadata.
 - `/models` is limited in Run mode to providers that the Agency Swarm path supports.
 
-Agent Builder and Plan are preserved from the OpenCode backbone, but they are currently hidden from the normal Run mode surface.
-
 ## Sharing
 
 `/share` is still the upstream OpenCode share flow and currently posts to `https://opncd.ai`.

USER_FLOWS.md

@@ -12,7 +12,7 @@ Keep implementation-level file paths and symbol details in `FORK_CHANGELOG.md`;
 - Launcher and install behavior for `npx @vrsen/agentswarm`, installed `agentswarm`, the direct fork binary, and `agentswarm pr`.
 - Downstream package builds that reuse this TUI foundation through generic product profile inputs.
 - Local Agency Swarm project detection, starter creation, Python environment repair, uv setup, bridge startup, resume recovery, and external Agency server connection.
-- TUI Run mode routing, `/auth`, `/connect`, run-target selection, attachments, history, handoffs, dead-server recovery, and hidden upstream-native commands.
+- TUI `/mode`, native Build and Plan exposure, Run mode routing, `/auth`, `/connect`, run-target selection, attachments, history, handoffs, dead-server recovery, and hidden upstream-native commands in Run.
 - Fork branding, tips, theme, config precedence, upgrade channel limits, share carry-forward, and developer/debug `agentswarm agency` commands.
 - Trust-safe telemetry metrics, event-list docs, derived dashboard metrics, opt-out behavior, and privacy proof for fork-owned Agent Swarm flows.
 - Out of scope: Python-side `agency.tui()` invocation before control reaches this repo.
@@ -182,6 +182,7 @@ For each failure scenario, capture the visible user result and cite the matching
 - **Happy-path proof:** In-flight Agency runs cancel through the bridge.
 - **Happy-path proof:** Codex OAuth is stripped from non-OpenAI LiteLLM agency runs.
 - **Happy-path proof:** Run mode hides Builder, Plan, `/editor`, `/variants`, `/init`, `/review`, and other disabled upstream-native surfaces.
+- **Happy-path proof:** `/mode` remains available in Run so the user can switch to Build or Plan without leaving the project.
 - **Happy-path proof:** `/models` and `/auth` are limited to Agency-supported providers.
 - **Happy-path proof:** Upstream provider/model state used for auth or LLM choice does not pull the user out of Run mode by accident.
 - **Happy-path proof:** `agency-swarm/default` stays active over stale stored model state until the user explicitly chooses another model.
@@ -193,13 +194,20 @@ For each failure scenario, capture the visible user result and cite the matching
 - **Failure scenarios to test:** Non-OpenAI LiteLLM agency runs do not receive Codex OAuth credentials while OpenAI-based LiteLLM runs still keep them.
 - **Failure scenarios to test:** Missing or unreachable Ollama fails visibly without switching out of Run mode.
 
-#### Builder and Plan instruction preservation
-
-- **Trigger:** Builder or Plan flows are exercised outside Run-mode hiding.
-- **Happy-path proof:** Builder still uses fork-specific Agency Swarm repo instructions.
-- **Happy-path proof:** Plan still writes Agency Swarm handoff plans instead of upstream OpenCode defaults.
-- **Failure scenarios to test:** Run mode keeps Builder and Plan switching hidden.
-- **Failure scenarios to test:** Any re-enabled Builder or Plan path keeps the fork-specific prompt instructions.
+#### `/mode`, Build, and Plan
+
+- **Trigger:** The user runs `/mode` and chooses Build, Plan, or Run.
+- **Happy-path proof:** `/mode` is the product mode switch; `/build` and `/plan` slash commands do not exist.
+- **Happy-path proof:** Build uses native OpenCode build behavior with fork-specific Agent Swarm repo instructions and works without an Agency Swarm server.
+- **Happy-path proof:** Plan uses native OpenCode Plan mode with fork-specific Agent Swarm handoff instructions and works without an Agency Swarm server.
+- **Happy-path proof:** Build and Plan prompts use native local agent state, not the Agency Swarm backend target state.
+- **Happy-path proof:** Native OpenCode commands hidden in Run return in Build and Plan.
+- **Happy-path proof:** `/agents` uses the native OpenCode agent picker in Build and Plan.
+- **Happy-path proof:** Tab cycles native local agents in Build and Plan.
+- **Happy-path proof:** Switching from Run to Build or Plan stops treating prompts as server-backed Run prompts.
+- **Happy-path proof:** Switching back to Run in the same project reconnects to or keeps using the Agency Swarm server and returns `/agents` to the swarm/agent picker.
+- **Failure scenarios to test:** Server failure in Run still lets the user switch to Build or Plan in the same project, make a plan or build a fix, then return to Run.
+- **Failure scenarios to test:** Run mode stays server-backed even when visible provider/model state is native.
 
 #### Attachments, history, and handoff
 

e2e/agent-swarm-tui/QA_COVERAGE.md

@@ -7,6 +7,8 @@
 - `USER_FLOWS.md` Detected Local Project: launcher mode shows the detected-project choice before `.venv` work begins.
 - `USER_FLOWS.md` Startup `/auth` and In-TUI `/connect`: `/auth` and `/connect` stay separate in the real terminal UI.
 - `USER_FLOWS.md` Run Mode: native `/editor`, `/variants`, `/init`, and `/review` slash commands stay hidden.
+- `USER_FLOWS.md` `/mode`, Build, and Plan: `/mode` appears as the product switch, `/build` and `/plan` do not exist, Build and Plan restore native `/review` and `/init`, and switching back to Run hides native commands again.
+- `USER_FLOWS.md` `/mode`, Build, and Plan: Tab cycles native local agents outside Run and Agency Swarm targets in Run.
 - `USER_FLOWS.md` Run Mode: `/agents` uses Swarm and agent wording, live agency labels, swarm-row routing, and specific-agent routing against an Agency Swarm TUI-demo-shaped swarm.
 - `USER_FLOWS.md` Run Mode: prompt submit reaches a local Agency Swarm protocol server with the configured agent.
 - `USER_FLOWS.md` Run Mode: simulated visible OpenAI model state does not pull prompts, slash-command `/new`, run-session local-project marking, `/connect`, or runtime auth recovery out of Agency Swarm routing.