karajan-code 1.15.0 → 1.17.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

@@ -0,0 +1,228 @@
+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 discovering gaps in the task specification."
+].join(" ");
+
+export const DISCOVER_MODES = ["gaps", "momtest", "wendel", "classify", "jtbd"];
+
+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];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  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.",
+    "## Gap Detection Guidelines",
+    [
+      "- Look for missing acceptance criteria or requirements",
+      "- Identify implicit assumptions that need explicit confirmation",
+      "- Find ambiguities where multiple interpretations exist",
+      "- Check for contradictions between different parts of the spec",
+      "- Consider edge cases and error scenarios not addressed",
+      "- Classify each gap by severity: critical (blocks implementation), major (could cause rework), minor (reasonable default exists)"
+    ].join("\n")
+  );
+
+  if (mode === "momtest") {
+    sections.push(
+      "## Mom Test Rules",
+      [
+        "For each gap, generate questions that follow The Mom Test principles:",
+        "- ALWAYS ask about past behavior and real experiences, never hypothetical scenarios",
+        "- NEVER ask 'Would you...?', 'Do you think...?', 'Would it be useful if...?'",
+        "- ALWAYS ask 'When was the last time...?', 'How do you currently...?', 'What happened when...?'",
+        "- Ask about specifics, not generalities",
+        "- Each question must have a targetRole (who to ask) and rationale (why this matters)",
+        "",
+        "Examples of BAD questions (hypothetical/opinion):",
+        "  - 'Would you use this feature?' -> opinion, not data",
+        "  - 'Do you think users need this?' -> speculation",
+        "",
+        "Examples of GOOD questions (past behavior):",
+        "  - 'When was the last time you had to do X manually?' -> real experience",
+        "  - 'How are you currently handling Y?' -> current behavior",
+        "  - 'What happened the last time Z failed?' -> real consequence"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "wendel") {
+    sections.push(
+      "## Wendel Behavior Change Checklist",
+      [
+        "Evaluate whether the task implies a user behavior change. If it does, assess these 5 conditions:",
+        "",
+        "1. **CUE** — Is there a clear trigger that will prompt the user to take the new action?",
+        "2. **REACTION** — Will the user have a positive emotional reaction when they encounter the cue?",
+        "3. **EVALUATION** — Can the user quickly understand the value of the new behavior?",
+        "4. **ABILITY** — Does the user have the skill and resources to perform the new behavior?",
+        "5. **TIMING** — Is this the right moment to introduce this change?",
+        "",
+        "For each condition, set status to: pass, fail, unknown, or not_applicable",
+        "If the task does NOT imply behavior change (e.g., internal refactor, backend optimization), set ALL conditions to 'not_applicable'",
+        "If ANY condition is 'fail', set verdict to 'needs_validation'"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "classify") {
+    sections.push(
+      "## Behavior Change Classification",
+      [
+        "Classify the task by its impact on user behavior:",
+        "",
+        "- **START**: User must adopt a completely new behavior or workflow",
+        "- **STOP**: User must stop doing something they currently do (highest resistance risk)",
+        "- **DIFFERENT**: User must do something they already do, but differently",
+        "- **not_applicable**: Task has no user behavior impact (internal refactor, backend, infra)",
+        "",
+        "Assess adoption risk: none (no user impact), low, medium, high",
+        "STOP changes carry the highest risk of resistance — always flag them",
+        "Provide a frictionEstimate explaining the expected friction"
+      ].join("\n")
+    );
+  }
+
+  if (mode === "jtbd") {
+    sections.push(
+      "## Jobs-to-be-Done Framework",
+      [
+        "Generate reinforced Jobs-to-be-Done from the task and any provided context (interview notes, field observations).",
+        "Each JTBD must include 5 layers:",
+        "",
+        "- **functional**: The practical job the user is trying to accomplish",
+        "- **emotionalPersonal**: How the user wants to feel personally",
+        "- **emotionalSocial**: How the user wants to be perceived by others",
+        "- **behaviorChange**: Type of change: START, STOP, DIFFERENT, or not_applicable",
+        "- **evidence**: Direct quotes or specific references from the context. If no context provided, set to 'not_available' and suggest what context is needed",
+        "",
+        "CRITICAL: evidence must contain real quotes or references from the provided context, NEVER invented assumptions",
+        "If no context is provided, mark evidence as 'not_available'"
+      ].join("\n")
+    );
+  }
+
+  const baseSchema = '{"verdict":"ready|needs_validation","gaps":[{"id":string,"description":string,"severity":"critical|major|minor","suggestedQuestion":string}]';
+  const momtestSchema = mode === "momtest"
+    ? ',"momTestQuestions":[{"gapId":string,"question":string,"targetRole":string,"rationale":string}]'
+    : "";
+  const wendelSchema = mode === "wendel"
+    ? ',"wendelChecklist":[{"condition":"CUE|REACTION|EVALUATION|ABILITY|TIMING","status":"pass|fail|unknown|not_applicable","justification":string}]'
+    : "";
+  const classifySchema = mode === "classify"
+    ? ',"classification":{"type":"START|STOP|DIFFERENT|not_applicable","adoptionRisk":"none|low|medium|high","frictionEstimate":string}'
+    : "";
+  const jtbdSchema = mode === "jtbd"
+    ? ',"jtbds":[{"id":string,"functional":string,"emotionalPersonal":string,"emotionalSocial":string,"behaviorChange":"START|STOP|DIFFERENT|not_applicable","evidence":string}]'
+    : "";
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: ${baseSchema}${momtestSchema}${wendelSchema}${classifySchema}${jtbdSchema},"summary":string}`
+  );
+
+  if (context) {
+    sections.push(`## Context\n${context}`);
+  }
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+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 || ""
+  };
+}
+
+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.has(String(g.severity).toLowerCase())
+        ? String(g.severity).toLowerCase()
+        : "major",
+      suggestedQuestion: g.suggestedQuestion
+    }));
+}
+
+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
+    }));
+}
+
+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.has(String(c.status).toLowerCase())
+        ? String(c.status).toLowerCase()
+        : "unknown",
+      justification: c.justification
+    }));
+}
+
+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,
+      emotionalPersonal: j.emotionalPersonal,
+      emotionalSocial: j.emotionalSocial,
+      behaviorChange: j.behaviorChange,
+      evidence: j.evidence
+    }));
+}
+
+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: 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");
 }