@hiai-gg/hiai-opencode 0.1.5 → 0.1.7

package/src/features/builtin-commands/commands.ts

@@ -9,6 +9,7 @@ import { START_WORK_TEMPLATE } from "./templates/start-work"
 import { HANDOFF_TEMPLATE } from "./templates/handoff"
 import { REMOVE_AI_SLOPS_TEMPLATE } from "./templates/remove-ai-slops"
 import { MCP_STATUS_TEMPLATE } from "./templates/mcp-status"
+import { DOCTOR_TEMPLATE } from "./templates/doctor"
 
 interface LoadBuiltinCommandsOptions {
   useRegisteredAgents?: boolean
@@ -126,6 +127,12 @@ $ARGUMENTS
       description: "(builtin) Show hiai-opencode MCP server status, missing keys, and local runtime availability",
       template: `<command-instruction>
 ${MCP_STATUS_TEMPLATE}
+</command-instruction>`,
+    },
+    doctor: {
+      description: "(builtin) Run hiai-opencode install/runtime diagnostics and explain setup issues",
+      template: `<command-instruction>
+${DOCTOR_TEMPLATE}
 </command-instruction>`,
     },
   }

package/src/features/builtin-commands/templates/doctor.ts

@@ -0,0 +1,43 @@
+export const DOCTOR_TEMPLATE = `# Hiai OpenCode Doctor Command
+
+## Purpose
+
+Use /doctor to run the hiai-opencode install/runtime diagnostic and report actionable setup issues.
+
+## Execute
+
+Run:
+
+\`\`\`bash
+hiai-opencode doctor
+\`\`\`
+
+If the binary is not on PATH, try the package-local fallback:
+
+\`\`\`bash
+node ./node_modules/@hiai-gg/hiai-opencode/assets/cli/hiai-opencode.mjs doctor
+\`\`\`
+
+## Report
+
+Summarize:
+
+- config path
+- enabled and disabled MCP servers
+- missing env vars by name only
+- static \`.mcp.json\` freshness and whether it is managed by hiai-opencode
+- OpenCode Connect visibility for configured model providers
+- OpenCode plugin registration sanity (including \`plugin: ["list"]\` misconfiguration warning)
+- skill materialization status from skill registry
+- agent count and naming summary
+- LSP runtime availability
+- MemPalace python source and selected interpreter (env/config/auto)
+- MCP tool probes (real connect + tools/list) for stdio and basic endpoint probes for remote MCP
+
+Rules:
+
+- Do not print API key values.
+- Do not ask for model provider env vars such as OPENROUTER_API_KEY or OPENAI_API_KEY; normal model auth belongs to OpenCode Connect.
+- If \`opencode mcp list\` is empty but doctor/mcp-status sees servers, explain the runtime-vs-static config distinction and run \`hiai-opencode export-mcp .mcp.json\` if the user wants static visibility.
+- Do not run package installs unless the user explicitly asks.
+`

package/src/features/builtin-commands/types.ts

@@ -1,6 +1,6 @@
 import type { CommandDefinition } from "../claude-code-command-loader"
 
-export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "remove-ai-slops" | "mcp-status"
+export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph" | "ulw-loop" | "refactor" | "start-work" | "stop-continuation" | "handoff" | "remove-ai-slops" | "mcp-status" | "doctor"
 
 export interface BuiltinCommandConfig {
   disabled_commands?: BuiltinCommandName[]

package/src/features/builtin-skills/skills/hiai-opencode-setup.ts

@@ -0,0 +1,69 @@
+import type { BuiltinSkill } from "../types"
+
+export const hiaiOpencodeSetupSkill: BuiltinSkill = {
+  name: "hiai-opencode-setup",
+  description:
+    "Use when install/setup/onboarding or MCP debug mentions: install, setup, bootstrap, doctor, mcp-status, MCP not found, mcp list empty, MemPalace, RAG, firecrawl, stitch, sequential-thinking, playwright, DCP, agents, skills, or LSP.",
+  template: `# hiai-opencode Setup And Runtime Operations
+
+Use this skill for hiai-opencode installation, diagnostics, and integration repair.
+
+## Architecture
+
+- hiai-opencode is an OpenCode plugin, not a standalone app.
+- MCP servers are external upstream tools launched by hiai-opencode wiring.
+- The user-facing config is \`hiai-opencode.json\` or \`.opencode/hiai-opencode.json\`.
+- Model provider credentials belong to OpenCode Connect. Do not ask for \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, or \`ANTHROPIC_API_KEY\` for normal model usage.
+- Service credentials are separate: \`FIRECRAWL_API_KEY\`, \`STITCH_AI_API_KEY\`, \`CONTEXT7_API_KEY\`.
+
+## First Diagnostic Commands
+
+\`\`\`bash
+hiai-opencode doctor
+hiai-opencode mcp-status
+opencode debug config
+\`\`\`
+
+If \`opencode mcp list\` is empty but doctor/mcp-status sees servers, explain that OpenCode's list may read only static \`.mcp.json\`. Refresh static visibility:
+
+\`\`\`bash
+hiai-opencode export-mcp .mcp.json
+opencode mcp list --print-logs --log-level INFO
+\`\`\`
+
+## Plugin vs MCP
+
+Install OpenCode plugins with:
+
+\`\`\`bash
+opencode plugin @hiai-gg/hiai-opencode@latest --global
+opencode plugin @tarquinen/opencode-dcp@latest --global
+\`\`\`
+
+Do not add MCP packages to the OpenCode plugin array. MCP packages are launched through \`hiai-opencode.json\` and helper scripts.
+
+## MCP Runtime Notes
+
+- \`playwright\`: node/npx; browser binaries may need \`HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1\`; Linux system deps may require admin rights.
+- \`sequential-thinking\`: node/npx; use for complex planning, revision, and branching.
+- \`firecrawl\`: requires \`FIRECRAWL_API_KEY\`.
+- \`mempalace\`: prefers \`uv\`; otherwise Python 3.9+ with \`mempalace\`. Use \`mempalace_status\` first, search before answering memory questions, and never invent memories.
+- \`rag\`: requires \`OPENCODE_RAG_URL\` or a reachable default \`http://localhost:9002/tools/search\`.
+- \`stitch\`: requires \`STITCH_AI_API_KEY\`.
+- \`context7\`: remote docs/search; key optional but recommended for limits.
+
+## Calling MCP
+
+- Use native MCP tools if OpenCode exposes them.
+- Use \`skill_mcp\` for skill-embedded MCP or enabled hiai-opencode MCP.
+- If \`skill_mcp\` says a server is not found, check whether the skill is loaded, whether the MCP is enabled in \`hiai-opencode.json\`, and whether \`.mcp.json\` needs export.
+
+## Safety Rules
+
+- Report missing keys by env var name only. Never print key values.
+- Prefer project-local or user-level installs. Do not use sudo/admin rights unless the user explicitly asks.
+- Do not edit unrelated OpenCode/Claude/Agents global skill folders unless the user opts in.
+- Keep DCP separate: it is an optional OpenCode plugin, not part of the hiai-opencode package.
+`,
+  allowedTools: ["Bash(*)", "Read(*)", "Edit(*)", "Glob(*)", "Grep(*)", "skill_mcp(*)"],
+}

package/src/features/builtin-skills/skills/index.ts

@@ -5,3 +5,5 @@ export { gitMasterSkill } from "./git-master"
 export { devBrowserSkill } from "./dev-browser"
 export { reviewWorkSkill } from "./review-work"
 export { aiSlopRemoverSkill } from "./ai-slop-remover"
+export { hiaiOpencodeSetupSkill } from "./hiai-opencode-setup"
+export { websiteCopywritingSkill } from "./website-copywriting"

package/src/features/builtin-skills/skills/website-copywriting.ts

@@ -0,0 +1,41 @@
+import type { BuiltinSkill } from "../types"
+
+export const websiteCopywritingSkill: BuiltinSkill = {
+  name: "website-copywriting",
+  description:
+    "Writes sharp website/product copy: landing pages, hero sections, CTAs, feature blocks, positioning, naming, and tone of voice.",
+  template: `# Website Copywriting
+
+Use this skill for public-facing product and website text.
+
+## Inputs To Clarify
+
+- Audience: who reads this and what do they already know?
+- Goal: sign up, book demo, understand feature, trust product, recover from error, continue onboarding.
+- Tone: precise, playful, premium, technical, calm, bold, founder-led, enterprise, developer-first.
+- Proof: real features, constraints, metrics, customer pain, differentiators. Do not invent proof.
+
+## Output Shape
+
+Prefer copy that can be pasted into UI:
+
+- Hero: headline, subheadline, primary CTA, secondary CTA.
+- Feature block: title, one-sentence value, 2-4 proof bullets.
+- Section copy: heading, short intro, card titles, card bodies.
+- Microcopy: button labels, empty states, errors, onboarding hints.
+- Alternatives: 3-5 variants when tone or positioning is undecided.
+
+## Writing Rules
+
+- Specific beats clever. Concrete verbs beat vague hype.
+- Avoid generic AI language: seamless, unlock, supercharge, leverage, robust, cutting-edge, revolutionize, next-generation.
+- Keep claims tied to actual capabilities.
+- Use short lines for UI. Long paragraphs are usually wrong for websites.
+- Preserve product vocabulary from the codebase/docs when available.
+- If visual direction matters, pair with \`frontend-ui-ux\` or delegate visual work to Designer.
+
+## Delegation Hint
+
+Use \`task(subagent_type="brainstormer", load_skills=["website-copywriting"], ...)\` for copy-only work.
+Use \`category="writing"\` when a category is required. Writer/copywriter aliases map to Brainstormer.`,
+}

package/src/features/builtin-skills/skills.test.ts

@@ -0,0 +1,8 @@
+import { expect, test } from "bun:test"
+
+import { createBuiltinSkills } from "./skills"
+
+test("website-copywriting is available as a builtin skill", () => {
+  const skills = createBuiltinSkills()
+  expect(skills.some((skill) => skill.name === "website-copywriting")).toBe(true)
+})

package/src/features/builtin-skills/skills.ts

@@ -10,6 +10,8 @@ import {
   devBrowserSkill,
   reviewWorkSkill,
   aiSlopRemoverSkill,
+  hiaiOpencodeSetupSkill,
+  websiteCopywritingSkill,
 } from "./skills/index"
 
 export interface CreateBuiltinSkillsOptions {
@@ -29,7 +31,16 @@ export function createBuiltinSkills(options: CreateBuiltinSkillsOptions = {}): B
     browserSkill = playwrightSkill
   }
 
-  const skills = [browserSkill, frontendUiUxSkill, gitMasterSkill, devBrowserSkill, reviewWorkSkill, aiSlopRemoverSkill]
+  const skills = [
+    browserSkill,
+    hiaiOpencodeSetupSkill,
+    frontendUiUxSkill,
+    gitMasterSkill,
+    devBrowserSkill,
+    reviewWorkSkill,
+    aiSlopRemoverSkill,
+    websiteCopywritingSkill,
+  ]
 
   if (!disabledSkills) {
     return skills

package/src/features/skill-mcp-manager/AGENTS.md

@@ -10,7 +10,7 @@
 
 | Tier | Manager | Scope |
 |------|---------|-------|
-| 1. Built-in | `createBuiltinMcps()` (src/mcp/) | Global, 3 remote HTTP |
+| 1. Platform defaults | `HIAI_MCP_REGISTRY` (src/mcp/registry.ts) | Global MCP defaults materialized from hiai-opencode.json |
 | 2. Claude Code | `claude-code-mcp-loader` (src/features/) | From `.mcp.json` |
 | 3. **Skill-embedded** | **`SkillMcpManager` (this module)** | **Per-session, from SKILL.md YAML** |
 

package/src/hooks/agent-usage-reminder/constants.ts

@@ -30,13 +30,13 @@ export const REMINDER_MESSAGE = `
 
 You called a search/fetch tool directly without leveraging specialized agents.
 
-RECOMMENDED: Use task with explore/librarian agents for better results:
+RECOMMENDED: Use task with researcher agents for better results:
 
 \`\`\`
 // Parallel exploration - fire multiple agents simultaneously
-task(subagent_type="explore", load_skills=[], prompt="Find all files matching pattern X")
-task(subagent_type="explore", load_skills=[], prompt="Search for implementation of Y")
-task(subagent_type="librarian", load_skills=[], prompt="Lookup documentation for Z")
+task(subagent_type="researcher", load_skills=[], prompt="Find all files matching pattern X")
+task(subagent_type="researcher", load_skills=[], prompt="Search for implementation of Y")
+task(subagent_type="researcher", load_skills=[], prompt="Lookup documentation for Z")
 
 // Then continue your work while they run in background
 // System will notify you when each completes

package/src/hooks/index.ts

@@ -28,8 +28,6 @@ export { createThinkingBlockValidatorHook } from "./thinking-block-validator";
 export { createToolPairValidatorHook } from "./tool-pair-validator";
 export { createCategorySkillReminderHook } from "./category-skill-reminder";
 export { createRalphLoopHook, type RalphLoopHook } from "./ralph-loop";
-export { createNoBobGptHook } from "./no-bob-gpt";
-export { createNoCoderNonGptHook } from "./no-coder-non-gpt";
 export { createAutoSlashCommandHook } from "./auto-slash-command";
 export { createEditErrorRecoveryHook } from "./edit-error-recovery";
 

package/src/hooks/keyword-detector/ultrawork/default.ts

@@ -95,50 +95,50 @@ TELL THE USER WHAT AGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
 
 ## MANDATORY: PLAN AGENT INVOCATION (NON-NEGOTIABLE)
 
-**YOU MUST ALWAYS INVOKE THE PLAN AGENT FOR ANY NON-TRIVIAL TASK.**
+**YOU MUST ALWAYS INVOKE THE STRATEGIST AGENT FOR ANY NON-TRIVIAL TASK.**
 
 | Condition | Action |
 |-----------|--------|
-| Task has 2+ steps | MUST call plan agent |
-| Task scope unclear | MUST call plan agent |
-| Implementation required | MUST call plan agent |
-| Architecture decision needed | MUST call plan agent |
+| Task has 2+ steps | MUST call strategist agent |
+| Task scope unclear | MUST call strategist agent |
+| Implementation required | MUST call strategist agent |
+| Architecture decision needed | MUST call strategist agent |
 
 \`\`\`
-task(subagent_type="plan", load_skills=[], run_in_background=false, prompt="<gathered context + user request>")
+task(subagent_type="strategist", load_skills=[], run_in_background=false, prompt="<gathered context + user request>")
 \`\`\`
 
-**WHY PLAN AGENT IS MANDATORY:**
-- Plan agent analyzes dependencies and parallel execution opportunities
-- Plan agent outputs a **parallel task graph** with waves and dependencies
-- Plan agent provides structured TODO list with category + skills per task
+**WHY STRATEGIST AGENT IS MANDATORY:**
+- Strategist analyzes dependencies and parallel execution opportunities
+- Strategist outputs a **parallel task graph** with waves and dependencies
+- Strategist provides structured TODO list with category + skills per task
 - YOU are an orchestrator, NOT an implementer
 
-### SESSION CONTINUITY WITH PLAN AGENT (CRITICAL)
+### SESSION CONTINUITY WITH STRATEGIST AGENT (CRITICAL)
 
-**Plan agent returns a session_id. USE IT for follow-up interactions.**
+**Strategist agent returns a session_id. USE IT for follow-up interactions.**
 
 | Scenario | Action |
 |----------|--------|
-| Plan agent asks clarifying questions | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="<your answer>")\` |
+| Strategist asks clarifying questions | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="<your answer>")\` |
 | Need to refine the plan | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Please adjust: <feedback>")\` |
-| Plan needs more detail | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Add more detail to Task N")\` |
+| Strategist needs more detail | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Add more detail to Task N")\` |
 
 **WHY SESSION_ID IS CRITICAL:**
-- Plan agent retains FULL conversation context
+- Strategist retains FULL conversation context
 - No repeated exploration or context gathering
 - Saves 70%+ tokens on follow-ups
 - Maintains interview continuity until plan is finalized
 
 \`\`\`
 // WRONG: Starting fresh loses all context
-task(subagent_type="plan", load_skills=[], run_in_background=false, prompt="Here's more info...")
+task(subagent_type="strategist", load_skills=[], run_in_background=false, prompt="Here's more info...")
 
 // CORRECT: Resume preserves everything
 task(session_id="ses_abc123", load_skills=[], run_in_background=false, prompt="Here's my answer to your question: ...")
 \`\`\`
 
-**FAILURE TO CALL PLAN AGENT = INCOMPLETE WORK.**
+**FAILURE TO CALL STRATEGIST AGENT = INCOMPLETE WORK.**
 
 ---
 
@@ -150,7 +150,7 @@ task(session_id="ses_abc123", load_skills=[], run_in_background=false, prompt="H
 |-----------|--------|-----|
 | Codebase exploration | task(subagent_type="researcher", load_skills=[], run_in_background=true) | Parallel, context-efficient |
 | Documentation lookup | task(subagent_type="researcher", load_skills=[], run_in_background=true) | Specialized knowledge |
-| Planning | task(subagent_type="plan", load_skills=[], run_in_background=false) | Parallel task graph + structured TODO list |
+| Planning | task(subagent_type="strategist", load_skills=[], run_in_background=false) | Parallel task graph + structured TODO list |
 | Hard problem (conventional) | task(subagent_type="strategist", load_skills=[], run_in_background=false) | Architecture, planning, complex logic |
 | Hard problem (review/debugging) | task(subagent_type="critic", load_skills=[], run_in_background=false) | Verification, debugging, high-risk review |
 | Hard problem (non-conventional) | task(category="artistry", load_skills=[...], run_in_background=true) | Different approach needed |

package/src/hooks/keyword-detector/ultrawork/gemini.ts

@@ -66,9 +66,9 @@ Where TYPE is one of: research | implementation | investigation | evaluation | f
 **IF YOU ARE NOT 100% CERTAIN:**
 
 1. **THINK DEEPLY** - What is the user's TRUE intent? What problem are they REALLY trying to solve?
-2. **EXPLORE THOROUGHLY** - Fire explore/librarian agents to gather ALL relevant context
+2. **EXPLORE THOROUGHLY** - Fire researcher agents (multiple parallel) to gather ALL relevant context
 3. **CONSULT SPECIALISTS** - For hard/complex tasks, DO NOT struggle alone. Delegate:
-   - **Logician**: Conventional problems - architecture, debugging, complex logic
+   - **Strategist**: Conventional problems - architecture, debugging, complex logic
    - **Artistry**: Non-conventional problems - different approach needed, unusual constraints
 4. **ASK THE USER** - If ambiguity remains after exploration, ASK. Don't guess.
 
@@ -81,9 +81,9 @@ Where TYPE is one of: research | implementation | investigation | evaluation | f
 
 **WHEN IN DOUBT:**
 \`\`\`
-task(subagent_type="explore", load_skills=[], prompt="I'm implementing [TASK DESCRIPTION] and need to understand [SPECIFIC KNOWLEDGE GAP]. Find [X] patterns in the codebase - show file paths, implementation approach, and conventions used. I'll use this to [HOW RESULTS WILL BE USED]. Focus on src/ directories, skip test files unless test patterns are specifically needed. Return concrete file paths with brief descriptions of what each file does.", run_in_background=true)
-task(subagent_type="librarian", load_skills=[], prompt="I'm working with [LIBRARY/TECHNOLOGY] and need [SPECIFIC INFORMATION]. Find official documentation and production-quality examples for [Y] - specifically: API reference, configuration options, recommended patterns, and common pitfalls. Skip beginner tutorials. I'll use this to [DECISION THIS WILL INFORM].", run_in_background=true)
-task(subagent_type="logician", load_skills=[], prompt="I need architectural review of my approach to [TASK]. Here's my plan: [DESCRIBE PLAN WITH SPECIFIC FILES AND CHANGES]. My concerns are: [LIST SPECIFIC UNCERTAINTIES]. Please evaluate: correctness of approach, potential issues I'm missing, and whether a better alternative exists.", run_in_background=false)
+task(subagent_type="researcher", load_skills=[], prompt="I'm implementing [TASK DESCRIPTION] and need to understand [SPECIFIC KNOWLEDGE GAP]. Find [X] patterns in the codebase - show file paths, implementation approach, and conventions used. I'll use this to [HOW RESULTS WILL BE USED]. Focus on src/ directories, skip test files unless test patterns are specifically needed. Return concrete file paths with brief descriptions of what each file does.", run_in_background=true)
+task(subagent_type="researcher", load_skills=[], prompt="I'm working with [LIBRARY/TECHNOLOGY] and need [SPECIFIC INFORMATION]. Find official documentation and production-quality examples for [Y] - specifically: API reference, configuration options, recommended patterns, and common pitfalls. Skip beginner tutorials. I'll use this to [DECISION THIS WILL INFORM].", run_in_background=true)
+task(subagent_type="strategist", load_skills=[], prompt="I need architectural review of my approach to [TASK]. Here's my plan: [DESCRIBE PLAN WITH SPECIFIC FILES AND CHANGES]. My concerns are: [LIST SPECIFIC UNCERTAINTIES]. Please evaluate: correctness of approach, potential issues I'm missing, and whether a better alternative exists.", run_in_background=false)
 \`\`\`
 
 **ONLY AFTER YOU HAVE:**
@@ -118,7 +118,7 @@ task(subagent_type="logician", load_skills=[], prompt="I need architectural revi
 **IF YOU ENCOUNTER A BLOCKER:**
 1. **DO NOT** give up
 2. **DO NOT** deliver a compromised version
-3. **DO** consult specialists (logician for conventional, artistry for non-conventional)
+3. **DO** consult specialists (strategist for conventional, artistry for non-conventional)
 4. **DO** ask the user for guidance
 5. **DO** explore alternative approaches
 
@@ -150,26 +150,26 @@ TELL THE USER WHAT AGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
 
 | Condition | Action |
 |-----------|--------|
-| Task has 2+ steps | MUST call plan agent |
-| Task scope unclear | MUST call plan agent |
-| Implementation required | MUST call plan agent |
-| Architecture decision needed | MUST call plan agent |
+| Task has 2+ steps | MUST call strategist agent |
+| Task scope unclear | MUST call strategist agent |
+| Implementation required | MUST call strategist agent |
+| Architecture decision needed | MUST call strategist agent |
 
 \`\`\`
-task(subagent_type="plan", load_skills=[], run_in_background=false, prompt="<gathered context + user request>")
+task(subagent_type="strategist", load_skills=[], run_in_background=false, prompt="<gathered context + user request>")
 \`\`\`
 
-### SESSION CONTINUITY WITH PLAN AGENT (CRITICAL)
+### SESSION CONTINUITY WITH STRATEGIST AGENT (CRITICAL)
 
-**Plan agent returns a session_id. USE IT for follow-up interactions.**
+**Strategist agent returns a session_id. USE IT for follow-up interactions.**
 
 | Scenario | Action |
 |----------|--------|
-| Plan agent asks clarifying questions | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="<your answer>")\` |
+| Strategist asks clarifying questions | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="<your answer>")\` |
 | Need to refine the plan | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Please adjust: <feedback>")\` |
-| Plan needs more detail | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Add more detail to Task N")\` |
+| Strategist needs more detail | \`task(session_id="{returned_session_id}", load_skills=[], run_in_background=false, prompt="Add more detail to Task N")\` |
 
-**FAILURE TO CALL PLAN AGENT = INCOMPLETE WORK.**
+**FAILURE TO CALL STRATEGIST AGENT = INCOMPLETE WORK.**
 
 ---
 
@@ -181,10 +181,10 @@ task(subagent_type="plan", load_skills=[], run_in_background=false, prompt="<gat
 
 | Task Type | Action | Why |
 |-----------|--------|-----|
-| Codebase exploration | task(subagent_type="explore", load_skills=[], run_in_background=true) | Parallel, context-efficient |
-| Documentation lookup | task(subagent_type="librarian", load_skills=[], run_in_background=true) | Specialized knowledge |
-| Planning | task(subagent_type="plan", load_skills=[], run_in_background=false) | Parallel task graph + structured TODO list |
-| Hard problem (conventional) | task(subagent_type="logician", load_skills=[], run_in_background=false) | Architecture, debugging, complex logic |
+| Codebase exploration | task(subagent_type="researcher", load_skills=[], run_in_background=true) | Parallel, context-efficient |
+| Documentation lookup | task(subagent_type="researcher", load_skills=[], run_in_background=true) | Specialized knowledge |
+| Planning | task(subagent_type="strategist", load_skills=[], run_in_background=false) | Parallel task graph + structured TODO list |
+| Hard problem (conventional) | task(subagent_type="strategist", load_skills=[], run_in_background=false) | Architecture, debugging, complex logic |
 | Hard problem (non-conventional) | task(category="artistry", load_skills=[...], run_in_background=true) | Different approach needed |
 | Implementation | task(category="...", load_skills=[...], run_in_background=true) | Domain-optimized models |
 
@@ -206,7 +206,7 @@ task(subagent_type="plan", load_skills=[], run_in_background=false, prompt="<gat
 
 ## WORKFLOW
 1. **CLASSIFY INTENT** (MANDATORY - see GEMINI_INTENT_GATE above)
-2. Spawn exploration/librarian agents via task(run_in_background=true) in PARALLEL
+2. Spawn researcher agents via task(run_in_background=true) in PARALLEL
 3. Use Plan agent with gathered context to create detailed work breakdown
 4. Execute with continuous verification against original requirements
 

package/src/hooks/keyword-detector/ultrawork/gpt.ts

@@ -69,15 +69,13 @@ Use these when they provide clear value based on the decision framework above:
 
 | Resource | When to Use | How to Use |
 |----------|-------------|------------|
-| explore agent | Need codebase patterns you don't have | \`task(subagent_type="explore", load_skills=[], run_in_background=true, ...)\` |
-| librarian agent | External library docs, OSS examples | \`task(subagent_type="librarian", load_skills=[], run_in_background=true, ...)\` |
-| logician agent | Stuck on architecture/debugging after 2+ attempts | \`task(subagent_type="logician", load_skills=[], run_in_background=false, ...)\` |
-| plan agent | Complex multi-step with dependencies (5+ steps) | \`task(subagent_type="plan", load_skills=[], run_in_background=false, ...)\` |
+| researcher agent | Need codebase patterns or external docs | \`task(subagent_type="researcher", load_skills=[], run_in_background=true, ...)\` |
+| strategist agent | Complex multi-step (5+ steps) or architecture decisions | \`task(subagent_type="strategist", load_skills=[], run_in_background=false, ...)\` |
 | task category | Specialized work matching a category | \`task(category="...", load_skills=[...], run_in_background=true)\` |
 
 <tool_usage_rules>
 - Prefer tools over internal knowledge for fresh or user-specific data
-- Parallelize independent reads (read_file, grep, explore, librarian) to reduce latency
+- Parallelize independent reads (read_file, grep, researcher) to reduce latency
 - After any write/update, briefly restate: What changed, Where (path), Follow-up needed
 </tool_usage_rules>
 
@@ -88,13 +86,13 @@ Use these when they provide clear value based on the decision framework above:
 | Track | Tools | Speed | Purpose |
 |-------|-------|-------|---------|
 | **Direct** | Grep, Read, LSP, AST-grep | Instant | Quick wins, known locations |
-| **Background** | explore, librarian agents | Async | Deep search, external docs |
+| **Background** | researcher agents | Async | Deep search, external docs |
 
 **ALWAYS run both tracks in parallel:**
 \`\`\`
 // Fire background agents for deep exploration
-task(subagent_type="explore", load_skills=[], prompt="I'm implementing [TASK] and need to understand [KNOWLEDGE GAP]. Find [X] patterns in the codebase - file paths, implementation approach, conventions used, and how modules connect. I'll use this to [DOWNSTREAM DECISION]. Focus on production code in src/. Return file paths with brief descriptions.", run_in_background=true)
-task(subagent_type="librarian", load_skills=[], prompt="I'm working with [TECHNOLOGY] and need [SPECIFIC INFO]. Find official docs and production examples for [Y] - API reference, configuration, recommended patterns, and pitfalls. Skip tutorials. I'll use this to [DECISION THIS INFORMS].", run_in_background=true)
+task(subagent_type="researcher", load_skills=[], prompt="I'm implementing [TASK] and need to understand [KNOWLEDGE GAP]. Find [X] patterns in the codebase - file paths, implementation approach, conventions used, and how modules connect. I'll use this to [DOWNSTREAM DECISION]. Focus on production code in src/. Return file paths with brief descriptions.", run_in_background=true)
+task(subagent_type="researcher", load_skills=[], prompt="I'm working with [TECHNOLOGY] and need [SPECIFIC INFO]. Find official docs and production examples for [Y] - API reference, configuration, recommended patterns, and pitfalls. Skip tutorials. I'll use this to [DECISION THIS INFORMS].", run_in_background=true)
 
 // WHILE THEY RUN - use direct tools for immediate context
 grep(pattern="relevant_pattern", path="src/")

package/src/hooks/keyword-detector/ultrawork/planner.ts

@@ -33,14 +33,14 @@ REFUSE. Say: "I'm a planner. I create work plans, not implementations. Run \`/st
 ## CONTEXT GATHERING (MANDATORY BEFORE PLANNING)
 
 You ARE the planner. Your job: create bulletproof work plans.
-**Before drafting ANY plan, gather context via explore/librarian agents.**
+**Before drafting ANY plan, gather context via researcher agents.**
 
 ### Research Protocol
 1. **Fire parallel background agents** for comprehensive context:
    \`\`\`
-   task(subagent_type="explore", load_skills=[], prompt="Find existing patterns for [topic] in codebase", run_in_background=true)
-   task(subagent_type="explore", load_skills=[], prompt="Find test infrastructure and conventions", run_in_background=true)
-   task(subagent_type="librarian", load_skills=[], prompt="Find official docs and best practices for [technology]", run_in_background=true)
+   task(subagent_type="researcher", load_skills=[], prompt="Find existing patterns for [topic] in codebase", run_in_background=true)
+   task(subagent_type="researcher", load_skills=[], prompt="Find test infrastructure and conventions", run_in_background=true)
+   task(subagent_type="researcher", load_skills=[], prompt="Find official docs and best practices for [technology]", run_in_background=true)
    \`\`\`
 2. **Wait for results** before planning - rushed plans fail
 3. **Synthesize findings** into informed requirements
@@ -49,7 +49,7 @@ You ARE the planner. Your job: create bulletproof work plans.
 - Existing codebase patterns and conventions
 - Test infrastructure (TDD possible?)
 - External library APIs and constraints
-- Similar implementations in OSS (via librarian)
+- Similar implementations in OSS (via researcher)
 
 **NEVER plan blind. Context first, plan second.**