opencode-dux 1.0.0

package/src/agents/index.ts

@@ -0,0 +1,248 @@
+import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk/v2';
+import {
+  ALL_AGENT_NAMES,
+  DEFAULT_MODELS,
+  getAgentOverride,
+  loadAgentPrompt,
+  type PluginConfig,
+  SUBAGENT_NAMES,
+} from '../config';
+import { createDesignerAgent } from './designer';
+import { createExplorerAgent } from './explorer';
+import { createFixerAgent } from './fixer';
+import { createInterpreterAgent } from './interpreter';
+import { createLibrarianAgent } from './librarian';
+import { createOracleAgent } from './oracle';
+import { type AgentDefinition, createOrchestratorAgent } from './orchestrator';
+import { applyDefaultPermissions, applyOverrides } from './overrides';
+import { createStewardAgent } from './steward';
+
+export type { AgentDefinition } from './orchestrator';
+
+type AgentFactory = (
+  model: string,
+  customPrompt?: string,
+  customAppendPrompt?: string,
+) => AgentDefinition;
+
+function normalizeDisplayName(displayName: string): string {
+  const trimmed = displayName.trim();
+  return trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function injectDisplayNames(
+  orchestrator: AgentDefinition,
+  nameMap: Map<string, string>,
+): void {
+  if (nameMap.size === 0) return;
+  let prompt = orchestrator.config.prompt;
+  if (!prompt) return;
+
+  for (const [internalName, displayName] of nameMap) {
+    prompt = prompt.replace(
+      new RegExp(`@${escapeRegExp(internalName)}\\b`, 'g'),
+      `@${normalizeDisplayName(displayName)}`,
+    );
+  }
+
+  orchestrator.config.prompt = prompt;
+}
+
+// Agent Classification
+
+export type SubagentName = (typeof SUBAGENT_NAMES)[number];
+
+export function isSubagent(name: string): name is SubagentName {
+  return (SUBAGENT_NAMES as readonly string[]).includes(name);
+}
+
+// Agent Factories
+
+const SUBAGENT_FACTORIES = {
+  explorer: createExplorerAgent,
+  librarian: createLibrarianAgent,
+  oracle: createOracleAgent,
+  designer: createDesignerAgent,
+  fixer: createFixerAgent,
+  steward: createStewardAgent,
+  interpreter: createInterpreterAgent,
+} satisfies Record<SubagentName, AgentFactory>;
+
+// Public API
+
+/**
+ * Create all agent definitions with optional configuration overrides.
+ * Instantiates the orchestrator and all subagents, applying user config and defaults.
+ *
+ * @param config - Optional plugin configuration with agent overrides
+ * @returns Array of agent definitions (orchestrator first, then subagents)
+ */
+export async function createAgents(
+  config?: PluginConfig,
+): Promise<AgentDefinition[]> {
+  // 1. Gather all sub-agent definitions with custom prompts
+  const protoSubAgents = (
+    Object.entries(SUBAGENT_FACTORIES) as [SubagentName, AgentFactory][]
+  ).map(([name, factory]) => {
+    const customPrompts = loadAgentPrompt(name, config?.preset);
+    return factory(
+      DEFAULT_MODELS[name] as string,
+      customPrompts.prompt,
+      customPrompts.appendPrompt,
+    );
+  });
+
+  // 2. Apply overrides and default permissions to built-in subagents
+  const builtInSubAgents = await Promise.all(
+    protoSubAgents.map(async (agent) => {
+      const override = getAgentOverride(config, agent.name);
+      if (override) {
+        applyOverrides(agent, override);
+      }
+      // Pass both skills AND mcps from the override
+      await applyDefaultPermissions(agent, override?.skills, override?.mcps);
+      return agent;
+    }),
+  );
+
+  const allSubAgents = [...builtInSubAgents];
+
+  // 3. Create Orchestrator (with its own overrides and custom prompts)
+  // Model is resolved from DEFAULT_MODELS.orchestrator (or user override).
+  // TUI /model selector overrides at runtime regardless.
+  const orchestratorOverride = getAgentOverride(config, 'orchestrator');
+  const orchestratorModel =
+    orchestratorOverride?.model ?? DEFAULT_MODELS.orchestrator;
+  const orchestratorPrompts = loadAgentPrompt('orchestrator', config?.preset);
+
+  // 3a. Resolve oracle model names for prompt injection
+  // (avoids hardcoding model IDs in the prompt text)
+  const oracleOverride = getAgentOverride(config, 'oracle');
+  const oracleDefaultModel =
+    typeof oracleOverride?.model === 'string'
+      ? oracleOverride.model
+      : DEFAULT_MODELS.oracle;
+  const oracleOptions = oracleOverride?.options as
+    | Record<string, unknown>
+    | undefined;
+  const oracleSmartModel =
+    typeof oracleOptions?.smart === 'string' ? oracleOptions.smart : '';
+  const oracleSmartModelOrFallback =
+    oracleSmartModel.length > 0 ? oracleSmartModel : (oracleDefaultModel ?? '');
+
+  const orchestrator = createOrchestratorAgent(
+    orchestratorModel,
+    orchestratorPrompts.prompt,
+    orchestratorPrompts.appendPrompt,
+    oracleDefaultModel as string | undefined,
+    oracleSmartModelOrFallback,
+  );
+  if (orchestratorOverride) {
+    applyOverrides(orchestrator, orchestratorOverride);
+  }
+  await applyDefaultPermissions(
+    orchestrator,
+    orchestratorOverride?.skills,
+    orchestratorOverride?.mcps,
+  );
+
+  // Collect all display names from orchestrator and all subagents
+  const displayNameMap = new Map<string, string>();
+  if (orchestrator.displayName) {
+    displayNameMap.set('orchestrator', orchestrator.displayName);
+  }
+  for (const agent of allSubAgents) {
+    if (agent.displayName) {
+      displayNameMap.set(agent.name, agent.displayName);
+    }
+  }
+
+  // Validate display names
+  const usedDisplayNames = new Set<string>();
+  for (const [, displayName] of displayNameMap) {
+    const normalizedDisplayName = normalizeDisplayName(displayName);
+    if (usedDisplayNames.has(normalizedDisplayName)) {
+      throw new Error(
+        `Duplicate displayName '${normalizedDisplayName}' assigned to multiple agents`,
+      );
+    }
+    usedDisplayNames.add(normalizedDisplayName);
+  }
+  for (const displayName of usedDisplayNames) {
+    if ((ALL_AGENT_NAMES as readonly string[]).includes(displayName)) {
+      throw new Error(
+        `displayName '${displayName}' conflicts with an agent name`,
+      );
+    }
+  }
+
+  // Inject display names into orchestrator prompt (complete map)
+  injectDisplayNames(orchestrator, displayNameMap);
+
+  return [orchestrator, ...allSubAgents];
+}
+
+/**
+ * Get agent configurations formatted for the OpenCode SDK.
+ * Converts agent definitions to SDK config format and applies classification metadata.
+ *
+ * @param config - Optional plugin configuration with agent overrides
+ * @returns Record mapping agent names to their SDK configurations
+ */
+export async function getAgentConfigs(
+  config?: PluginConfig,
+): Promise<Record<string, SDKAgentConfig>> {
+  const agents = await createAgents(config);
+
+  const applyClassification = (
+    name: string,
+    sdkConfig: SDKAgentConfig & {
+      displayName?: string;
+      hidden?: boolean;
+    },
+  ): void => {
+    if (isSubagent(name)) {
+      sdkConfig.mode = 'subagent';
+    } else if (name === 'orchestrator') {
+      sdkConfig.mode = 'primary';
+    } else {
+      sdkConfig.mode = 'subagent';
+    }
+  };
+
+  const entries: Array<[string, SDKAgentConfig]> = [];
+
+  for (const a of agents) {
+    const sdkConfig: SDKAgentConfig & {
+      displayName?: string;
+      hidden?: boolean;
+    } = {
+      ...a.config,
+      description: a.description,
+    };
+
+    if (a.displayName) {
+      sdkConfig.displayName = a.displayName;
+    }
+
+    applyClassification(a.name, sdkConfig);
+
+    const normalizedDisplayName = a.displayName
+      ? normalizeDisplayName(a.displayName)
+      : undefined;
+
+    if (normalizedDisplayName) {
+      entries.push([normalizedDisplayName, sdkConfig]);
+      entries.push([a.name, { ...sdkConfig, hidden: true }]);
+      continue;
+    }
+
+    entries.push([a.name, sdkConfig]);
+  }
+
+  return Object.fromEntries(entries);
+}

package/src/agents/interpreter.ts

@@ -0,0 +1,136 @@
+import type { AgentDefinition } from './orchestrator';
+import { resolvePrompt } from './orchestrator';
+import {
+  formatBlockedOutputBlock,
+  INTERPRETER_VARIANT_SCOPE_LINES,
+  NEEDS_USER_OUTPUT_FORMAT_BLOCK,
+  REPO_RULES_PRECEDENCE_BLOCK,
+  SELF_REVIEW_BLOCK,
+  SUBAGENT_NEEDS_USER_FORMAT,
+  USER_CHOICE_POLICY_BLOCK,
+} from './prompt-blocks';
+
+const INTERPRETER_CRITICAL_INVARIANTS = `<critical_invariants>
+Violating any = failure mode.
+1) ALWAYS describe what IS visible - never skip reporting on partial/degraded images.
+2) NEVER assume UI redesign intent - neutral description first.
+3) NEVER substitute for @designer - describe pixels, not design opinions.
+4) NEVER modify files or delegate to subagents.
+</critical_invariants>`;
+
+const INTERPRETER_PROMPT = `<role>
+You are Interpreter, a visual-context specialist. Your job is to translate
+screenshots, diagrams, error captures, and UI images into structured,
+actionable intelligence. You describe WHAT is visible - never HOW to fix it
+(@fixer), never HOW to redesign it (@designer), never WHY it broke (@oracle).
+Your output is the foundation other agents build on.
+</role>
+
+${INTERPRETER_CRITICAL_INVARIANTS}
+
+${REPO_RULES_PRECEDENCE_BLOCK}
+
+<capabilities>
+- Describe visible layout, components, errors, and diagrams
+- Transcribe readable on-screen text, labels, and error codes
+- Infer likely user intent from visual context
+- Suggest routing for the orchestrator (@explorer / @oracle / @designer / @fixer)
+- Handle partially corrupted or blurred images with reduced confidence
+</capabilities>
+
+<tool_routing>
+- Vision-only specialist - no tool calls required in most sessions.
+- If host-injected context is insufficient AND image-reading tool available → use it.
+- NEVER use search/glob/read tools - belongs to @explorer.
+- If vision-capable tooling unavailable → report in <blocked>.
+</tool_routing>
+
+<workflow>
+1) Describe all visible elements: layout, components, error messages, diagrams.
+2) Transcribe readable text (labels, error codes, stack traces, form values).
+3) Infer the user's most likely intent from the visual context.
+4) Suggest the appropriate next agent(s) with one-line rationale each.
+5) Rate your confidence and note any regions that were unreadable or ambiguous.
+</workflow>
+
+${USER_CHOICE_POLICY_BLOCK}
+
+<constraints>
+- Default analysis-only; code changes belong in @fixer. Never patch files yourself — invariant #4 prohibits it regardless of orchestrator instruction.
+- NEVER assume UI redesign unless the user asked for design polish; neutral description first.
+- Separate confirmed visually vs inferred claims.
+- Host-injected "does not support image input" → vision-incapable model. Report that; do not claim "no image attached."
+- Partial/corrupted images: describe what IS visible, label unreadable regions, lower <confidence>. NEVER skip reporting.
+</constraints>
+
+<variant_policy>
+${INTERPRETER_VARIANT_SCOPE_LINES.map((l) => `- ${l}`).join('\n')}
+- max: not supported - interpreter provides context that the orchestrator then routes to @oracle for in-depth analysis. The expected flow is @interpreter first (describe), then @oracle (analyze).
+</variant_policy>
+
+${SUBAGENT_NEEDS_USER_FORMAT}
+
+${SELF_REVIEW_BLOCK}
+
+<output_format>
+<visible>
+What the image shows (layout, components, errors, diagrams).
+</visible>
+<text_detected>
+Bullets of readable strings (approximate if partially blurred).
+</text_detected>
+<intent>
+Likely user goal in one short paragraph.
+</intent>
+<routing_hint>
+Suggested next agent(s) with one-line rationale each.
+</routing_hint>
+<confidence>
+[high/medium/low] and why.
+</confidence>
+${formatBlockedOutputBlock('image analysis cannot be completed due to missing image data or tools')}
+${NEEDS_USER_OUTPUT_FORMAT_BLOCK}
+
+<good_example>
+<needs_user>
+<reason>Screenshot shows both form UI and API response-unclear if task is frontend or backend.</reason>
+<questions>[{"question": "What is the primary focus of this task?", "header": "Task focus", "options": [{"label": "Frontend form", "description": "Build/redesign the UI form shown-route to @designer then @fixer"}, {"label": "Backend API", "description": "Implement/fix the API endpoint returning this data-route to @fixer"}]}]</questions>
+</needs_user>
+</good_example>
+
+<good_example>
+User: [screenshot of error]
+Interpreter: Describes visible layout, transcribes error code "500 Internal Server Error",
+infers intent (debugging), suggests @oracle for root cause analysis.
+Returns: <visible> + <text_detected> + <intent> + <routing_hint> + <confidence: high>.
+</good_example>
+
+<bad_example>
+User: [screenshot of error]
+Interpreter: Claims "no image attached" when model is vision-incapable.
+Missing: explicit "vision-incapable model" report.
+</bad_example>
+</output_format>`;
+
+export function createInterpreterAgent(
+  model: string,
+  customPrompt?: string,
+  customAppendPrompt?: string,
+): AgentDefinition {
+  const prompt = resolvePrompt(
+    INTERPRETER_PROMPT,
+    customPrompt,
+    customAppendPrompt,
+  );
+
+  return {
+    name: 'interpreter',
+    description:
+      'Screenshot and image understanding (errors, diagrams, repro captures). Routes context to other specialists; not a substitute for @designer UX reviews.',
+    config: {
+      model,
+      temperature: 0.15,
+      prompt,
+    },
+  };
+}

package/src/agents/librarian.test.ts

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

package/src/agents/librarian.ts

@@ -0,0 +1,145 @@
+import type { AgentDefinition } from './orchestrator';
+import { resolvePrompt } from './orchestrator';
+import {
+  formatBlockedOutputBlock,
+  LIBRARIAN_VARIANT_SCOPE_LINES,
+  NEEDS_USER_OUTPUT_FORMAT_BLOCK,
+  REPO_RULES_PRECEDENCE_BLOCK,
+  SELF_REVIEW_BLOCK,
+  SUBAGENT_NEEDS_USER_FORMAT,
+  USER_CHOICE_POLICY_BLOCK,
+} from './prompt-blocks';
+
+const LIBRARIAN_CRITICAL_INVARIANTS = `<critical_invariants>
+Violating any = failure mode.
+1) NEVER guess APIs - cite sources only.
+2) GitHub URLs → github MCP only, no substitutions.
+3) ALWAYS label versions when sources span multiple releases.
+4) NEVER modify files or delegate to subagents.
+</critical_invariants>`;
+
+const LIBRARIAN_PROMPT = `<role>
+You are Librarian, a documentation and external research specialist.
+</role>
+
+${LIBRARIAN_CRITICAL_INVARIANTS}
+
+${REPO_RULES_PRECEDENCE_BLOCK}
+
+<capabilities>
+- External API and library documentation lookup
+- Version-specific behavior and changelog analysis
+- Official examples and best practices from authoritative sources
+- GitHub repository exploration (issues, PRs, releases)
+- Conflict resolution across multiple documentation sources
+</capabilities>
+
+<workflow>
+1) GitHub first: requests with a GitHub URL or explicit repo target → github MCP immediately (all asset types-not only issues/PRs/releases).
+2) Gather official sources in this priority order:
+   a) GitHub repository (issues, PRs, releases, source code)
+   b) Context7 library documentation
+   c) Implementation examples from GitHub search
+   d) Websearch for recent blog posts or announcements (if version recency matters)
+3) Corroborate with implementation examples when helpful.
+4) Add websearch-driven recency when step 1 does not apply and freshness matters.
+5) Report concise findings with citations naming the tool actually used when non-obvious.
+</workflow>
+
+${USER_CHOICE_POLICY_BLOCK}
+
+<constraints>
+- NEVER guess APIs or version behavior.
+- NEVER omit source citations.
+- NEVER mix versions without explicitly labeling them.
+- NEVER treat forum chatter as canonical when official docs or repository metadata exists.
+- NEVER modify files or delegate.
+- GitHub URLs → github MCP only. If github MCP fails → <blocked> with URL + error. NEVER substitute webfetch/websearch for GitHub-hosted content.
+- If github, context7, or websearch tools are missing from your callable tools, include that in \`<blocked>\` with what would be needed-do not compensate with guesses.
+- Stay evidence-focused.
+</constraints>
+
+<tool_and_mcp_routing>
+| Need | Tool/MCP | Usage |
+|---|---|---|
+| any GitHub URL, repository content, or GitHub-hosted resource | github | ALWAYS use GitHub MCP first for ANY GitHub URL (before websearch/other fetch tools) |
+| official API behavior and version details | context7 | First choice for library docs when URL is not the primary source |
+| real-world code examples from repos | github | Implementation patterns from repository source |
+| recent ecosystem changes or release notes | websearch MCP | When no GitHub URL applies; use the configured websearch tools |
+| upstream GitHub issues, PRs, and release metadata | github | Repository-native source of truth |
+| arbitrary non-GitHub web URL | websearch MCP or webfetch | General web content; never substitute for github MCP on GitHub URLs |
+</tool_and_mcp_routing>
+
+<conflict_resolution>
+- When sources disagree, prefer (in order): official changelog/release notes → official docs → repository source code → high-signal blog/forum posts.
+- Always label the version each source pertains to.
+- If sources span multiple major versions, report each version's behavior separately rather than averaging.
+- If context7 returns nothing, fall back to GitHub repository source and tools from the websearch MCP - never invent.
+- Competing libraries/versions when user did not specify → <needs_user>. Each option \`description\` must cover tradeoffs from docs (maintenance, bundle size, API style, ecosystem fit).
+- NEVER crown a winner when the choice depends on user preference or constraints unknown to you.
+</conflict_resolution>
+
+<variant_policy>
+${LIBRARIAN_VARIANT_SCOPE_LINES.map((l) => `- ${l}`).join('\n')}
+</variant_policy>
+
+${SUBAGENT_NEEDS_USER_FORMAT}
+
+${SELF_REVIEW_BLOCK}
+
+<output_format>
+<answer>
+Short, evidence-based recommendation.
+</answer>
+<sources>
+- <source>official-doc-url-or-id</source>
+- <source>repo-url-or-path</source>
+</sources>
+<notes>
+- version caveats or uncertainty, if any
+</notes>
+${formatBlockedOutputBlock('no sources could be found or the query requires unavailable APIs')}
+${NEEDS_USER_OUTPUT_FORMAT_BLOCK}
+
+<good_example>
+<needs_user>
+<reason>Library has multiple major versions with breaking changes.</reason>
+<questions>[{"question": "Which version should I reference for this API?", "header": "Library version", "options": [{"label": "v14.x (stable)", "description": "Current LTS, most docs and examples target this"}, {"label": "v15.x (canary)", "description": "Latest features, may have breaking changes, fewer examples"}]}]</questions>
+</needs_user>
+</good_example>
+
+<good_example>
+User: "How to use Context7 MCP for Next.js docs?"
+Librarian: Queries context7, cross-references GitHub repo, cites v14.2.3 docs.
+Returns: <answer> with versioned recommendation + <sources> with URLs.
+</good_example>
+
+<bad_example>
+User: "How to use Context7 MCP for Next.js docs?"
+Librarian: Returns generic Next.js advice without version labels or source URLs.
+Missing: version context, source URLs, conflict resolution.
+</bad_example>
+</output_format>`;
+
+export function createLibrarianAgent(
+  model: string,
+  customPrompt?: string,
+  customAppendPrompt?: string,
+): AgentDefinition {
+  const prompt = resolvePrompt(
+    LIBRARIAN_PROMPT,
+    customPrompt,
+    customAppendPrompt,
+  );
+
+  return {
+    name: 'librarian',
+    description:
+      'External documentation and library research. Use for official docs lookup, GitHub examples, and understanding library internals.',
+    config: {
+      model,
+      temperature: 0.1,
+      prompt,
+    },
+  };
+}

package/src/agents/oracle.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+import { createOracleAgent } from './oracle';
+
+describe('createOracleAgent', () => {
+  test('creates agent with correct name', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    expect(agent.name).toBe('oracle');
+  });
+
+  test('sets the provided model', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    expect(agent.config.model).toBe('test/oracle-model');
+  });
+
+  test('prompt contains expected sections', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('<role>');
+    expect(prompt).toContain('<capabilities>');
+    expect(prompt).toContain('<tool_routing>');
+    expect(prompt).toContain('<constraints>');
+    expect(prompt).toContain('<user_choice_policy>');
+    expect(prompt).toContain('<variant_policy>');
+    expect(prompt).toContain('<output_format>');
+  });
+
+  test('has temperature 0.15', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    expect(agent.config.temperature).toBe(0.15);
+  });
+
+  test('custom prompt overrides the base prompt', () => {
+    const agent = createOracleAgent(
+      'test/oracle-model',
+      'Custom oracle prompt',
+    );
+    expect(agent.config.prompt).toBe('Custom oracle prompt');
+  });
+
+  test('custom append prompt is appended to base', () => {
+    const agent = createOracleAgent(
+      'test/oracle-model',
+      undefined,
+      'Extra instructions',
+    );
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).toContain('Extra instructions');
+    expect(prompt).toContain('<role>');
+  });
+
+  test('has description', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    expect(agent.description).toBeTruthy();
+    expect(agent.description?.length).toBeGreaterThan(10);
+  });
+
+  test('prompt contains all required sections (complete check)', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    const prompt = agent.config.prompt ?? '';
+    const requiredSections = [
+      '<role>',
+      '<capabilities>',
+      '<tool_routing>',
+      '<constraints>',
+      '<user_choice_policy>',
+      '<variant_policy>',
+      '<output_format>',
+      '<diagnosis>',
+      '<recommendation>',
+      '<tradeoffs>',
+      '<risks>',
+      '<confidence>',
+      '<action_items>',
+      '<blocked>',
+      '<good_example>',
+      '<bad_example>',
+    ];
+    for (const section of requiredSections) {
+      expect(prompt).toContain(section);
+    }
+  });
+
+  test('prompt does not contain resolver boilerplate', () => {
+    const agent = createOracleAgent('test/oracle-model');
+    const prompt = agent.config.prompt ?? '';
+    expect(prompt).not.toContain('if (customPrompt)');
+    expect(prompt).not.toContain('else if (customAppendPrompt)');
+  });
+});