feat(KB-178): add proactive triage subtask guidance

- Add proactive subtask breakdown prompts to triage agent
- Update dashboard routes to support triage subtask operations
- Add comprehensive tests for triage subtask guidance logic
- Include changeset for @dustinbyrne/kb package release

packages/engine/src/triage.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import type { TaskStore, Task, TaskDetail, Settings } from "@kb/core";
 import {
   TriageProcessor,
+  TRIAGE_SYSTEM_PROMPT,
   buildSpecificationPrompt,
   readAttachmentContents,
 } from "./triage.js";
@@ -171,6 +172,46 @@ describe("buildSpecificationPrompt", () => {
 
     expect(prompt).toContain("(none)");
   });
+
+  it("includes proactive subtask guidance when breakdown was not explicitly requested", () => {
+    const prompt = buildSpecificationPrompt(
+      baseTask,
+      ".kb/tasks/KB-001/PROMPT.md",
+    );
+
+    expect(prompt).toContain("## Subtask Consideration");
+    expect(prompt).toContain("Size M or L");
+    expect(prompt).toContain("Subtask creation is OPTIONAL");
+    expect(prompt).not.toContain("## Subtask Breakdown Requested");
+  });
+
+  it("keeps explicit breakIntoSubtasks flow mandatory when requested", () => {
+    const prompt = buildSpecificationPrompt(
+      {
+        ...baseTask,
+        breakIntoSubtasks: true,
+      },
+      ".kb/tasks/KB-001/PROMPT.md",
+    );
+
+    expect(prompt).toContain("## Subtask Breakdown Requested");
+    expect(prompt).toContain("If splitting: use the \\\`task_create\\\` tool");
+    expect(prompt).not.toContain("## Subtask Consideration");
+  });
+});
+
+describe("TRIAGE_SYSTEM_PROMPT", () => {
+  it("includes proactive M/L subtask breakdown guidance", () => {
+    expect(TRIAGE_SYSTEM_PROMPT).toContain(
+      "## Proactive Subtask Breakdown for M/L Tasks",
+    );
+    expect(TRIAGE_SYSTEM_PROMPT).toContain(
+      "Even when `breakIntoSubtasks` is not set to `true`",
+    );
+    expect(TRIAGE_SYSTEM_PROMPT).toContain(
+      "Size S tasks should generally NOT be split",
+    );
+  });
 });
 
 describe("readAttachmentContents", () => {

packages/engine/src/triage.ts

@@ -22,7 +22,7 @@ import {
   type UsageLimitPauser,
 } from "./usage-limit-detector.js";
 
-const TRIAGE_SYSTEM_PROMPT = `You are a task specification agent for "kb", an AI-orchestrated task board.
+export const TRIAGE_SYSTEM_PROMPT = `You are a task specification agent for "kb", an AI-orchestrated task board.
 
 Your job: take a rough task description and produce a fully specified PROMPT.md that another AI agent can execute autonomously in a fresh context with zero memory of this conversation.
 
@@ -157,6 +157,15 @@ When the task includes \`breakIntoSubtasks: true\`, first decide whether it shou
 - If splitting: use the \`task_create\` tool to create child tasks in triage, include clear descriptions and dependencies between them, then stop. Do NOT write a PROMPT.md for the parent task.
 - If not splitting: proceed with a normal PROMPT.md specification.
 
+## Proactive Subtask Breakdown for M/L Tasks
+For tasks you assess as Size M or L, proactively consider whether optional subtask breakdown would improve execution.
+
+- Even when \`breakIntoSubtasks\` is not set to \`true\`, you should evaluate whether splitting into 2-5 child tasks would improve work organization, handoff clarity, or parallel execution.
+- Treat this as a suggestion, not a requirement: only propose splitting when the work is meaningfully decomposable and the parent task would otherwise remain a coherent medium/large effort.
+- Keep explicit user intent first: when \`breakIntoSubtasks: true\`, follow the mandatory breakdown flow above.
+- Size S tasks should generally NOT be split because the overhead usually outweighs the benefit.
+- If you decide not to split an M/L task, proceed with a normal PROMPT.md specification.
+
 ## Triage tools
 You have these extra tools during triage:
 - \`task_list\` — list existing active tasks
@@ -1144,6 +1153,17 @@ The user has requested that this task be broken into smaller subtasks if it is c
 5. If NOT splitting: proceed with a normal PROMPT.md specification for this task
 
 **Important:** If you create subtasks, this parent task will be closed and replaced by the children. Make sure each child is a complete, executable task.`;
+  } else {
+    subtaskSection = `
+
+## Subtask Consideration
+The user did not explicitly request subtask breakdown, so you should first assess the likely task size and complexity.
+
+- If the work appears to be Size M or L, consider whether optionally splitting it into 2-5 child tasks would improve organization, dependency clarity, or parallel execution.
+- Subtask creation is OPTIONAL in this case — only split when it provides a clear benefit.
+- If you choose to split: use the \\\`task_create\\\` tool to create the child tasks, set dependencies where needed, and then stop without writing a PROMPT.md for the parent task.
+- If the work appears to be Size S, or if an M/L task is still best handled as one coherent unit, do NOT split and proceed with a normal PROMPT.md specification.
+- If size is uncertain at first, make a quick assessment from the available context before deciding whether to suggest a breakdown.`;
   }
 
   return `${isRevision ? "Revise" : "Specify"} this task and write the result to \`${promptPath}\`.