@karajan-family/code 4.21.0

package/src/roles/impeccable-role.js

@@ -0,0 +1,85 @@
+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.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on auditing frontend/UI code for design quality."
+].join(" ");
+
+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";
+
+  const cats = parsed.categories || {};
+  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 AgentRole {
+  constructor(opts) {
+    const mode = opts.mode || "audit";
+    const roleName = mode === "refactoring" ? "impeccable-design" : "impeccable";
+    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 = 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(", ")}`);
+      } catch (err) {
+        this.logger?.warn?.(`WebPerf skill installation failed: ${err.message}`);
+      }
+    } else {
+      this.logger?.debug?.("Chrome DevTools MCP not configured — WebPerf skills skipped");
+    }
+
+    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 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"}` };
+    }
+
+    try {
+      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" };
+      }
+
+      const verdict = parsed.verdict || (parsed.issuesFound > 0 ? "IMPROVED" : "APPROVED");
+      return {
+        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}` };
+    }
+  }
+}

package/src/roles/index.js

@@ -0,0 +1,18 @@
+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";
+export { CommiterRole } from "./commiter-role.js";
+export { CoderRole } from "./coder-role.js";
+export { SonarRole } from "./sonar-role.js";
+export { ResearcherRole } from "./researcher-role.js";
+export { TriageRole } from "./triage-role.js";
+export { TesterRole } from "./tester-role.js";
+export { SecurityRole } from "./security-role.js";
+export { SolomonRole } from "./solomon-role.js";
+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/onboarder-role.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0384 PR 2 — Onboarder role. Wraps collectors bundle + LLM
+// synthesis into a Markdown Architecture Brief.
+import { AgentRole } from "./agent-role.js";
+
+const FENCE_RE = /^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/;
+
+export class OnboarderRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "onboarder" });
+  }
+
+  extractInput(input) {
+    if (typeof input === "string") return { bundle: { projectDir: input } };
+    return { bundle: input?.bundle || input || { projectDir: "" } };
+  }
+
+  async buildPrompt({ bundle }) {
+    const instructions = this.instructions || "";
+    const prompt = [
+      instructions,
+      "",
+      "## Bundle (deterministic collectors output)",
+      "",
+      "```json",
+      JSON.stringify(bundle, null, 2),
+      "```",
+      "",
+      "Produce the Architecture Brief now.",
+    ].join("\n");
+    return { prompt };
+  }
+
+  parseOutput(raw) {
+    if (!raw || typeof raw !== "string") return { brief: "" };
+    const trimmed = raw.trim();
+    const fenced = trimmed.match(FENCE_RE);
+    return { brief: fenced ? fenced[1].trim() : trimmed };
+  }
+
+  buildSuccessResult(parsed, provider) {
+    return { brief: parsed.brief, provider };
+  }
+
+  buildSummary(parsed) {
+    const lines = (parsed.brief || "").split("\n").length;
+    return `Architecture brief composed (${lines} line${lines === 1 ? "" : "s"})`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { brief: agentResult.output || "", provider },
+      summary: "Architecture brief composed (raw)",
+      usage: agentResult.usage,
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}

package/src/roles/perf-role.js

@@ -0,0 +1,122 @@
+/**
+ * PerfRole — webperf quality gate (KJC-TSK-0150).
+ *
+ * Same shape as SonarRole / AuditRole: extends BaseRole, exposes an
+ * `execute()` that returns `{ok, result, summary}`. Internally drives
+ * `runWebperfScan` from src/webperf/scanner.js (the Lighthouse wrapper
+ * added in KJC-TSK-0149) and persists the result so subsequent
+ * `kj audit` runs surface it via `cwv-result` mode (KJC-TSK-0360).
+ *
+ * Configuration (kj.config.yml):
+ *   webperf:
+ *     url: http://localhost:3000   # required for the role to run
+ *     preset: desktop              # or "mobile"
+ *     thresholds: { lcp: { good: 2500, poor: 4000 }, ... }
+ *     persist: true                # writes to ~/.karajan/webperf/<slug>/last.json
+ *
+ * Pipeline activation (KJC-TSK-0151) wires this role behind a triage-
+ * driven flag so it only runs for frontend / fullstack tasks.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { BaseRole } from "./base-role.js";
+import { runWebperfScan } from "../webperf/scanner.js";
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultPersistDir() { return getWebperfDir(); }
+
+async function persistResult(result, projectDir) {
+  if (!result?.ok) return null;
+  const dir = path.join(defaultPersistDir(), projectSlug(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "last.json");
+  await fs.writeFile(filePath, JSON.stringify(result, null, 2), "utf8");
+  return filePath;
+}
+
+export class PerfRole extends BaseRole {
+  constructor({ config, logger, emitter = null, scanFn = null }) {
+    super({ name: "perf", config, logger, emitter });
+    // scanFn is injectable for tests so we don't need to mock execFile here.
+    this._scan = scanFn || runWebperfScan;
+  }
+
+  /**
+   * Run a webperf scan against the configured URL.
+   *
+   * @param {object} [_input] - unused; PerfRole reads its target from config
+   * @returns {Promise<{ok: boolean, result: object, summary: string}>}
+   */
+  async execute(_input) {
+    const webperfConfig = this.config?.webperf || {};
+    const url = webperfConfig.url;
+    const preset = webperfConfig.preset === "mobile" ? "mobile" : "desktop";
+    const thresholds = webperfConfig.thresholds || null;
+    const persist = webperfConfig.persist !== false;
+
+    if (!url) {
+      return {
+        ok: false,
+        result: { error: "config.webperf.url is required for PerfRole" },
+        summary: "PerfRole skipped: no config.webperf.url configured",
+      };
+    }
+
+    const scan = await this._scan(url, { preset, thresholds, logger: this.logger });
+
+    if (!scan.ok) {
+      return {
+        ok: false,
+        result: {
+          url,
+          error: scan.reason || "webperf scan failed",
+        },
+        summary: `Webperf scan failed: ${scan.reason || "unknown"}`,
+      };
+    }
+
+    let savedPath = null;
+    if (persist) {
+      try {
+        savedPath = await persistResult(scan, this.config?.projectDir);
+      } catch (err) {
+        if (this.logger?.warn) {
+          this.logger.warn(`PerfRole: failed to persist result (non-blocking): ${err.message}`);
+        }
+      }
+    }
+
+    const verdict = scan.cwv?.pass ? "PASS" : "FAIL";
+    const score = typeof scan.performanceScore === "number" ? scan.performanceScore : null;
+    const blockingMetrics = (scan.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)}`).join(", ");
+    const summaryParts = [
+      `Webperf ${verdict}`,
+      score !== null ? `score ${score}/100` : null,
+      blockingMetrics ? `blocking: ${blockingMetrics}` : null,
+      `top opportunities: ${scan.issues?.length ?? 0}`,
+    ].filter(Boolean);
+
+    return {
+      ok: scan.cwv?.pass === true,
+      result: {
+        url: scan.url,
+        preset: scan.preset,
+        capturedAt: scan.capturedAt,
+        performanceScore: scan.performanceScore,
+        metrics: scan.metrics,
+        cwv: scan.cwv,
+        issues: scan.issues,
+        thresholds: scan.thresholds,
+        savedPath,
+      },
+      summary: summaryParts.join(" — "),
+    };
+  }
+}

package/src/roles/planner-role.js

@@ -0,0 +1,151 @@
+import { AgentRole } from "./agent-role.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const RESEARCH_FIELDS = [
+  { key: "affected_files", label: "Affected files" },
+  { key: "patterns", label: "Patterns" },
+  { key: "constraints", label: "Constraints" },
+  { key: "risks", label: "Risks" },
+  { 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(", ")}`);
+  }
+  sections.push("");
+}
+
+function appendArchitectSection(sections, architectContext) {
+  if (!architectContext) return;
+  const arch = architectContext.architecture || {};
+  sections.push("## Architecture context");
+  if (arch.type) sections.push(`Type: ${arch.type}`);
+  if (arch.layers?.length) sections.push(`Layers: ${arch.layers.join(", ")}`);
+  if (arch.patterns?.length) sections.push(`Patterns: ${arch.patterns.join(", ")}`);
+  if (arch.dataModel?.entities?.length) sections.push(`Data model entities: ${arch.dataModel.entities.join(", ")}`);
+  if (arch.apiContracts?.length) sections.push(`API contracts: ${arch.apiContracts.join(", ")}`);
+  if (arch.tradeoffs?.length) sections.push(`Tradeoffs: ${arch.tradeoffs.join(", ")}`);
+  if (architectContext.summary) sections.push(`Summary: ${architectContext.summary}`);
+  sections.push("");
+}
+
+function resolveSilenceTimeoutMs(config) {
+  const minutes = Number(config?.session?.max_agent_silence_minutes);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
+}
+
+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 AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "planner" });
+  }
+
+  async execute(input) {
+    const { task: rawTask, onOutput } = typeof input === "string"
+      ? { task: input, onOutput: null }
+      : { task: input?.task || input || "", onOutput: input?.onOutput || null };
+
+    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 sections = [];
+    if (this.instructions) sections.push(this.instructions, "");
+    // Tests-first planning (v2.7.5):
+    // The planner MUST emit structured acceptance tests for every step.
+    // These are the contract the coder is handed (phase 2 of the
+    // tests-first flow); the tester role later runs them as the
+    // pass/fail gate. Without them the coder has no executable spec.
+    sections.push(
+      "Create an implementation plan for this task as structured JSON.",
+      "",
+      "Output MUST be a JSON object with this exact shape:",
+      "",
+      "```json",
+      "{",
+      '  "approach": "<2-3 sentence high-level plan>",',
+      '  "risks": ["<risk 1>", "<risk 2>"],',
+      '  "outOfScope": ["<excluded item>"],',
+      '  "steps": [',
+      "    {",
+      '      "description": "<what this step achieves, one sentence>",',
+      '      "spec_section": "<short reference to the SPEC section this implements, e.g. \\"5.3\\" or \\"§5 Initial Scope\\". Optional but strongly preferred.>",',
+      '      "acceptance_tests": [',
+      '        { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+      '        { "type": "shell", "content": "<bash command that must exit 0>" }',
+      "      ]",
+      "    }",
+      "  ]",
+      "}",
+      "```",
+      "",
+      "Rules for acceptance_tests (CRITICAL — this is the contract the coder must satisfy):",
+      '- EVERY step MUST have at least one acceptance_test. No empty arrays.',
+      '- "gherkin" tests describe observable behaviour in natural language. Use them for end-to-end or user-facing assertions.',
+      '- "shell" tests are bash commands that exit 0 on success. Use them for concrete verifications (file exists, lint passes, specific exit code, HTTP status).',
+      '- Write tests BEFORE the step is implemented — they should fail until the step is done, pass afterwards.',
+      '- Prefer 2-4 tests per step: one happy-path, at least one edge case / failure path.',
+      '- Do NOT use the generic fallback "npx vitest run" (pre-v2.7.5 placeholder). Each test must assert something specific to the step.',
+      "",
+      "spec_section: when the task includes a structured SPEC (numbered headings like '## 5. Initial Scope'), every step MUST cite the section it implements. Becomes traceability metadata for the coder and reviewer.",
+      "",
+      "Steps must be ordered so that each depends only on previous steps (the first step has no prerequisites).",
+      "Return ONLY the JSON — no prose, no markdown fences around it.",
+      ""
+    );
+    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 silenceMs = resolveSilenceTimeoutMs(this.config);
+    if (silenceMs) runArgs.silenceTimeoutMs = silenceMs;
+    const timeoutMs = resolveRuntimeTimeoutMs(this.config);
+    if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+
+    // KJC-TSK-0413 step C: PlannerRole tiene execute() custom (no usa el de
+    // AgentRole). Wrap aquí también.
+    const result = await withBrainRecovery({
+      agent, taskArgs: runArgs, role: "planner", provider,
+      emitter: this.emitter, logger: this.logger,
+    });
+
+    if (!result.ok) {
+      const recoveryNote = result.recovery?.class ? ` [${result.recovery.class}]` : "";
+      return {
+        ok: false,
+        result: { ...result, error: result.error || result.output || `Planner agent failed${recoveryNote}`, plan: null, recovery: result.recovery, action: result.action },
+        summary: `Planner failed${recoveryNote}: ${result.recovery?.message || result.error || "unknown error"}`
+      };
+    }
+
+    const plan = result.output?.trim() || "";
+    return {
+      ok: true,
+      result: { ...result, plan, provider },
+      summary: plan ? `Plan generated (${plan.split("\n").length} lines)` : "Empty plan generated"
+    };
+  }
+}

package/src/roles/refactorer-role.js

@@ -0,0 +1,30 @@
+import { AgentRole } from "./agent-role.js";
+
+export class RefactorerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "refactorer" });
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.refactorer?.provider || this.config?.roles?.coder?.provider || "claude";
+  }
+
+  async buildPrompt({ task }) {
+    const sections = [];
+    if (this.instructions) sections.push(this.instructions, "");
+    sections.push(
+      "Refactor the current changes for clarity and maintainability without changing behavior.",
+      "Do not expand scope and keep tests green.",
+      "",
+      "## Task context",
+      task
+    );
+    return { prompt: sections.join("\n") };
+  }
+
+  buildSuccessResult(parsed, provider, agentResult) {
+    return { ...agentResult, output: (agentResult.output || "").trim(), provider };
+  }
+
+  buildSummary() { return "Refactoring applied"; }
+}