karajan-code 1.59.0 → 2.0.0

package/src/roles/hu-reviewer-role.js

@@ -1,112 +1,64 @@
-import { BaseRole } from "./base-role.js";
-import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { AgentRole } from "./agent-role.js";
 import { buildHuReviewerPrompt, parseHuReviewerOutput } from "../prompts/hu-reviewer.js";
 
-/**
- * Resolve the provider for the hu-reviewer role, falling back to coder.
- * @param {object} config
- * @returns {string}
- */
-function resolveProvider(config) {
-  return (
-    config?.roles?.["hu-reviewer"]?.provider ||
-    config?.roles?.hu_reviewer?.provider ||
-    config?.roles?.coder?.provider ||
-    "claude"
-  );
-}
+const EMPTY_BATCH = { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" };
 
-/**
- * Build a human-readable summary from parsed evaluations.
- * @param {object} parsed - Parsed HU reviewer output.
- * @returns {string}
- */
-function buildSummary(parsed) {
-  const { batch_summary: bs } = parsed;
-  const parts = [`${bs.total} HU(s) evaluated`];
-  if (bs.certified > 0) parts.push(`${bs.certified} certified`);
-  if (bs.needs_rewrite > 0) parts.push(`${bs.needs_rewrite} need rewrite`);
-  if (bs.needs_context > 0) parts.push(`${bs.needs_context} need context`);
-  return `HU Review complete: ${parts.join(", ")}`;
-}
+export class HuReviewerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "hu-reviewer" });
+  }
 
-export class HuReviewerRole extends BaseRole {
-  /**
-   * @param {{config: object, logger: object, emitter?: object|null, createAgentFn?: Function|null}} params
-   */
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
-    super({ name: "hu-reviewer", config, logger, emitter });
-    this._createAgent = createAgentFn || defaultCreateAgent;
+  resolveProvider() {
+    return (
+      this.config?.roles?.["hu-reviewer"]?.provider ||
+      this.config?.roles?.hu_reviewer?.provider ||
+      this.config?.roles?.coder?.provider ||
+      "claude"
+    );
   }
 
-  /**
-   * Execute the HU review.
-   * @param {{stories: Array<{id: string, text: string}>, context?: string|null, onOutput?: Function|null}} input
-   * @returns {Promise<{ok: boolean, result: object, summary: string, usage?: object}>}
-   */
-  async execute(input) {
-    const stories = input?.stories || [];
-    const context = input?.context || null;
-    const onOutput = input?.onOutput || null;
+  extractInput(input) {
+    return {
+      stories: input?.stories || [],
+      context: input?.context || null,
+      onOutput: input?.onOutput || null
+    };
+  }
 
-    const provider = resolveProvider(this.config);
-    const agent = this._createAgent(provider, this.config, this.logger);
+  async buildPrompt({ stories, context }) {
+    const prompt = buildHuReviewerPrompt({
+      stories, instructions: this.instructions, context,
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null
+    });
+    return { prompt };
+  }
 
-    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context, productContext: this.config?.productContext || null, domainContext: this.config?.domainContext || null });
-    const runArgs = { prompt, role: "hu-reviewer" };
-    if (onOutput) runArgs.onOutput = onOutput;
-    const result = await agent.runTask(runArgs);
+  parseOutput(raw) { return parseHuReviewerOutput(raw); }
 
-    if (!result.ok) {
-      return {
-        ok: false,
-        result: {
-          error: result.error || result.output || "HU Review failed",
-          provider
-        },
-        summary: `HU Review failed: ${result.error || "unknown error"}`,
-        usage: result.usage
-      };
-    }
+  buildSuccessResult(parsed, provider) {
+    return { evaluations: parsed.evaluations, batch_summary: parsed.batch_summary, provider };
+  }
+
+  buildSummary(parsed) {
+    const bs = parsed.batch_summary;
+    const parts = [`${bs.total} HU(s) evaluated`];
+    if (bs.certified > 0) parts.push(`${bs.certified} certified`);
+    if (bs.needs_rewrite > 0) parts.push(`${bs.needs_rewrite} need rewrite`);
+    if (bs.needs_context > 0) parts.push(`${bs.needs_context} need context`);
+    return `HU Review complete: ${parts.join(", ")}`;
+  }
 
-    try {
-      const parsed = parseHuReviewerOutput(result.output);
-      if (!parsed) {
-        return {
-          ok: true,
-          result: {
-            evaluations: [],
-            batch_summary: { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" },
-            raw: result.output,
-            provider
-          },
-          summary: "HU Review complete (unstructured output)",
-          usage: result.usage
-        };
-      }
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { evaluations: [], batch_summary: { ...EMPTY_BATCH }, raw: agentResult.output, provider },
+      summary: "HU Review complete (unstructured output)",
+      usage: agentResult.usage
+    };
+  }
 
-      return {
-        ok: true,
-        result: {
-          evaluations: parsed.evaluations,
-          batch_summary: parsed.batch_summary,
-          provider
-        },
-        summary: buildSummary(parsed),
-        usage: result.usage
-      };
-    } catch { /* agent output is not structured JSON */
-      return {
-        ok: true,
-        result: {
-          evaluations: [],
-          batch_summary: { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" },
-          raw: result.output,
-          provider
-        },
-        summary: "HU Review complete (unstructured output)",
-        usage: result.usage
-      };
-    }
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
   }
 }

package/src/roles/impeccable-role.js

@@ -1,6 +1,6 @@
-import { BaseRole } from "./base-role.js";
-import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { AgentRole } from "./agent-role.js";
 import { isDevToolsMcpAvailable, ensureWebPerfSkills } from "../webperf/devtools-detect.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -8,135 +8,78 @@ const SUBAGENT_PREAMBLE = [
   "Do NOT use any MCP tools. Focus only on auditing frontend/UI code for design quality."
 ].join(" ");
 
-function resolveProvider(config) {
-  return (
-    config?.roles?.impeccable?.provider ||
-    config?.roles?.coder?.provider ||
-    "claude"
-  );
-}
-
-function buildPrompt({ task, diff, instructions }) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  if (instructions) {
-    sections.push(instructions);
-  }
-
-  sections.push(
-    `## Task\n${task}`
-  );
-
-  if (diff) {
-    sections.push(`## Git diff to audit\n${diff}`);
-  }
-
-  return sections.join("\n\n");
-}
-
-function parseImpeccableOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
-}
-
 function buildSummary(parsed) {
   const verdict = parsed.verdict || "APPROVED";
   const found = parsed.issuesFound || 0;
   const fixed = parsed.issuesFixed || 0;
-
-  if (verdict === "APPROVED" || found === 0) {
-    return `Verdict: APPROVED; No frontend design issues found`;
-  }
+  if (verdict === "APPROVED" || found === 0) return "Verdict: APPROVED; No frontend design issues found";
 
   const cats = parsed.categories || {};
-  const parts = Object.entries(cats)
-    .filter(([, count]) => count > 0)
-    .map(([cat, count]) => `${count} ${cat}`);
-
+  const parts = Object.entries(cats).filter(([, count]) => count > 0).map(([cat, count]) => `${count} ${cat}`);
   return `Verdict: ${verdict}; ${found} issue(s) found, ${fixed} fixed (${parts.join(", ")})`;
 }
 
-export class ImpeccableRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null, mode = "audit" }) {
+export class ImpeccableRole extends AgentRole {
+  constructor(opts) {
+    const mode = opts.mode || "audit";
     const roleName = mode === "refactoring" ? "impeccable-design" : "impeccable";
-    super({ name: roleName, config, logger, emitter });
-    this._createAgent = createAgentFn || defaultCreateAgent;
+    super({ ...opts, name: roleName });
     this.mode = mode;
   }
 
+  resolveProvider() {
+    return this.config?.roles?.impeccable?.provider || this.config?.roles?.coder?.provider || "claude";
+  }
+
   async execute(input) {
-    const { task, diff, projectDir } = typeof input === "string"
-      ? { task: input, diff: null, projectDir: null }
-      : { task: input?.task || this.context?.task || "", diff: input?.diff || null, projectDir: input?.projectDir || null };
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const diff = typeof input === "object" ? input?.diff || null : null;
+    const projectDir = typeof input === "object" ? input?.projectDir || null : null;
 
     // Auto-install WebPerf skills when DevTools MCP is configured
     if (isDevToolsMcpAvailable(this.config)) {
       const dir = projectDir || process.cwd();
       try {
         const webperfResult = await ensureWebPerfSkills(dir, this.logger);
-        if (webperfResult.installed.length > 0) {
-          this.logger?.info?.(`WebPerf skills installed: ${webperfResult.installed.join(", ")}`);
-        }
+        if (webperfResult.installed.length > 0) this.logger?.info?.(`WebPerf skills installed: ${webperfResult.installed.join(", ")}`);
       } catch (err) {
         this.logger?.warn?.(`WebPerf skill installation failed: ${err.message}`);
       }
     } else {
-      this.logger?.info?.("Chrome DevTools MCP not configured — skipping WebPerf skills");
+      this.logger?.debug?.("Chrome DevTools MCP not configured — WebPerf skills skipped");
     }
 
-    const provider = resolveProvider(this.config);
-    const agent = this._createAgent(provider, this.config, this.logger);
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+    sections.push(`## Task\n${task}`);
+    if (diff) sections.push(`## Git diff to audit\n${diff}`);
+    if (isDevToolsMcpAvailable(this.config)) {
+      sections.push("\nNote: WebPerf domain skills are available. Use them for Core Web Vitals analysis if the audit involves frontend performance.");
+    }
 
-    const webperfNote = isDevToolsMcpAvailable(this.config)
-      ? "\n\nNote: WebPerf domain skills are available. Use them for Core Web Vitals analysis if the audit involves frontend performance."
-      : "";
-    const prompt = buildPrompt({ task, diff, instructions: this.instructions }) + webperfNote;
-    const result = await agent.runTask({ prompt, role: "impeccable" });
+    const result = await agent.runTask({ prompt: sections.join("\n\n"), role: "impeccable" });
 
     if (!result.ok) {
-      return {
-        ok: false,
-        result: {
-          error: result.error || result.output || "Impeccable audit failed",
-          provider
-        },
-        summary: `Impeccable audit failed: ${result.error || "unknown error"}`
-      };
+      return { ok: false, result: { error: result.error || result.output || "Impeccable audit failed", provider }, summary: `Impeccable audit failed: ${result.error || "unknown error"}` };
     }
 
     try {
-      const parsed = parseImpeccableOutput(result.output);
+      const parsed = extractFirstJson(result.output);
       if (!parsed) {
-        return {
-          ok: false,
-          result: { error: "Failed to parse impeccable output: no JSON found", provider },
-          summary: "Impeccable output parse error: no JSON found"
-        };
+        return { ok: false, result: { error: "Failed to parse impeccable output: no JSON found", provider }, summary: "Impeccable output parse error: no JSON found" };
       }
 
       const verdict = parsed.verdict || (parsed.issuesFound > 0 ? "IMPROVED" : "APPROVED");
-      const ok = verdict === "APPROVED" || verdict === "IMPROVED";
-
       return {
-        ok,
-        result: {
-          verdict,
-          issuesFound: parsed.issuesFound || 0,
-          issuesFixed: parsed.issuesFixed || 0,
-          categories: parsed.categories || {},
-          changes: parsed.changes || [],
-          provider
-        },
+        ok: verdict === "APPROVED" || verdict === "IMPROVED",
+        result: { verdict, issuesFound: parsed.issuesFound || 0, issuesFixed: parsed.issuesFixed || 0, categories: parsed.categories || {}, changes: parsed.changes || [], provider },
         summary: buildSummary({ ...parsed, verdict })
       };
     } catch (err) {
-      return {
-        ok: false,
-        result: { error: `Failed to parse impeccable output: ${err.message}`, provider },
-        summary: `Impeccable output parse error: ${err.message}`
-      };
+      return { ok: false, result: { error: `Failed to parse impeccable output: ${err.message}`, provider }, summary: `Impeccable output parse error: ${err.message}` };
     }
   }
 }

package/src/roles/index.js

@@ -1,4 +1,5 @@
 export { BaseRole, ROLE_EVENTS, resolveRoleMdPath, loadFirstExisting } from "./base-role.js";
+export { AgentRole } from "./agent-role.js";
 export { PlannerRole } from "./planner-role.js";
 export { ReviewerRole } from "./reviewer-role.js";
 export { RefactorerRole } from "./refactorer-role.js";
@@ -14,3 +15,4 @@ export { DiscoverRole } from "./discover-role.js";
 export { ArchitectRole } from "./architect-role.js";
 export { AuditRole } from "./audit-role.js";
 export { HuReviewerRole } from "./hu-reviewer-role.js";
+export { KarajanBrainRole } from "./karajan-brain-role.js";

package/src/roles/karajan-brain-role.js

@@ -0,0 +1,134 @@
+import { AgentRole } from "./agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const BRAIN_PREAMBLE = [
+  "You are Karajan Brain, the central orchestrator of a multi-agent AI coding pipeline.",
+  "You receive the output of a role that just completed and decide what happens next.",
+  "Your decisions MUST be intelligent, context-aware, and token-efficient.",
+  "Do NOT execute the task yourself — you route, enrich, and control the flow."
+].join(" ");
+
+/**
+ * KarajanBrainRole — AI-powered central orchestrator.
+ * Receives role outputs and decides: next role, enriched prompt, direct actions.
+ * Only consults Solomon when facing a genuine dilemma.
+ */
+export class KarajanBrainRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "karajan-brain" });
+  }
+
+  resolveProvider() {
+    return (
+      this.config?.roles?.["karajan-brain"]?.provider ||
+      this.config?.brain?.provider ||
+      this.config?.roles?.coder?.provider ||
+      "claude"
+    );
+  }
+
+  extractInput(input) {
+    return {
+      currentRole: input?.currentRole || null,
+      roleOutput: input?.roleOutput || null,
+      pipelineState: input?.pipelineState || {},
+      availableRoles: input?.availableRoles || [],
+      task: input?.task || this.context?.task || "",
+      onOutput: input?.onOutput || null
+    };
+  }
+
+  async buildPrompt({ currentRole, roleOutput, pipelineState, availableRoles, task }) {
+    const sections = [BRAIN_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+
+    sections.push(
+      "## Current pipeline state",
+      `Task: ${task}`,
+      `Last role executed: ${currentRole || "none"}`,
+      `Available roles: ${availableRoles.join(", ") || "coder, reviewer, tester, security"}`,
+      `Iteration: ${pipelineState.iteration || 0}/${pipelineState.maxIterations || 5}`
+    );
+
+    if (pipelineState.filesChanged != null) {
+      sections.push(`Files changed so far: ${pipelineState.filesChanged}`);
+    }
+    if (pipelineState.budget) {
+      sections.push(`Budget used: $${pipelineState.budget.cost_usd?.toFixed(2) || 0}`);
+    }
+
+    if (roleOutput) {
+      const outputStr = typeof roleOutput === "string" ? roleOutput : JSON.stringify(roleOutput, null, 2);
+      const truncated = outputStr.length > 3000 ? outputStr.slice(0, 3000) + "...[truncated]" : outputStr;
+      sections.push(`## Output from ${currentRole}`, truncated);
+    }
+
+    sections.push(
+      "## Your decision",
+      "Return a single JSON object with your routing decision:",
+      "```json",
+      "{",
+      '  "nextRole": "coder|reviewer|tester|security|solomon|done",',
+      '  "enrichedPrompt": "string with specific instructions for the next role, or null to use default",',
+      '  "directActions": [{"type": "run_command|create_file|update_gitignore", "params": {}}],',
+      '  "reasoning": "why this decision",',
+      '  "consultSolomon": false,',
+      '  "dilemma": null',
+      "}",
+      "```",
+      "",
+      "Guidelines:",
+      "- If coder produced 0 file changes and there's reviewer feedback: enrich the prompt with concrete file paths and resend to coder",
+      "- If tests are failing but node_modules missing: directAction to run npm install",
+      '- If you cannot decide or face a genuine dilemma (security vs deadline, conflicting gates): set consultSolomon=true and describe the dilemma',
+      "- If the pipeline should end (approved, max iterations, unrecoverable): set nextRole=done"
+    );
+
+    return { prompt: sections.join("\n\n") };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    return {
+      nextRole: parsed.nextRole || "coder",
+      enrichedPrompt: parsed.enrichedPrompt || null,
+      directActions: Array.isArray(parsed.directActions) ? parsed.directActions : [],
+      reasoning: parsed.reasoning || "",
+      consultSolomon: Boolean(parsed.consultSolomon),
+      dilemma: parsed.dilemma || null,
+      provider
+    };
+  }
+
+  buildSummary(parsed) {
+    const next = parsed.nextRole || "unknown";
+    const actions = Array.isArray(parsed.directActions) ? parsed.directActions.length : 0;
+    const solomon = parsed.consultSolomon ? " (consulting Solomon)" : "";
+    return `Brain: next=${next}, ${actions} direct action(s)${solomon}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    // Fallback: continue with default flow
+    return {
+      ok: true,
+      result: {
+        nextRole: "coder",
+        enrichedPrompt: null,
+        directActions: [],
+        reasoning: "Unstructured output — falling back to default flow",
+        consultSolomon: false,
+        dilemma: null,
+        provider
+      },
+      summary: "Brain: fallback to default flow (unstructured output)",
+      usage: agentResult.usage
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}

package/src/roles/planner-role.js

@@ -1,34 +1,4 @@
-import { BaseRole } from "./base-role.js";
-import { createAgent as defaultCreateAgent } from "../agents/index.js";
-
-function resolveProvider(config) {
-  return (
-    config?.roles?.planner?.provider ||
-    config?.roles?.coder?.provider ||
-    "claude"
-  );
-}
-
-function resolvePlannerSilenceTimeoutMs(config) {
-  const minutes = Number(config?.session?.max_agent_silence_minutes);
-  if (!Number.isFinite(minutes) || minutes <= 0) return null;
-  return Math.round(minutes * 60 * 1000);
-}
-
-function resolvePlannerRuntimeTimeoutMs(config) {
-  const minutes = Number(config?.session?.max_planner_minutes);
-  if (!Number.isFinite(minutes) || minutes <= 0) return null;
-  return Math.round(minutes * 60 * 1000);
-}
-
-function appendDecompositionSection(sections, triageDecomposition) {
-  if (!triageDecomposition?.length) return;
-  sections.push("## Triage decomposition recommendation", "The triage stage determined this task should be decomposed. Suggested subtasks:");
-  for (let i = 0; i < triageDecomposition.length; i++) {
-    sections.push(`${i + 1}. ${triageDecomposition[i]}`);
-  }
-  sections.push("", "Focus your plan on the FIRST subtask only. List the remaining subtasks as 'pending_subtasks' in your output for documentation.", "");
-}
+import { AgentRole } from "./agent-role.js";
 
 const RESEARCH_FIELDS = [
   { key: "affected_files", label: "Affected files" },
@@ -38,13 +8,18 @@ const RESEARCH_FIELDS = [
   { key: "prior_decisions", label: "Prior decisions" }
 ];
 
+function appendDecompositionSection(sections, triageDecomposition) {
+  if (!triageDecomposition?.length) return;
+  sections.push("## Triage decomposition recommendation", "The triage stage determined this task should be decomposed. Suggested subtasks:");
+  for (let i = 0; i < triageDecomposition.length; i++) sections.push(`${i + 1}. ${triageDecomposition[i]}`);
+  sections.push("", "Focus your plan on the FIRST subtask only. List the remaining subtasks as 'pending_subtasks' in your output for documentation.", "");
+}
+
 function appendResearchSection(sections, research) {
   if (!research) return;
   sections.push("## Research findings");
   for (const { key, label } of RESEARCH_FIELDS) {
-    if (research[key]?.length) {
-      sections.push(`${label}: ${research[key].join(", ")}`);
-    }
+    if (research[key]?.length) sections.push(`${label}: ${research[key].join(", ")}`);
   }
   sections.push("");
 }
@@ -63,61 +38,51 @@ function appendArchitectSection(sections, architectContext) {
   sections.push("");
 }
 
-function buildPrompt({ task, instructions, research, triageDecomposition, architectContext, productContext = null, domainContext = null }) {
-  const sections = [];
-
-  if (instructions) {
-    sections.push(instructions, "");
-  }
-
-  sections.push(
-    "Create an implementation plan for this task.",
-    "Return concise numbered steps focused on execution order and risk.",
-    ""
-  );
-
-  if (productContext) {
-    sections.push("## Product Context", productContext, "");
-  }
-
-  if (domainContext) {
-    sections.push("## Domain Context", domainContext, "");
-  }
-
-  appendDecompositionSection(sections, triageDecomposition);
-  appendArchitectSection(sections, architectContext);
-  appendResearchSection(sections, research);
-
-  sections.push("## Task", task);
+function resolveSilenceTimeoutMs(config) {
+  const minutes = Number(config?.session?.max_agent_silence_minutes);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
+}
 
-  return sections.join("\n");
+function resolveRuntimeTimeoutMs(config) {
+  const minutes = Number(config?.session?.max_planner_minutes);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
 }
 
-export class PlannerRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
-    super({ name: "planner", config, logger, emitter });
-    this._createAgent = createAgentFn || defaultCreateAgent;
+export class PlannerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "planner" });
   }
 
   async execute(input) {
-    const { task, onOutput } = typeof input === "string"
+    const { task: rawTask, onOutput } = typeof input === "string"
       ? { task: input, onOutput: null }
       : { task: input?.task || input || "", onOutput: input?.onOutput || null };
-    const taskStr = task || this.context?.task || "";
+
+    const task = rawTask || this.context?.task || "";
     const research = this.context?.research || null;
     const triageDecomposition = this.context?.triageDecomposition || null;
     const architectContext = this.context?.architecture || null;
-    const provider = resolveProvider(this.config);
-
-    const agent = this._createAgent(provider, this.config, this.logger);
-    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition, architectContext, productContext: this.config?.productContext || null, domainContext: this.config?.domainContext || null });
 
-    const runArgs = { prompt, role: "planner" };
+    const sections = [];
+    if (this.instructions) sections.push(this.instructions, "");
+    sections.push("Create an implementation plan for this task.", "Return concise numbered steps focused on execution order and risk.", "");
+    if (this.config?.productContext) sections.push("## Product Context", this.config.productContext, "");
+    if (this.config?.domainContext) sections.push("## Domain Context", this.config.domainContext, "");
+    appendDecompositionSection(sections, triageDecomposition);
+    appendArchitectSection(sections, architectContext);
+    appendResearchSection(sections, research);
+    sections.push("## Task", task);
+
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+    const runArgs = { prompt: sections.join("\n"), role: "planner" };
     if (onOutput) runArgs.onOutput = onOutput;
-    const silenceTimeoutMs = resolvePlannerSilenceTimeoutMs(this.config);
-    if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
-    const timeoutMs = resolvePlannerRuntimeTimeoutMs(this.config);
+
+    const silenceMs = resolveSilenceTimeoutMs(this.config);
+    if (silenceMs) runArgs.silenceTimeoutMs = silenceMs;
+    const timeoutMs = resolveRuntimeTimeoutMs(this.config);
     if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+
     const result = await agent.runTask(runArgs);
 
     if (!result.ok) {