opencode-dux 1.0.0

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "opencode-dux",
+  "version": "1.0.0",
+  "description": "Agent orchestration, management, and operations plugin for OpenCode",
+  "main": "index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./src/index.ts"
+    },
+    "./tui": {
+      "import": "./src/tui.ts",
+      "types": "./dist/tui.d.ts"
+    }
+  },
+  "bin": {
+    "opencode-dux": "./dist/cli/index.js"
+  },
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai",
+    "agents",
+    "orchestration",
+    "llm",
+    "claude",
+    "gpt",
+    "gemini"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bakhtiar-personal-work/opencode-dux"
+  },
+  "bugs": {
+    "url": "https://github.com/bakhtiar-personal-work/opencode-dux/issues"
+  },
+  "homepage": "https://github.com/bakhtiar-personal-work/opencode-dux#readme",
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "opencode-dux.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:plugin": "bun build src/index.ts src/tui.ts --outdir dist --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external @opentui/core --external @opentui/solid --external jsdom --external zod --external solid-js",
+    "build:cli": "bun build src/cli/index.ts --outdir dist/cli --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external jsdom --external zod",
+    "clean": "bun -e \"import{rmSync}from'node:fs';rmSync('dist',{recursive:true,force:true});console.log('Cleaned dist/')\"",
+    "build": "bun run clean && bun run build:plugin && bun run build:cli && tsc --emitDeclarationOnly && bun run generate-schema",
+    "contributors:add": "all-contributors add",
+    "contributors:check": "all-contributors check",
+    "contributors:generate": "all-contributors generate",
+    "generate-schema": "bun run scripts/generate-schema.ts",
+    "verify:release": "bun run scripts/verify-release-artifact.ts",
+    "verify:host-smoke": "bun run scripts/verify-opencode-host-smoke.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome lint .",
+    "format": "biome format . --write",
+    "check": "biome check --write .",
+    "check:ci": "biome check .",
+    "dev": "bun run build && opencode",
+    "prepublishOnly": "bun run build",
+    "release:patch": "npm version patch && git push --follow-tags && npm publish",
+    "release:minor": "npm version minor && git push --follow-tags && npm publish",
+    "release:major": "npm version major && git push --follow-tags && npm publish"
+  },
+  "dependencies": {
+    "@ast-grep/cli": "^0.42.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "^0.6.0",
+    "@opencode-ai/plugin": "^1.3.17",
+    "@opencode-ai/sdk": "^1.3.17",
+    "jsdom": "^26.1.0",
+    "lru-cache": "^11.3.3",
+    "turndown": "^7.2.4"
+  },
+  "optionalDependencies": {
+    "@opentui/solid": "^0.1.97"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.11",
+    "@types/bun": "latest",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^24.12.4",
+    "@types/turndown": "^5.0.6",
+    "all-contributors-cli": "^6.26.1",
+    "bun-types": "1.3.12",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "trustedDependencies": [
+    "@ast-grep/cli"
+  ],
+  "private": false
+}

package/src/agents/descriptions.ts

@@ -0,0 +1,55 @@
+/**
+ * Centralized agent descriptions used by the orchestrator prompt,
+ * SDK registration, and sidebar UI labels.
+ */
+
+// XML-formatted agent descriptions for the orchestrator delegation prompt
+export const AGENT_DESCRIPTIONS: Record<string, string> = {
+  explorer: `<agent name="@explorer">
+- Role: codebase search specialist
+- Delegate when: locate files, usages, symbols, tests, config links
+- Do not use when: exact file is already known and must be read in full
+</agent>`,
+  librarian: `<agent name="@librarian">
+- Role: external docs and API reference specialist
+- Delegate when: library behavior, version details, official examples, upstream GitHub issues/PRs/releases
+- Do not use when: pure language fundamentals or local code discovery
+</agent>`,
+  oracle: `<agent name="@oracle">
+- Role: technical analysis and code review; uses orchestrator \`model\` + \`variant\` matrix
+- Delegate when: debugging, architecture, tradeoffs, risk, any review depth
+- Do not use when: pure local discovery (@explorer) or docs-only (@librarian)
+</agent>`,
+  designer: `<agent name="@designer">
+- Role: UI/UX specialist for ALL user-facing UI — new pages, existing component changes, layout updates, styling, visual polish, a11y
+- Delegate when: ANY change to TSX/JSX files, components, pages, layouts, styling, or user-facing visual elements — BEFORE @oracle or @fixer
+- Do not use when: backend-only, non-visual work, or pure logic changes (hooks/utils) that don't affect rendering
+</agent>`,
+  fixer: `<agent name="@fixer">
+- Role: implementation specialist
+- Delegate when: edits, tests, scoped commands-after gates in <first_gate> when applicable
+- Do not use when: strategy/conventions/UI design still unresolved-delegate upward first
+</agent>`,
+  steward: `<agent name="@steward">
+- Role: rules citation from steward_paths — verbatim excerpts only; does NOT analyze, evaluate, or compare rules
+- Delegate when: repo conventions needed before oracle/fixer (see <first_gate> 1)
+- Do not use when: pure symbol search (@explorer); rules analysis (@oracle).
+</agent>`,
+  interpreter: `<agent name="@interpreter">
+- Role: screenshot / attached-image analyst
+- Delegate when: user message has images and task is not redesign-only
+- Do not use when: redesign-only-use @designer; text-only prompts
+</agent>`,
+};
+
+// Compact sidebar labels for the TUI agent list
+export const AGENT_SIDEBAR_DESCRIPTIONS: Record<string, string> = {
+  orchestrator: 'Orchestrates',
+  explorer: 'File Search',
+  librarian: 'Doc Search',
+  oracle: 'Architecture',
+  designer: 'Design',
+  fixer: 'Implement',
+  steward: 'Repo rules',
+  interpreter: 'Vision',
+};

package/src/agents/designer.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'bun:test';
+import { createDesignerAgent } from './designer';
+
+describe('createDesignerAgent', () => {
+  test('creates agent with correct name', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    expect(agent.name).toBe('designer');
+  });
+
+  test('sets the provided model', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    expect(agent.config.model).toBe('test/designer-model');
+  });
+
+  test('prompt contains expected sections', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('<role>');
+    expect(prompt).toContain('<discovery_first>');
+    expect(prompt).toContain('<design_principles>');
+    expect(prompt).toContain('<vision_and_evidence>');
+    expect(prompt).toContain('<user_choice_policy>');
+    expect(prompt).toContain('<constraints>');
+    expect(prompt).toContain('<variant_policy>');
+    expect(prompt).toContain('<output_format>');
+  });
+
+  test('has temperature 0.3', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    expect(agent.config.temperature).toBe(0.3);
+  });
+
+  test('custom prompt overrides the base prompt', () => {
+    const agent = createDesignerAgent(
+      'test/designer-model',
+      'Custom designer prompt',
+    );
+    expect(agent.config.prompt).toBe('Custom designer prompt');
+  });
+
+  test('custom append prompt is appended to base', () => {
+    const agent = createDesignerAgent(
+      'test/designer-model',
+      undefined,
+      'Extra instructions',
+    );
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('Extra instructions');
+    expect(prompt).toContain('<role>');
+  });
+
+  test('has description', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    expect(agent.description).toBeTruthy();
+    expect(agent.description?.length).toBeGreaterThan(10);
+  });
+
+  test('prompt contains all required sections (complete check)', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    const prompt = agent.config.prompt ?? '';
+    const requiredSections = [
+      '<role>',
+      '<discovery_first>',
+      '<design_principles>',
+      '<vision_and_evidence>',
+      '<user_choice_policy>',
+      '<constraints>',
+      '<variant_policy>',
+      '<output_format>',
+      '<design_plan>',
+      '<accessibility_check>',
+      '<implementation_notes>',
+      '<blocked>',
+    ];
+    for (const section of requiredSections) {
+      expect(prompt).toContain(section);
+    }
+  });
+
+  test('prompt does not contain resolver boilerplate', () => {
+    const agent = createDesignerAgent('test/designer-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).not.toContain('if (customPrompt)');
+    expect(prompt).not.toContain('else if (customAppendPrompt)');
+  });
+});

package/src/agents/designer.ts

@@ -0,0 +1,154 @@
+import type { AgentDefinition } from './orchestrator';
+import { resolvePrompt } from './orchestrator';
+import {
+  DESIGNER_VARIANT_SCOPE_LINES,
+  formatBlockedOutputBlock,
+  NEEDS_USER_OUTPUT_FORMAT_BLOCK,
+  REPO_RULES_PRECEDENCE_BLOCK,
+  SELF_REVIEW_BLOCK,
+  SUBAGENT_NEEDS_USER_FORMAT,
+  USER_CHOICE_POLICY_BLOCK,
+} from './prompt-blocks';
+
+const DESIGNER_CRITICAL_INVARIANTS = `<critical_invariants>
+Violating any = failure mode.
+1) DEFAULT: design-review mode — produce plan + \`<implementation_notes>\` for ALL UI work routed to you (new pages, existing component changes, layout, styling, visual elements). Only implement yourself when the task explicitly orders implementation. If the task scope includes any user-facing UI, your review is mandatory — do not defer to @oracle or @fixer.
+2) NEVER assume a styling system without glob evidence. Undetectable → <blocked>.
+3) NEVER invent new design tokens when project tokens already fit.
+4) NEVER modify files or delegate to subagents.
+</critical_invariants>`;
+
+const DESIGNER_PROMPT = `<role>
+You are Designer, the sole authority on ALL user-facing UI work. You handle new pages, existing component modifications, layout changes, styling updates, visual polish, and accessibility. No UI change — new or existing — should reach @fixer without your design review. The orchestrator MUST route all UI work to you before @oracle or @fixer.
+</role>
+
+${DESIGNER_CRITICAL_INVARIANTS}
+
+${REPO_RULES_PRECEDENCE_BLOCK}
+
+<discovery_first>
+Detect styling system (skip if task prompt spec):
+1) Glob for styling evidence (in order):
+   - \`**/tailwind.config.*\` (Tailwind)
+   - \`**/unocss.config.*\` (UnoCSS)
+   - \`**/panda.config.*\` (Panda CSS)
+   - \`**/*.module.css\` (CSS Modules)
+   - \`**/package.json\` then grep for "styled-components", "emotion", "vanilla-extract"
+   - \`**/tokens.*\` or \`**/design-tokens/**\` (design token files)
+2) Read found configs → extract project breakpoints & component library (shadcn/Radix/Headless UI/MUI/Chakra/Mantine/custom)
+3) NEVER assume Tailwind without evidence; if system undetectable → <blocked>
+</discovery_first>
+
+<tool_routing>
+- Detect styling system: glob for config files (\`tailwind.config.*\`, \`unocss.config.*\`, \`panda.config.*\`, etc.) first; use read only on the files actually found.
+- Read component/page sources: prefer targeted reads of the specific component named in the task; use search tools to locate the file if not provided in context.
+- Avoid bulk reads: do not read entire directories; locate the minimal set needed to detect styling idioms and implement the plan.
+- If no styling system can be detected after reasonable glob/search attempts, report in \`<blocked>\`.
+</tool_routing>
+
+<design_principles>
+- Maintain cohesive visual language using the project's existing tokens.
+- Prefer strong intentional hierarchy, spacing, and contrast.
+- Use the project's primary styling mechanism first; introduce alternatives only with explicit justification.
+- Verify responsive behavior at the breakpoints the project actually defines (read them from config).
+</design_principles>
+
+<vision_and_evidence>
+- With an image (screenshot, mock, error capture): describe layout and visible issues → propose prioritized UX improvements → map them to concrete implementation steps.
+- Without an image: read component/page sources and infer likely UX issues-label inferences distinctly from visually confirmed findings.
+- Direct implementation stays aligned with detected tokens/components; novelty is justified only when the task explicitly pushes new patterns.
+</vision_and_evidence>
+
+<constraints>
+- DEFAULT: design-review mode - produce \`<implementation_notes>\` for @fixer. Only implement when task explicitly orders.
+- If user-facing scope ambiguous → <needs_user> (per <user_choice_policy>). If tooling/styling undetectable → <blocked>.
+- Only apply patches yourself when the task prompt explicitly instructs Designer to implement.
+- Respect existing design system tokens and component patterns.
+- Prioritize accessibility and keyboard navigation (WCAG AA contrast minimum).
+- Avoid cosmetic changes that regress usability.
+- Never invent new tokens when an existing one fits.
+- NEVER propose deleting or restructuring code beyond the explicit scope of
+  the design request.
+</constraints>
+
+${USER_CHOICE_POLICY_BLOCK}
+<designer_choice_supplement>
+- Layout & pattern forks (e.g. primary action left vs right, toolbar vs footer, modal vs inline, tabs vs stepper, dense vs spacious) when the task does not mandate one: <needs_user>-each option \`description\` states the UX consequence.
+- User-visible copy or tone when multiple wordings change meaning or stakes and the brief is silent: <needs_user>.
+</designer_choice_supplement>
+
+<variant_policy>
+${DESIGNER_VARIANT_SCOPE_LINES.map((l) => `- ${l}`).join('\n')}
+</variant_policy>
+
+${SUBAGENT_NEEDS_USER_FORMAT}
+
+${SELF_REVIEW_BLOCK}
+
+<output_format>
+<design_plan>
+- List each proposed change as a concrete action: component name or file, what changes (token, spacing, color, layout, copy), and why (contrast, hierarchy, accessibility, usability)
+- Prioritize by user impact: critical issues first, polish last
+- Separate visual changes from interaction/behavior changes
+</design_plan>
+<accessibility_check>
+- WCAG 2.1 AA minimum
+- contrast
+- focus order
+- semantic labels/roles
+- keyboard interaction
+</accessibility_check>
+<implementation_notes>
+- concrete component or style targets
+- if implementation is needed, include a handoff checklist for @fixer with file targets and acceptance criteria
+</implementation_notes>
+${formatBlockedOutputBlock('the design system cannot be detected or styling context is missing')}
+${NEEDS_USER_OUTPUT_FORMAT_BLOCK}
+
+Batch every UX pattern choice in one handoff — and include <user_choice_policy> context.
+<good_example>
+<needs_user>
+<reason>Config panel entry point ambiguous: modal or inline?</reason>
+<questions>[{"question": "Should the config panel be a modal overlay or an inline section?", "header": "Config panel style", "options": [{"label": "Modal", "description": "Overlay dialog; better focus, interrupts workflow"}, {"label": "Inline", "description": "Same-page section; non-disruptive, visible alongside content"}]}]</questions>
+</needs_user>
+</good_example>
+<iteration>
+If the orchestrator reports the plan was rejected or needs revision, adjust the plan in a follow-up - do not repeat unchanged sections, only emit deltas.
+</iteration>
+
+<good_example>
+User: "Improve the login form UX"
+Designer: Detects Tailwind + shadcn, proposes 3 changes (spacing, contrast, focus order).
+Returns: <design_plan> with file targets + <implementation_notes> for @fixer.
+</good_example>
+
+<bad_example>
+User: "Improve the login form UX"
+Designer: Assumes React + Material UI (wrong), proposes changes using non-existent tokens.
+Missing: discovery_first step, project evidence.
+</bad_example>
+</output_format>`;
+
+export function createDesignerAgent(
+  model: string,
+  customPrompt?: string,
+  customAppendPrompt?: string,
+): AgentDefinition {
+  const prompt = resolvePrompt(
+    DESIGNER_PROMPT,
+    customPrompt,
+    customAppendPrompt,
+  );
+
+  return {
+    name: 'designer',
+    description:
+      'UI/UX design, review, and implementation. Use for styling, responsive design, component architecture and visual polish.',
+    config: {
+      model,
+      // 0.3 provides enough variation for creative UI texture choices while staying deterministic enough for consistent design-system application
+      temperature: 0.3,
+      prompt,
+    },
+  };
+}

package/src/agents/display-name.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, test } from 'bun:test';
+import type { PluginConfig } from '../config';
+import { createAgents, getAgentConfigs } from './index';
+
+describe('displayName', () => {
+  test('stores displayName on agent when configured', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: 'researcher' },
+      },
+    };
+
+    const agents = await createAgents(config);
+    const explorer = agents.find((a) => a.name === 'explorer');
+    expect(explorer?.displayName).toBe('researcher');
+
+    const sdkConfigs = await getAgentConfigs(config);
+    expect((sdkConfigs.explorer as { displayName?: string }).displayName).toBe(
+      'researcher',
+    );
+  });
+
+  test('injects configured displayName into orchestrator prompt mentions', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: 'researcher' },
+      },
+    };
+
+    const agents = await createAgents(config);
+    const orchestrator = agents.find((a) => a.name === 'orchestrator');
+    const prompt = orchestrator?.config.prompt ?? '';
+
+    expect(prompt).toContain('@researcher');
+    expect(prompt).not.toMatch(/@explorer\b/);
+  });
+
+  test('normalizes @-prefixed displayName in prompt injection', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: '@researcher' },
+      },
+    };
+
+    const agents = await createAgents(config);
+    const orchestrator = agents.find((a) => a.name === 'orchestrator');
+    const prompt = orchestrator?.config.prompt ?? '';
+
+    expect(prompt).toContain('@researcher');
+    expect(prompt).not.toContain('@@researcher');
+    expect(prompt).not.toMatch(/@explorer\b/);
+  });
+
+  test('normalizes whitespace-padded displayName in prompt injection', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: '  researcher  ' },
+      },
+    };
+
+    const agents = await createAgents(config);
+    const orchestrator = agents.find((a) => a.name === 'orchestrator');
+    const prompt = orchestrator?.config.prompt ?? '';
+
+    expect(prompt).toContain('@researcher');
+    expect(prompt).not.toContain('@ researcher ');
+    expect(prompt).not.toMatch(/@explorer\b/);
+  });
+
+  test('throws when duplicate displayName is assigned', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: 'helper' },
+        librarian: { displayName: 'helper' },
+      },
+    };
+
+    await expect(createAgents(config)).rejects.toThrow(
+      "Duplicate displayName 'helper' assigned to multiple agents",
+    );
+  });
+
+  test('throws when normalized duplicate displayName is assigned', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: 'advisor' },
+        librarian: { displayName: ' @advisor ' },
+      },
+    };
+
+    await expect(createAgents(config)).rejects.toThrow(
+      "Duplicate displayName 'advisor' assigned to multiple agents",
+    );
+  });
+
+  test('throws when displayName conflicts with internal agent name', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: 'oracle' },
+      },
+    };
+
+    await expect(createAgents(config)).rejects.toThrow(
+      "displayName 'oracle' conflicts with an agent name",
+    );
+  });
+
+  test('throws when normalized displayName conflicts with internal agent name', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explorer: { displayName: ' @oracle ' },
+      },
+    };
+
+    await expect(createAgents(config)).rejects.toThrow(
+      "displayName 'oracle' conflicts with an agent name",
+    );
+  });
+
+  test('throws when orchestrator displayName conflicts with internal agent name', async () => {
+    const config: PluginConfig = {
+      agents: {
+        orchestrator: { displayName: 'oracle' },
+      },
+    };
+
+    await expect(createAgents(config)).rejects.toThrow(
+      /displayName.*conflicts with an agent name/,
+    );
+  });
+
+  test('resolves legacy alias for explorer displayName override', async () => {
+    const config: PluginConfig = {
+      agents: {
+        explore: { displayName: 'researcher' },
+      },
+    };
+
+    const agents = await createAgents(config);
+    const explorer = agents.find((a) => a.name === 'explorer');
+
+    expect(explorer?.displayName).toBe('researcher');
+  });
+
+  test('uses displayName as host-facing registry key with hidden internal alias', async () => {
+    const config: PluginConfig = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    };
+
+    const sdkConfigs = (await getAgentConfigs(config)) as Record<
+      string,
+      { hidden?: boolean; mode?: string }
+    >;
+
+    expect(sdkConfigs.advisor).toBeDefined();
+    expect(sdkConfigs.advisor.mode).toBe('subagent');
+    expect(sdkConfigs.advisor.hidden).toBeUndefined();
+
+    expect(sdkConfigs.oracle).toBeDefined();
+    expect(sdkConfigs.oracle.mode).toBe('subagent');
+    expect(sdkConfigs.oracle.hidden).toBe(true);
+  });
+
+  test('uses orchestrator displayName as host-facing key with hidden internal alias', async () => {
+    const config: PluginConfig = {
+      agents: {
+        orchestrator: { displayName: 'engineer' },
+      },
+    };
+
+    const sdkConfigs = (await getAgentConfigs(config)) as Record<
+      string,
+      { hidden?: boolean; mode?: string }
+    >;
+
+    expect(sdkConfigs.engineer).toBeDefined();
+    expect(sdkConfigs.engineer.mode).toBe('primary');
+    expect(sdkConfigs.engineer.hidden).toBeUndefined();
+
+    expect(sdkConfigs.orchestrator).toBeDefined();
+    expect(sdkConfigs.orchestrator.mode).toBe('primary');
+    expect(sdkConfigs.orchestrator.hidden).toBe(true);
+  });
+});

package/src/agents/explorer.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+import { createExplorerAgent } from './explorer';
+
+describe('createExplorerAgent', () => {
+  test('creates agent with correct name', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    expect(agent.name).toBe('explorer');
+  });
+
+  test('sets the provided model', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    expect(agent.config.model).toBe('test/explorer-model');
+  });
+
+  test('prompt contains expected sections', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('<role>');
+    expect(prompt).toContain('<tool_routing>');
+    expect(prompt).toContain('<workflow>');
+    expect(prompt).toContain('<constraints>');
+    expect(prompt).toContain('<user_choice_policy>');
+    expect(prompt).toContain('<output_format>');
+    expect(prompt).toContain('<variant_policy>');
+  });
+
+  test('custom prompt overrides the base prompt', () => {
+    const agent = createExplorerAgent(
+      'test/explorer-model',
+      'Custom explorer prompt',
+    );
+    expect(agent.config.prompt).toBe('Custom explorer prompt');
+  });
+
+  test('custom append prompt is appended to base', () => {
+    const agent = createExplorerAgent(
+      'test/explorer-model',
+      undefined,
+      'Extra instructions',
+    );
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('Extra instructions');
+    expect(prompt).toContain('<role>');
+  });
+
+  test('has description', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    expect(agent.description).toBeTruthy();
+    expect(agent.description?.length).toBeGreaterThan(10);
+  });
+
+  test('prompt contains all required sections (complete check)', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    const prompt = agent.config.prompt ?? '';
+    const requiredSections = [
+      '<role>',
+      '<tool_routing>',
+      '<workflow>',
+      '<big_repo_strategy>',
+      '<constraints>',
+      '<user_choice_policy>',
+      '<variant_policy>',
+      '<stale_codemap>',
+      '<output_format>',
+      '<results>',
+      '<no_results>',
+    ];
+    for (const section of requiredSections) {
+      expect(prompt).toContain(section);
+    }
+  });
+
+  test('prompt does not contain resolver boilerplate', () => {
+    const agent = createExplorerAgent('test/explorer-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).not.toContain('if (customPrompt)');
+    expect(prompt).not.toContain('else if (customAppendPrompt)');
+  });
+});