Hide non-primary agents from the Tab switcher

README.md

@@ -78,7 +78,7 @@ If this project helps your workflow, please consider supporting ongoing maintena
 
 ## Agent roles (Tab menu)
 
-This setup keeps `build` as the default agent for quick direct work, while adding `orchestrator` and focused specialists for manual selection via `Tab`:
+This setup keeps `build` as the default agent for quick direct work, exposes only `build`, `plan`, and `orchestrator` in the `Tab` switcher, and keeps focused specialists available as hidden secondary subagents:
 
 - `orchestrator` (primary): execution lead for complex tasks, with explicit delegation and completion gates.
 - `explore` (subagent): read-only internal codebase scout.
@@ -94,7 +94,9 @@ This setup keeps `build` as the default agent for quick direct work, while addin
 Default selection note:
 
 - `build` remains the configured `default_agent` in `opencode.json` for speed.
+- `plan` remains the built-in planning primary in OpenCode.
 - choose `orchestrator` when you want end-to-end multi-step execution with delegation and completion gates.
+- specialist subagents stay hidden from `Tab` and are meant for delegation or explicit `@agent` invocation.
 
 Agent files live in `agent/*.md` and install globally to `~/.config/opencode/agent/`.
 Agent source-of-truth specs live in `agent/specs/*.json` and generate markdown via `scripts/build_agents.py`.

agent/ambiguity-analyst.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: cheap
   default_category: deep

agent/explore.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: free
   default_category: quick

agent/librarian.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: cheap
   default_category: balanced

agent/oracle.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: expensive
   default_category: critical

agent/plan-critic.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: expensive
   default_category: critical

agent/release-scribe.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: cheap
   default_category: quick

agent/reviewer.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: expensive
   default_category: critical

agent/specs/ambiguity-analyst.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/explore.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/librarian.json

@@ -38,6 +38,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/oracle.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/plan-critic.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/release-scribe.json

@@ -38,6 +38,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/reviewer.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/strategic-planner.json

@@ -39,6 +39,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/specs/verifier.json

@@ -38,6 +38,7 @@
       "task",
       "todowrite",
       "todoread"
-    ]
+    ],
+    "hidden": true
   }
 }

agent/strategic-planner.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: cheap
   default_category: deep

agent/verifier.md

@@ -14,6 +14,7 @@ tools:
   task: false
   todowrite: false
   todoread: false
+hidden: true
 routing:
   cost_tier: cheap
   default_category: quick

docs/agents-playbook.md

@@ -45,9 +45,11 @@ Think of it as:
 In OpenCode prompt:
 
 1. Press `Tab`
-2. Pick agent (`build`, `orchestrator`, etc.)
+2. Pick agent (`build`, `plan`, or `orchestrator`)
 3. Run your prompt normally
 
+Our custom specialist subagents are intentionally marked hidden, so they stay out of the `Tab` switcher and are used through delegation or explicit `@agent` mention instead.
+
 You can verify available agents with:
 
 ```bash

opencode.json

@@ -1,6 +1,25 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "default_agent": "build",
+  "agent": {
+    "executor": {
+      "hidden": true
+    },
+    "planner": {
+      "hidden": true
+    },
+    "supervisor": {
+      "hidden": true
+    },
+    "oracle": {
+      "mode": "subagent",
+      "hidden": true
+    },
+    "reviewer": {
+      "mode": "subagent",
+      "hidden": true
+    }
+  },
   "autoupdate": true,
   "share": "manual",
   "permission": {

scripts/agent_doctor.py

@@ -77,20 +77,42 @@
         "Use `reviewer` for final quality/safety pass",
         "Anti-loop guard",
     ],
-    "explore.md": ["mode: subagent", "bash: false", "write: false", "edit: false"],
+    "explore.md": [
+        "mode: subagent",
+        "hidden: true",
+        "bash: false",
+        "write: false",
+        "edit: false",
+    ],
     "librarian.md": [
         "mode: subagent",
+        "hidden: true",
         "bash: false",
         "write: false",
         "edit: false",
     ],
-    "oracle.md": ["mode: subagent", "write: false", "edit: false"],
-    "verifier.md": ["mode: subagent", "write: false", "edit: false"],
-    "reviewer.md": ["mode: subagent", "write: false", "edit: false"],
-    "release-scribe.md": ["mode: subagent", "write: false", "edit: false"],
-    "strategic-planner.md": ["mode: subagent", "write: false", "edit: false"],
-    "ambiguity-analyst.md": ["mode: subagent", "write: false", "edit: false"],
-    "plan-critic.md": ["mode: subagent", "write: false", "edit: false"],
+    "oracle.md": ["mode: subagent", "hidden: true", "write: false", "edit: false"],
+    "verifier.md": ["mode: subagent", "hidden: true", "write: false", "edit: false"],
+    "reviewer.md": ["mode: subagent", "hidden: true", "write: false", "edit: false"],
+    "release-scribe.md": [
+        "mode: subagent",
+        "hidden: true",
+        "write: false",
+        "edit: false",
+    ],
+    "strategic-planner.md": [
+        "mode: subagent",
+        "hidden: true",
+        "write: false",
+        "edit: false",
+    ],
+    "ambiguity-analyst.md": [
+        "mode: subagent",
+        "hidden: true",
+        "write: false",
+        "edit: false",
+    ],
+    "plan-critic.md": ["mode: subagent", "hidden: true", "write: false", "edit: false"],
 }
 
 REQUIRED_ORCHESTRATION_MARKERS: list[str] = [

scripts/build_agents.py

@@ -54,6 +54,11 @@ def _validate_metadata(name: str, metadata: Any) -> dict[str, Any]:
         if not isinstance(value, str) or not value.strip():
             raise ValueError(f"{name}: metadata.{key} must be a non-empty string")
         result[key] = value.strip()
+    hidden = metadata.get("hidden")
+    if hidden is not None:
+        if not isinstance(hidden, bool):
+            raise ValueError(f"{name}: metadata.hidden must be boolean")
+        result["hidden"] = hidden
     for key in ("triggers", "avoid_when", "denied_tools"):
         value = metadata.get(key)
         if value is None:
@@ -138,6 +143,8 @@ def _render_agent(spec: dict[str, Any], profile: str) -> tuple[str, str]:
     for tool_name, enabled in tools.items():
         header_lines.append(f"  {tool_name}: {'true' if enabled else 'false'}")
     if metadata:
+        if isinstance(metadata.get("hidden"), bool):
+            header_lines.append(f"hidden: {'true' if metadata['hidden'] else 'false'}")
         header_lines.append("routing:")
         for key in ("cost_tier", "default_category", "fallback_policy"):
             value = metadata.get(key)