karajan-code 1.16.0 → 1.18.0

package/src/planning-game/adapter.js

@@ -7,31 +7,27 @@ const CARD_ID_PATTERN = /[A-Z0-9]{2,5}-(?:TSK|BUG|PCS|PRP|SPR|QA)-\d{4}/;
 
 export function parseCardId(text) {
   if (!text) return null;
-  const match = String(text).match(CARD_ID_PATTERN);
+  const match = CARD_ID_PATTERN.exec(String(text));
   return match ? match[0] : null;
 }
 
-export function buildTaskFromCard(card) {
-  const parts = [`## ${card.cardId}: ${card.title}`];
-
+function appendDescriptionSection(parts, card) {
   if (card.descriptionStructured?.length) {
     parts.push("", "### User Story");
     for (const s of card.descriptionStructured) {
-      parts.push(`- **Como** ${s.role}`);
-      parts.push(`  **Quiero** ${s.goal}`);
-      parts.push(`  **Para** ${s.benefit}`);
+      parts.push(`- **Como** ${s.role}`, `  **Quiero** ${s.goal}`, `  **Para** ${s.benefit}`);
     }
   } else if (card.description) {
     parts.push("", "### Description", card.description);
   }
+}
 
+function appendAcceptanceCriteriaSection(parts, card) {
   if (card.acceptanceCriteriaStructured?.length) {
     parts.push("", "### Acceptance Criteria");
     for (const ac of card.acceptanceCriteriaStructured) {
       if (ac.given && ac.when && ac.then) {
-        parts.push(`- **Given** ${ac.given}`);
-        parts.push(`  **When** ${ac.when}`);
-        parts.push(`  **Then** ${ac.then}`);
+        parts.push(`- **Given** ${ac.given}`, `  **When** ${ac.when}`, `  **Then** ${ac.then}`);
       } else if (ac.raw) {
         parts.push(`- ${ac.raw}`);
       }
@@ -39,24 +35,31 @@ export function buildTaskFromCard(card) {
   } else if (card.acceptanceCriteria) {
     parts.push("", "### Acceptance Criteria", card.acceptanceCriteria);
   }
+}
 
-  if (card.implementationPlan) {
-    const plan = card.implementationPlan;
-    parts.push("", "### Implementation Plan");
-    if (plan.approach) parts.push(`**Approach:** ${plan.approach}`);
-    if (plan.steps?.length) {
-      parts.push("**Steps:**");
-      for (const step of plan.steps) {
-        parts.push(`1. ${step.description}`);
-      }
+function appendImplementationPlanSection(parts, card) {
+  if (!card.implementationPlan) return;
+  const plan = card.implementationPlan;
+  parts.push("", "### Implementation Plan");
+  if (plan.approach) parts.push(`**Approach:** ${plan.approach}`);
+  if (plan.steps?.length) {
+    parts.push("**Steps:**");
+    for (const step of plan.steps) {
+      parts.push(`1. ${step.description}`);
     }
   }
+}
 
+export function buildTaskFromCard(card) {
+  const parts = [`## ${card.cardId}: ${card.title}`];
+  appendDescriptionSection(parts, card);
+  appendAcceptanceCriteriaSection(parts, card);
+  appendImplementationPlanSection(parts, card);
   return parts.join("\n");
 }
 
 export function buildCommitsPayload(gitLog) {
-  if (!gitLog || !gitLog.length) return [];
+  if (!gitLog?.length) return [];
   return gitLog.map((entry) => ({
     hash: entry.hash,
     message: entry.message,

package/src/planning-game/architect-adrs.js

@@ -0,0 +1,45 @@
+/**
+ * Automatic ADR generation from architect tradeoffs.
+ * Creates ADRs in Planning Game when PG is linked, or returns suggestions otherwise.
+ */
+
+function buildAdr({ tradeoff, taskTitle }) {
+  return {
+    title: tradeoff,
+    status: "accepted",
+    context: `Architecture decision for task: ${taskTitle}`,
+    decision: tradeoff
+  };
+}
+
+export async function createArchitectADRs({ tradeoffs, pgTaskId, pgProject, taskTitle, mcpClient }) {
+  if (!tradeoffs?.length) {
+    return { created: 0, adrs: [] };
+  }
+
+  const hasPg = Boolean(pgTaskId && pgProject && mcpClient);
+
+  if (!hasPg) {
+    const adrs = tradeoffs.map(tradeoff => ({
+      ...buildAdr({ tradeoff, taskTitle }),
+      suggestion: true
+    }));
+    return { created: 0, adrs };
+  }
+
+  const adrs = [];
+  let created = 0;
+
+  for (const tradeoff of tradeoffs) {
+    const adr = buildAdr({ tradeoff, taskTitle });
+    try {
+      await mcpClient.createAdr({ projectId: pgProject, adr });
+      adrs.push(adr);
+      created++;
+    } catch {
+      // Log warning but don't block pipeline for a single ADR failure
+    }
+  }
+
+  return { created, adrs };
+}

package/src/planning-game/client.js

@@ -9,7 +9,7 @@
  * Requires planning_game.api_url in config or PG_API_URL env var.
  */
 
-import { withRetry, isTransientError } from "../utils/retry.js";
+import { withRetry } from "../utils/retry.js";
 
 const DEFAULT_API_URL = "http://localhost:3000/api";
 const DEFAULT_TIMEOUT_MS = 10000;
@@ -104,6 +104,20 @@ export async function createCard({ projectId, card, timeoutMs = DEFAULT_TIMEOUT_
   return parseJsonResponse(response);
 }
 
+export async function createAdr({ projectId, adr, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/adrs`;
+  const response = await fetchWithRetry(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(adr)
+    },
+    timeoutMs
+  );
+  return parseJsonResponse(response);
+}
+
 export async function relateCards({ projectId, sourceCardId, targetCardId, relationType, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/relate`;
   const response = await fetchWithRetry(

package/src/planning-game/decomposition.js

@@ -74,10 +74,12 @@ export function buildDecompositionQuestion(subtasks, parentCardId) {
   for (let i = 0; i < subtasks.length; i++) {
     lines.push(`${i + 1}. ${subtasks[i]}`);
   }
-  lines.push("");
-  lines.push(`Create these as linked cards in Planning Game (parent: ${parentCardId})?`);
-  lines.push("Each subtask will block the next one (sequential chain).");
-  lines.push("");
-  lines.push("Reply: yes / no");
+  lines.push(
+    "",
+    `Create these as linked cards in Planning Game (parent: ${parentCardId})?`,
+    "Each subtask will block the next one (sequential chain).",
+    "",
+    "Reply: yes / no"
+  );
   return lines.join("\n");
 }

package/src/prompts/architect.js

@@ -0,0 +1,88 @@
+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 designing the architecture for the task."
+].join(" ");
+
+export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
+
+export function buildArchitectPrompt({ task, instructions, researchContext = null }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    "You are the architect in a multi-role AI pipeline.",
+    "Analyze the task and produce a concrete architecture design including layers, patterns, data model, API contracts, dependencies, and tradeoffs.",
+    "## Architecture Guidelines",
+    [
+      "- Identify the architecture type (layered, microservices, event-driven, etc.)",
+      "- Define the layers and their responsibilities",
+      "- Identify design patterns to apply",
+      "- Define the data model with entities",
+      "- Specify API contracts (endpoints, events, interfaces)",
+      "- List external and internal dependencies",
+      "- Document tradeoffs and their rationale",
+      "- If critical decisions cannot be made without more information, list clarifying questions"
+    ].join("\n"),
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"verdict":"ready|needs_clarification","architecture":{"type":string,"layers":[string],"patterns":[string],"dataModel":{"entities":[string]},"apiContracts":[string],"dependencies":[string],"tradeoffs":[string]},"questions":[string],"summary":string}'
+  );
+
+  if (researchContext) {
+    sections.push(`## Research Context\n${researchContext}`);
+  }
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+function filterStrings(arr) {
+  if (!Array.isArray(arr)) return [];
+  return arr.filter((item) => typeof item === "string");
+}
+
+export function parseArchitectOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch {
+    return null;
+  }
+
+  const verdict = VALID_VERDICTS.has(parsed.verdict)
+    ? parsed.verdict
+    : "needs_clarification";
+
+  const arch = parsed.architecture && typeof parsed.architecture === "object"
+    ? parsed.architecture
+    : {};
+
+  const dataModel = arch.dataModel && typeof arch.dataModel === "object"
+    ? arch.dataModel
+    : {};
+
+  return {
+    verdict,
+    architecture: {
+      type: typeof arch.type === "string" ? arch.type : "",
+      layers: filterStrings(arch.layers),
+      patterns: filterStrings(arch.patterns),
+      dataModel: {
+        entities: filterStrings(dataModel.entities)
+      },
+      apiContracts: filterStrings(arch.apiContracts),
+      dependencies: filterStrings(arch.dependencies),
+      tradeoffs: filterStrings(arch.tradeoffs)
+    },
+    questions: filterStrings(parsed.questions),
+    summary: parsed.summary || ""
+  };
+}

package/src/prompts/discover.js

@@ -6,11 +6,11 @@ const SUBAGENT_PREAMBLE = [
 
 export const DISCOVER_MODES = ["gaps", "momtest", "wendel", "classify", "jtbd"];
 
-const VALID_VERDICTS = ["ready", "needs_validation"];
-const VALID_SEVERITIES = ["critical", "major", "minor"];
-const VALID_WENDEL_STATUSES = ["pass", "fail", "unknown", "not_applicable"];
-const VALID_CLASSIFY_TYPES = ["START", "STOP", "DIFFERENT", "not_applicable"];
-const VALID_ADOPTION_RISKS = ["none", "low", "medium", "high"];
+const VALID_VERDICTS = new Set(["ready", "needs_validation"]);
+const VALID_SEVERITIES = new Set(["critical", "major", "minor"]);
+const VALID_WENDEL_STATUSES = new Set(["pass", "fail", "unknown", "not_applicable"]);
+const VALID_CLASSIFY_TYPES = new Set(["START", "STOP", "DIFFERENT", "not_applicable"]);
+const VALID_ADOPTION_RISKS = new Set(["none", "low", "medium", "high"]);
 
 export function buildDiscoverPrompt({ task, instructions, mode = "gaps", context = null }) {
   const sections = [SUBAGENT_PREAMBLE];
@@ -21,10 +21,7 @@ export function buildDiscoverPrompt({ task, instructions, mode = "gaps", context
 
   sections.push(
     "You are a task discovery agent for Karajan Code, a multi-agent coding orchestrator.",
-    "Analyze the following task and identify gaps, ambiguities, missing information, and implicit assumptions."
-  );
-
-  sections.push(
+    "Analyze the following task and identify gaps, ambiguities, missing information, and implicit assumptions.",
     "## Gap Detection Guidelines",
     [
       "- Look for missing acceptance criteria or requirements",
@@ -143,56 +140,60 @@ export function buildDiscoverPrompt({ task, instructions, mode = "gaps", context
   return sections.join("\n\n");
 }
 
-export function parseDiscoverOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = text.match(/\{[\s\S]*\}/);
-  if (!jsonMatch) return null;
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonMatch[0]);
-  } catch {
-    return null;
-  }
-
-  const verdict = VALID_VERDICTS.includes(parsed.verdict) ? parsed.verdict : "ready";
+function parseClassification(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const rawType = String(raw.type || "").toUpperCase();
+  let type;
+  if (rawType === "NOT_APPLICABLE") type = "not_applicable";
+  else if (VALID_CLASSIFY_TYPES.has(rawType)) type = rawType;
+  else type = "not_applicable";
+  const rawRisk = String(raw.adoptionRisk || "").toLowerCase();
+  return {
+    type,
+    adoptionRisk: VALID_ADOPTION_RISKS.has(rawRisk) ? rawRisk : "medium",
+    frictionEstimate: raw.frictionEstimate || ""
+  };
+}
 
-  const rawGaps = Array.isArray(parsed.gaps) ? parsed.gaps : [];
-  const gaps = rawGaps
-    .filter((g) => g && g.id && g.description && g.suggestedQuestion)
+function parseGaps(rawGaps) {
+  return (Array.isArray(rawGaps) ? rawGaps : [])
+    .filter((g) => g?.id && g.description && g.suggestedQuestion)
     .map((g) => ({
       id: g.id,
       description: g.description,
-      severity: VALID_SEVERITIES.includes(String(g.severity).toLowerCase())
+      severity: VALID_SEVERITIES.has(String(g.severity).toLowerCase())
         ? String(g.severity).toLowerCase()
         : "major",
       suggestedQuestion: g.suggestedQuestion
     }));
+}
 
-  const rawQuestions = Array.isArray(parsed.momTestQuestions) ? parsed.momTestQuestions : [];
-  const momTestQuestions = rawQuestions
-    .filter((q) => q && q.gapId && q.question && q.targetRole && q.rationale)
+function parseMomTestQuestions(rawQuestions) {
+  return (Array.isArray(rawQuestions) ? rawQuestions : [])
+    .filter((q) => q?.gapId && q.question && q.targetRole && q.rationale)
     .map((q) => ({
       gapId: q.gapId,
       question: q.question,
       targetRole: q.targetRole,
       rationale: q.rationale
     }));
+}
 
-  const rawChecklist = Array.isArray(parsed.wendelChecklist) ? parsed.wendelChecklist : [];
-  const wendelChecklist = rawChecklist
-    .filter((c) => c && c.condition && c.justification && c.status)
+function parseWendelChecklist(rawChecklist) {
+  return (Array.isArray(rawChecklist) ? rawChecklist : [])
+    .filter((c) => c?.condition && c.justification && c.status)
     .map((c) => ({
       condition: c.condition,
-      status: VALID_WENDEL_STATUSES.includes(String(c.status).toLowerCase())
+      status: VALID_WENDEL_STATUSES.has(String(c.status).toLowerCase())
         ? String(c.status).toLowerCase()
         : "unknown",
       justification: c.justification
     }));
+}
 
-  const rawJtbds = Array.isArray(parsed.jtbds) ? parsed.jtbds : [];
-  const jtbds = rawJtbds
-    .filter((j) => j && j.id && j.functional && j.emotionalPersonal && j.emotionalSocial && j.behaviorChange && j.evidence)
+function parseJtbds(rawJtbds) {
+  return (Array.isArray(rawJtbds) ? rawJtbds : [])
+    .filter((j) => j?.id && j.functional && j.emotionalPersonal && j.emotionalSocial && j.behaviorChange && j.evidence)
     .map((j) => ({
       id: j.id,
       functional: j.functional,
@@ -201,27 +202,27 @@ export function parseDiscoverOutput(raw) {
       behaviorChange: j.behaviorChange,
       evidence: j.evidence
     }));
+}
 
-  let classification = null;
-  if (parsed.classification && typeof parsed.classification === "object") {
-    const rawType = String(parsed.classification.type || "").toUpperCase();
-    const type = rawType === "NOT_APPLICABLE" ? "not_applicable"
-      : VALID_CLASSIFY_TYPES.includes(rawType) ? rawType : "not_applicable";
-    const rawRisk = String(parsed.classification.adoptionRisk || "").toLowerCase();
-    classification = {
-      type,
-      adoptionRisk: VALID_ADOPTION_RISKS.includes(rawRisk) ? rawRisk : "medium",
-      frictionEstimate: parsed.classification.frictionEstimate || ""
-    };
+export function parseDiscoverOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch {
+    return null;
   }
 
   return {
-    verdict,
-    gaps,
-    momTestQuestions,
-    wendelChecklist,
-    classification,
-    jtbds,
+    verdict: VALID_VERDICTS.has(parsed.verdict) ? parsed.verdict : "ready",
+    gaps: parseGaps(parsed.gaps),
+    momTestQuestions: parseMomTestQuestions(parsed.momTestQuestions),
+    wendelChecklist: parseWendelChecklist(parsed.wendelChecklist),
+    classification: parseClassification(parsed.classification),
+    jtbds: parseJtbds(parsed.jtbds),
     summary: parsed.summary || ""
   };
 }

package/src/prompts/planner.js

@@ -1,3 +1,25 @@
+function extractStepText(line) {
+  const numberedStep = /^\d+[).:-]\s*(.+)$/.exec(line);
+  if (numberedStep) return numberedStep[1].trim();
+  const bulletStep = /^[-*]\s+(.+)$/.exec(line);
+  if (bulletStep) return bulletStep[1].trim();
+  return null;
+}
+
+function classifyLine(line, state) {
+  if (!state.title) {
+    const titleMatch = /^title\s*:\s*(.+)$/i.exec(line);
+    if (titleMatch) return { type: "title", value: titleMatch[1].trim() };
+  }
+  if (!state.approach) {
+    const approachMatch = /^(approach|strategy)\s*:\s*(.+)$/i.exec(line);
+    if (approachMatch) return { type: "approach", value: approachMatch[2].trim() };
+  }
+  const stepText = extractStepText(line);
+  if (stepText) return { type: "step", value: stepText };
+  return null;
+}
+
 export function parsePlannerOutput(output) {
   const text = String(output || "").trim();
   if (!text) return null;
@@ -7,49 +29,42 @@ export function parsePlannerOutput(output) {
     .map((line) => line.trim())
     .filter(Boolean);
 
-  let title = null;
-  let approach = null;
+  const state = { title: null, approach: null };
   const steps = [];
 
   for (const line of lines) {
-    if (!title) {
-      const titleMatch = line.match(/^title\s*:\s*(.+)$/i);
-      if (titleMatch) {
-        title = titleMatch[1].trim();
-        continue;
-      }
-    }
+    const classified = classifyLine(line, state);
+    if (!classified) continue;
+    if (classified.type === "title") state.title = classified.value;
+    else if (classified.type === "approach") state.approach = classified.value;
+    else if (classified.type === "step") steps.push(classified.value);
+  }
 
-    if (!approach) {
-      const approachMatch = line.match(/^(approach|strategy)\s*:\s*(.+)$/i);
-      if (approachMatch) {
-        approach = approachMatch[2].trim();
-        continue;
-      }
-    }
+  if (!state.title) {
+    const firstFreeLine = lines.find((line) => !/^(approach|strategy)\s*:/i.test(line) && !/^\d+[).:-]\s*/.test(line));
+    state.title = firstFreeLine || null;
+  }
 
-    const numberedStep = line.match(/^\d+[\).:-]\s*(.+)$/);
-    if (numberedStep) {
-      steps.push(numberedStep[1].trim());
-      continue;
-    }
+  return { title: state.title, approach: state.approach, steps };
+}
 
-    const bulletStep = line.match(/^[-*]\s+(.+)$/);
-    if (bulletStep) {
-      steps.push(bulletStep[1].trim());
-      continue;
-    }
-  }
+function formatArchitectContext(architectContext) {
+  if (!architectContext) return null;
+  const arch = architectContext.architecture || {};
+  const lines = ["## Architecture Context"];
 
-  if (!title) {
-    const firstFreeLine = lines.find((line) => !/^(approach|strategy)\s*:/i.test(line) && !/^\d+[\).:-]\s*/.test(line));
-    title = firstFreeLine || null;
-  }
+  if (arch.type) lines.push(`**Type:** ${arch.type}`);
+  if (arch.layers?.length) lines.push(`**Layers:** ${arch.layers.join(", ")}`);
+  if (arch.patterns?.length) lines.push(`**Patterns:** ${arch.patterns.join(", ")}`);
+  if (arch.dataModel?.entities?.length) lines.push(`**Data model entities:** ${arch.dataModel.entities.join(", ")}`);
+  if (arch.apiContracts?.length) lines.push(`**API contracts:** ${arch.apiContracts.join(", ")}`);
+  if (arch.tradeoffs?.length) lines.push(`**Tradeoffs:** ${arch.tradeoffs.join(", ")}`);
+  if (architectContext.summary) lines.push(`**Summary:** ${architectContext.summary}`);
 
-  return { title, approach, steps };
+  return lines.length > 1 ? lines.join("\n") : null;
 }
 
-export function buildPlannerPrompt({ task, context }) {
+export function buildPlannerPrompt({ task, context, architectContext }) {
   const parts = [
     "You are an expert software architect. Create an implementation plan for the following task.",
     "",
@@ -62,6 +77,11 @@ export function buildPlannerPrompt({ task, context }) {
     parts.push("## Context", context, "");
   }
 
+  const archSection = formatArchitectContext(architectContext);
+  if (archSection) {
+    parts.push(archSection, "");
+  }
+
   parts.push(
     "## Output format",
     "Respond with a JSON object containing:",

package/src/prompts/triage.js

@@ -10,7 +10,8 @@ const ROLE_DESCRIPTIONS = [
   { role: "tester", description: "Runs dedicated testing pass after coding. Ensures tests exist and pass." },
   { role: "security", description: "Audits code for security vulnerabilities. Checks auth, input validation, injection risks." },
   { role: "refactorer", description: "Cleans up and refactors code after the main implementation." },
-  { role: "reviewer", description: "Reviews the code diff for quality issues. Standard quality gate." }
+  { role: "reviewer", description: "Reviews the code diff for quality issues. Standard quality gate." },
+  { role: "architect", description: "Designs solution architecture — layers, patterns, data model, API contracts, tradeoffs. Activate when task creates new module/app, affects data model/APIs, complexity is medium/complex, or design is ambiguous." }
 ];
 
 export function buildTriagePrompt({ task, instructions, availableRoles }) {
@@ -24,15 +25,9 @@ export function buildTriagePrompt({ task, instructions, availableRoles }) {
 
   sections.push(
     "You are a task triage agent for Karajan Code, a multi-agent coding orchestrator.",
-    "Analyze the following task and determine which pipeline roles should be activated."
-  );
-
-  sections.push(
+    "Analyze the following task and determine which pipeline roles should be activated.",
     "## Available Roles",
-    roles.map((r) => `- **${r.role}**: ${r.description}`).join("\n")
-  );
-
-  sections.push(
+    roles.map((r) => `- **${r.role}**: ${r.description}`).join("\n"),
     "## Decision Guidelines",
     [
       "- **planner**: Enable for complex tasks (multi-file, architectural changes, data model changes). Disable for simple fixes.",
@@ -41,20 +36,17 @@ export function buildTriagePrompt({ task, instructions, availableRoles }) {
       "- **security**: Enable for authentication, APIs, user input handling, data access, external integrations. Disable for UI-only or doc changes.",
       "- **refactorer**: Enable only when explicitly requested or when the task is a refactoring task.",
       "- **reviewer**: Enable for most tasks as a quality gate. Disable only for trivial, single-line changes.",
+      "- **architect**: Enable when creating new modules/apps, changing data models or APIs, medium/complex tasks, or when design approach is ambiguous. Disable for simple fixes, doc-only, or CSS-only changes.",
       "",
       "Note: coder is ALWAYS active — you don't need to decide on it."
-    ].join("\n")
-  );
-
-  sections.push(
+    ].join("\n"),
     "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
     "Keep the reasoning short and practical.",
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security"],"taskType":"sw|infra|doc|add-tests|refactor","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}'
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect"],"taskType":"sw|infra|doc|add-tests|refactor","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
+    `## Task\n${task}`
   );
 
-  sections.push(`## Task\n${task}`);
-
   return sections.join("\n\n");
 }
 

package/src/review/parser.js

@@ -22,33 +22,32 @@ export function parseMaybeJsonString(value) {
   }
 }
 
-export function normalizeReviewPayload(payload) {
-  if (!payload) return null;
-
-  if (payload.approved !== undefined && payload.blocking_issues !== undefined) {
-    return payload;
-  }
+function isReviewPayload(obj) {
+  return obj?.approved !== undefined && obj?.blocking_issues !== undefined;
+}
 
-  if (Array.isArray(payload)) {
-    for (let i = payload.length - 1; i >= 0; i -= 1) {
-      const item = payload[i];
-      if (item?.approved !== undefined && item?.blocking_issues !== undefined) {
-        return item;
-      }
+function findReviewInArray(arr) {
+  for (let i = arr.length - 1; i >= 0; i -= 1) {
+    const item = arr[i];
+    if (isReviewPayload(item)) return item;
 
-      const nested = item?.result || item?.message?.content?.[0]?.text;
-      if (typeof nested === "string") {
-        const parsedNested = parseMaybeJsonString(nested);
-        if (parsedNested?.approved !== undefined) return parsedNested;
-      }
+    const nested = item?.result || item?.message?.content?.[0]?.text;
+    if (typeof nested === "string") {
+      const parsedNested = parseMaybeJsonString(nested);
+      if (parsedNested?.approved !== undefined) return parsedNested;
     }
-    return null;
   }
+  return null;
+}
+
+export function normalizeReviewPayload(payload) {
+  if (!payload) return null;
+  if (isReviewPayload(payload)) return payload;
+  if (Array.isArray(payload)) return findReviewInArray(payload);
 
   if (typeof payload.result === "string") {
     const parsedResult = parseMaybeJsonString(payload.result);
     if (parsedResult?.approved !== undefined) return parsedResult;
-    return null;
   }
 
   return null;