kanbango 2.5.0 → 3.1.0

package/mcp-server.js

@@ -8,6 +8,8 @@ const path = require('path');
 const pkg = require('./package.json');
 const kanban = require('./kanban.js');
 const plan = require('./plan.js');
+const guiRegistry = require('./gui-registry.js');
+const playbook = require('./agent-playbook.js');
 
 const COLS = kanban.COLS;
 const READ_VIEWS = Object.keys(kanban.VIEW_FIELDS);
@@ -17,7 +19,11 @@ let guiProcess = null;
 let guiPort = null;
 
 function normalizePort(value) {
-  return kanban.normalizeGuiPort(value);
+  return guiRegistry.normalizeGuiPort(value);
+}
+
+function ownsGuiProcess() {
+  return Boolean(guiProcess && guiProcess.exitCode === null);
 }
 
 function sleep(ms) {
@@ -41,7 +47,7 @@ async function waitForGuiReady(pid, timeoutMs = GUI_READY_TIMEOUT_MS) {
       );
     }
 
-    const info = await kanban.discoverRunningGui();
+    const info = await guiRegistry.discoverRunningGui();
     if (info && info.pid === pid) return info;
 
     await sleep(GUI_READY_POLL_MS);
@@ -145,27 +151,28 @@ async function startGuiServer(port) {
     throw invalidRequest('Invalid port', 'Use an integer between 1 and 65535', { port });
   }
 
-  if (guiProcess && guiProcess.exitCode === null && guiPort) {
+  if (ownsGuiProcess() && guiPort) {
     return {
       status: 'already_running',
+      owned: true,
       port: guiPort,
       pid: guiProcess.pid,
       url: `http://localhost:${guiPort}`
     };
   }
 
-  const existing = await kanban.discoverRunningGui();
+  const existing = await guiRegistry.discoverRunningGui();
   if (existing) {
-    guiPort = existing.port;
     return {
       status: 'already_running',
+      owned: false,
       port: existing.port,
       pid: existing.pid,
       url: existing.url
     };
   }
 
-  const desiredPort = kanban.resolvePreferredGuiPort(port);
+  const desiredPort = guiRegistry.resolvePreferredGuiPort(port);
   await kanban.ensureBacklogDir();
 
   const scriptPath = path.join(__dirname, 'bin', 'kanban.js');
@@ -189,6 +196,7 @@ async function startGuiServer(port) {
 
   return {
     status: 'started',
+    owned: true,
     port: ready.port,
     pid: ready.pid,
     url: ready.url
@@ -196,61 +204,70 @@ async function startGuiServer(port) {
 }
 
 async function stopGuiServer() {
-  const trackedRunning = guiProcess && guiProcess.exitCode === null;
-  const discovered = trackedRunning ? null : await kanban.discoverRunningGui();
-
-  if (!trackedRunning && !discovered) {
-    guiProcess = null;
-    guiPort = null;
-    return { status: 'not_running' };
-  }
-
-  const port = trackedRunning ? guiPort : discovered.port;
-  const pid = trackedRunning ? guiProcess.pid : discovered.pid;
-
-  if (trackedRunning) {
+  if (ownsGuiProcess()) {
+    const port = guiPort;
+    const pid = guiProcess.pid;
     guiProcess.kill();
-  } else if (pid) {
-    try {
-      process.kill(pid, 'SIGTERM');
-    } catch {
-      // process may already be gone
+
+    const deadline = Date.now() + 2000;
+    while (Date.now() < deadline) {
+      const still = await guiRegistry.discoverRunningGui();
+      if (!still || still.pid !== pid) break;
+      await sleep(50);
     }
-  }
 
-  const deadline = Date.now() + 2000;
-  while (Date.now() < deadline) {
-    const still = await kanban.discoverRunningGui();
-    if (!still || still.pid !== pid) break;
-    await sleep(50);
+    await guiRegistry.clearGuiPortFile({ force: true });
+    guiProcess = null;
+    guiPort = null;
+    return { status: 'stopping', owned: true, port, pid };
   }
 
-  await kanban.clearGuiPortFile({ force: true });
   guiProcess = null;
   guiPort = null;
 
-  return { status: 'stopping', port, pid };
+  const discovered = await guiRegistry.discoverRunningGui();
+  if (!discovered) {
+    return { status: 'not_running' };
+  }
+
+  return {
+    status: 'external_running',
+    owned: false,
+    port: discovered.port,
+    pid: discovered.pid,
+    url: discovered.url,
+    hint: 'GUI was not started by this MCP process; stop refused. Stop it from the owning terminal or kill that PID manually.'
+  };
 }
 
 async function guiStatus() {
-  if (guiProcess && guiProcess.exitCode === null && guiPort) {
+  if (ownsGuiProcess() && guiPort) {
     return {
       status: 'running',
+      owned: true,
       port: guiPort,
       pid: guiProcess.pid,
       url: `http://localhost:${guiPort}`
     };
   }
 
-  const discovered = await kanban.discoverRunningGui();
+  guiProcess = null;
+  guiPort = null;
+
+  const discovered = await guiRegistry.discoverRunningGui();
   if (!discovered) {
-    guiProcess = null;
-    guiPort = null;
     return { status: 'not_running' };
   }
 
-  guiPort = discovered.port;
-  return discovered;
+  return {
+    status: 'external_running',
+    owned: false,
+    port: discovered.port,
+    pid: discovered.pid,
+    url: discovered.url,
+    cwd: discovered.cwd,
+    started_at: discovered.started_at
+  };
 }
 
 const server = new Server(
@@ -270,37 +287,41 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: 'kanban_read',
-        description: 'Read tasks from the board. operation=list returns multiple tasks with optional col/epic filters. operation=show requires task_id. Use view for preset payload sizes or fields for exact field selection.',
+        description: playbook.TOOL_DESCRIPTIONS.kanban_read,
         inputSchema: {
           type: 'object',
           properties: {
             operation: {
               type: 'string',
-              enum: ['list', 'show'],
-              description: "Operation to perform: 'list' for all tasks, 'show' for a specific task",
+              enum: ['list', 'show', 'list_epics', 'show_epic', 'help'],
+              description: 'list/show=tasks; list_epics/show_epic=initiative containers; help=token playbook',
               default: 'list'
             },
             task_id: {
               type: 'string',
-                description: "Task ID (optional for 'list', required for 'show'). Use a numeric ID like '014' or just a number like '14'."
+              description: "Required for show. Numeric id: '014' or '14'."
+            },
+            epic_id: {
+              type: 'string',
+              description: "Required for show_epic. Epic id like 'E001'."
             },
             col: {
               type: 'string',
               enum: COLS,
-              description: 'Optional column filter for list'
+              description: 'Filter list by column (saves tokens — prefer this)'
             },
             epic: {
               type: 'string',
-              description: 'Optional epic group filter for list'
+              description: 'Filter list by epic id or title'
             },
             view: {
               type: 'string',
               enum: READ_VIEWS,
-              description: 'Preset response view. Defaults to summary.'
+              description: 'summary=board scan (default); planning=scope/AC; execution=+subtasks; full=everything. Prefer smallest that works.'
             },
             fields: {
               type: 'array',
-              description: 'Explicit fields to return. When provided, fields override view.',
+              description: 'Exact fields only (overrides view). Use when you need 1–2 fields.',
               items: { type: 'string' }
             }
           },
@@ -309,61 +330,80 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'kanban_manage',
-        description: 'Mutate tasks and accepted plans. Required by action: create/plan_create -> title only; move -> task_id + column; update -> task_id + patch/shortcuts; plan_advance/plan_done/plan_status -> task_id; plan_evidence -> task_id + diff + test_command + stdout + stderr + exit_code. Strongly recommended on create/plan_create: description, specs, in_scope, out_of_scope, acceptance_criteria (missing fields return warnings, not errors). Example: {"action":"create","title":"Ship Docker image","description":"...","specs":"...","in_scope":["CLI"],"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned","epic":"Release"}.',
+        description: playbook.TOOL_DESCRIPTIONS.kanban_manage,
         inputSchema: {
           type: 'object',
           properties: {
             action: {
               type: 'string',
-               enum: ['create', 'move', 'update', 'plan_create', 'plan_advance', 'plan_evidence', 'plan_done', 'plan_status'],
-               description: 'Create, move, update, or operate the accepted-plan workflow'
+              enum: [
+                'create',
+                'move',
+                'update',
+                'epic_create',
+                'epic_update',
+                'plan_create',
+                'plan_advance',
+                'plan_evidence',
+                'plan_done',
+                'plan_status'
+              ],
+              description: 'create|move|update daily; epic_create|epic_update for containers; plan_* for multi-step work'
             },
             title: {
               type: 'string',
-              description: "Non-empty title. Required for 'create' and 'plan_create'."
+              description: 'Required for create, plan_create, epic_create'
             },
             col: {
               type: 'string',
               enum: COLS,
               default: 'planned',
-              description: "Column for 'create' or shortcut patch field for 'update' (default: 'planned')."
+              description: 'create column, or update shortcut for column'
             },
             epic: {
               type: 'string',
               default: '—',
-              description: "Epic group for 'create', 'update', or 'plan_create' (optional)."
+              description: 'Epic id or title (create/update/plan_create). Prefer E001.'
+            },
+            epic_id: {
+              type: 'string',
+              description: 'Required for epic_update; optional filter/link id'
             },
             description: {
               type: 'string',
-              description: "Strongly recommended. High-level context/why for 'create', 'update', or 'plan_create'."
+              description: 'Why/context (recommended on create / epic_create)'
+            },
+            goals: {
+              type: 'string',
+              description: 'Epic outcome one-liner (recommended on epic_create)'
             },
             specs: {
               type: 'string',
-              description: "Strongly recommended. Technical constraints, APIs, and edge cases for 'create', 'update', or 'plan_create'."
+              description: 'Technical constraints (recommended on create)'
             },
             in_scope: {
               type: 'array',
-              description: "Strongly recommended. What this task includes (boundaries) for 'create', 'update', or 'plan_create'.",
+              description: 'In-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             out_of_scope: {
               type: 'array',
-              description: "Strongly recommended. Explicit non-goals / exclusions for 'create', 'update', or 'plan_create'.",
+              description: 'Out-of-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             acceptance_criteria: {
               type: 'array',
-              description: "Strongly recommended. Completion requirements for 'create', 'update', or 'plan_create'.",
+              description: 'Done criteria (recommended on create)',
               items: { type: 'string' }
             },
             test_cases: {
               type: 'array',
-              description: "Recommended. Verification scenarios for 'create', 'update', or 'plan_create'.",
+              description: 'Verification scenarios',
               items: { type: 'string' }
             },
             subtasks: {
               type: 'array',
-              description: "Optional subtask list for 'create', 'update', or internally generated by 'plan_create'.",
+              description: 'Full subtask list replace on update (send complete array, not a single toggle)',
               items: {
                 type: 'object',
                 properties: {
@@ -376,58 +416,58 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             notes: {
               type: 'string',
-              description: "Optional freeform notes for 'create', 'update', or 'plan_create'."
+              description: 'Freeform notes'
             },
             task_id: {
               type: 'string',
-                description: "Task ID required for 'move', 'update', and all plan_* actions except 'plan_create'. Use '014' or '14'."
+              description: "Required for move/update/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
               enum: COLS,
-              description: "Target column required for 'move'."
+              description: 'Target column for move (not col)'
             },
             patch: {
               type: 'object',
-              description: "Patch payload for 'update'. Use this for bulk field changes; top-level shortcuts are merged into the patch."
+              description: 'Bulk update object; merged with top-level field shortcuts'
             },
             return: {
               type: 'string',
               enum: ['none', 'summary', 'full'],
-              description: "Response shape for 'move' and 'update'. Defaults to summary. 'create' returns the full created task."
+              description: 'move/update/epic_update response size. Prefer none. Default summary. create/epic_create return full once.'
             },
             index: {
               type: 'integer',
-              description: "Zero-based plan subtask index for 'plan_advance'. Defaults to the first incomplete step when omitted."
+              description: 'plan_advance: subtask index; omit = first incomplete'
             },
             steps: {
               type: 'array',
               items: { type: 'string' },
-              description: "Implementation steps inserted between the default plan workflow steps for 'plan_create'."
+              description: 'plan_create: implementation steps between red/green test steps'
             },
             project_root: {
               type: 'string',
-              description: "Project root used for test runner detection in 'plan_create'. Defaults to the MCP server working directory."
+              description: 'plan_create: root for test-runner detect (default cwd)'
             },
             diff: {
               type: 'string',
-              description: "Required for 'plan_evidence'. Include the relevant code diff or summary."
+              description: 'plan_evidence: short diff or summary (not whole repo)'
             },
             test_command: {
               type: 'string',
-              description: "Required for 'plan_evidence'. The exact verification command that was run."
+              description: 'plan_evidence: exact command run'
             },
             stdout: {
               type: 'string',
-              description: "Required for 'plan_evidence'. Captured standard output from the verification command."
+              description: 'plan_evidence: test stdout (truncate to last ~2KB if huge)'
             },
             stderr: {
               type: 'string',
-              description: "Required for 'plan_evidence'. Captured standard error from the verification command."
+              description: 'plan_evidence: test stderr (truncate if huge)'
             },
             exit_code: {
               type: 'integer',
-              description: "Required for 'plan_evidence'. Integer process exit code from the verification command."
+              description: 'plan_evidence: process exit code'
             }
           },
           required: ['action'],
@@ -436,18 +476,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'kanban_gui',
-        description: 'Control the web GUI server: start, stop, or check status.',
+        description: playbook.TOOL_DESCRIPTIONS.kanban_gui,
         inputSchema: {
           type: 'object',
           properties: {
             action: {
               type: 'string',
               enum: ['start', 'stop', 'status'],
-              description: "Action to perform: 'start' launches GUI, 'stop' kills it, 'status' checks if running"
+              description: 'start | stop (owned only) | status'
             },
             port: {
               type: 'integer',
-              description: "Port for the GUI server (only for 'start'). Defaults to KANBANGO_GUI_PORT or a stable hash of the project cwd (5510-5999)."
+              description: 'Optional start port; else KANBANGO_GUI_PORT or stable 5510-5999'
             }
           },
           required: ['action'],
@@ -467,15 +507,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     switch (name) {
       case 'kanban_read': {
         const operation = args.operation || 'list';
+
+        if (operation === 'help') {
+          result = playbook.playbookHelpPayload();
+          break;
+        }
+
         const readOptions = normalizeReadOptions(args, 'summary');
 
         if (operation === 'list') {
-          let tasks = await kanban.allEpics();
+          await kanban.migrateEpicGroups();
+          let tasks = await kanban.allTasks();
           if (args.col) {
             tasks = tasks.filter((task) => task.column === args.col);
           }
-          if (args.epic) {
-            tasks = tasks.filter((task) => task.epic_group === args.epic);
+          if (args.epic || args.epic_id) {
+            const filter = args.epic_id || args.epic;
+            tasks = tasks.filter((task) => kanban.taskMatchesEpicFilter(task, filter));
           }
 
           result = tasks.map((task) => kanban.shapeTask(task, readOptions));
@@ -489,10 +537,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
 
           result = kanban.shapeTask(await kanban.getTask(args.task_id), readOptions);
+        } else if (operation === 'list_epics') {
+          await kanban.migrateEpicGroups();
+          const tasks = await kanban.allTasks();
+          const epics = await kanban.listEpicEntities();
+          const epicView = args.view === 'full' || args.view === 'planning' || args.view === 'execution'
+            ? (args.view === 'execution' ? 'planning' : args.view)
+            : 'summary';
+          result = epics.map((epic) => kanban.shapeEpic(epic, tasks, {
+            view: Array.isArray(args.fields) && args.fields.length > 0 ? undefined : epicView,
+            fields: args.fields
+          }));
+        } else if (operation === 'show_epic') {
+          const epicRef = args.epic_id || args.epic;
+          if (!epicRef) {
+            throw invalidRequest(
+              "epic_id is required for 'show_epic' operation",
+              'Provide an epic id like E001',
+              { operation }
+            );
+          }
+          await kanban.migrateEpicGroups();
+          const link = await kanban.resolveEpicRef(epicRef, { createIfMissing: false });
+          const epic = await kanban.getEpicEntity(link.epic_id);
+          const tasks = await kanban.allTasks();
+          result = kanban.shapeEpic(epic, tasks, {
+            view: args.view || 'full',
+            fields: args.fields
+          });
         } else {
           throw invalidRequest(
             `Unknown operation: ${operation}`,
-            'Use one of: list, show',
+            'Use one of: list, show, list_epics, show_epic, help',
             { operation }
           );
         }
@@ -515,7 +591,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               subtasks: args.subtasks,
               notes: args.notes
             };
-            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', createPayload);
+            const epicRef = args.epic_id || args.epic || '—';
+            const created = await kanban.doCreate(args.title, args.col || 'planned', epicRef, createPayload);
             const shaped = kanban.shapeTask(created, { view: 'full' });
             const warnings = kanban.createFieldWarnings(createPayload);
             result = warnings.length > 0
@@ -524,6 +601,54 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
 
+          case 'epic_create': {
+            const epicPayload = {
+              description: args.description,
+              goals: args.goals,
+              in_scope: args.in_scope,
+              out_of_scope: args.out_of_scope,
+              notes: args.notes
+            };
+            const createdEpic = await kanban.doCreateEpic(args.title, epicPayload);
+            const shapedEpic = kanban.shapeEpic(createdEpic, [], { view: 'full' });
+            const epicWarnings = kanban.createEpicFieldWarnings(epicPayload);
+            result = epicWarnings.length > 0
+              ? {
+                ...shapedEpic,
+                warnings: epicWarnings,
+                missing_recommended: kanban.missingRecommendedEpicCreateFields(epicPayload)
+              }
+              : shapedEpic;
+            break;
+          }
+
+          case 'epic_update': {
+            const epicId = args.epic_id || args.epic;
+            if (!epicId) {
+              throw invalidRequest(
+                "epic_id is required for 'epic_update'",
+                'Provide an epic id like E001',
+                { action }
+              );
+            }
+            const epicPatch = args.patch ? { ...args.patch } : {};
+            if (args.title !== undefined) epicPatch.title = args.title;
+            if (args.description !== undefined) epicPatch.description = args.description;
+            if (args.goals !== undefined) epicPatch.goals = args.goals;
+            if (args.in_scope !== undefined) epicPatch.in_scope = args.in_scope;
+            if (args.out_of_scope !== undefined) epicPatch.out_of_scope = args.out_of_scope;
+            if (args.notes !== undefined) epicPatch.notes = args.notes;
+            const updatedEpic = await kanban.updateEpicEntity(epicId, epicPatch);
+            if (returnShape === 'none') {
+              result = { ok: true, epic_id: updatedEpic.id };
+            } else if (returnShape === 'summary') {
+              result = kanban.shapeEpic(updatedEpic, await kanban.allTasks(), { view: 'summary' });
+            } else {
+              result = kanban.shapeEpic(updatedEpic, await kanban.allTasks(), { view: 'full' });
+            }
+            break;
+          }
+
           case 'move': {
             if (!args.task_id) {
               throw invalidRequest(
@@ -562,7 +687,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (args.test_cases !== undefined) patch.test_cases = args.test_cases;
             if (args.subtasks !== undefined) patch.subtasks = args.subtasks;
             if (args.notes !== undefined) patch.notes = args.notes;
-            if (args.epic !== undefined) patch.epic_group = args.epic;
+            if (args.epic_id !== undefined) patch.epic_id = args.epic_id;
+            else if (args.epic !== undefined) patch.epic = args.epic;
             if (args.col !== undefined) patch.column = args.col;
             const updated = await kanban.updateTask(args.task_id, patch);
             result = formatTaskResult(updated, returnShape);
@@ -597,7 +723,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           default:
             throw invalidRequest(
               `Unknown action: ${action}`,
-              'Use create, move, update, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
+              'Use create, move, update, epic_create, epic_update, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
               { action }
             );
         }
@@ -656,9 +782,10 @@ async function maybeAutoStartGui() {
 function installGuiShutdownHooks() {
   let shuttingDown = false;
 
-  async function shutdown() {
+  async function shutdownOwnedGui() {
     if (shuttingDown) return;
     shuttingDown = true;
+    if (!ownsGuiProcess()) return;
     try {
       await stopGuiServer();
     } catch {
@@ -667,7 +794,7 @@ function installGuiShutdownHooks() {
   }
 
   process.once('exit', () => {
-    if (guiProcess && guiProcess.exitCode === null) {
+    if (ownsGuiProcess()) {
       try {
         guiProcess.kill();
       } catch {
@@ -676,10 +803,10 @@ function installGuiShutdownHooks() {
     }
   });
   process.once('SIGINT', () => {
-    shutdown().finally(() => process.exit(0));
+    shutdownOwnedGui().finally(() => process.exit(0));
   });
   process.once('SIGTERM', () => {
-    shutdown().finally(() => process.exit(0));
+    shutdownOwnedGui().finally(() => process.exit(0));
   });
 }
 
@@ -699,7 +826,8 @@ module.exports = {
   startGuiServer,
   stopGuiServer,
   guiStatus,
-  resolvePreferredGuiPort: kanban.resolvePreferredGuiPort,
+  resolvePreferredGuiPort: guiRegistry.resolvePreferredGuiPort,
+  playbook,
   server,
   main
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "2.5.0",
+  "version": "3.1.0",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {

package/plan.js

@@ -147,7 +147,7 @@ async function done(payload = {}) {
     throw planError('PLAN_INCOMPLETE', 'Plan has incomplete subtasks',
       'Advance every plan step before marking the workflow done', { incomplete });
   }
-  const updated = await kanban.updateTask(task.id, { column: 'done', plan: { ...(task.plan || {}), status: 'done' } });
+  const updated = await kanban.updateTask(task.id, { column: 'done', plan: { ...task.plan, status: 'done' } });
   return result(updated, { status: 'done' });
 }
 

package/tests/run.js

@@ -18,3 +18,6 @@ runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks test');
 runNode(path.join('tests', 'read-views.test.js'), [], 'Read views test');
 runNode(path.join('tests', 'mcp-server.test.js'), [], 'MCP server test');
 runNode(path.join('tests', 'gui-port.test.js'), [], 'GUI port test');
+runNode(path.join('tests', 'plan-workflow.test.js'), [], 'Plan workflow test');
+runNode(path.join('tests', 'agent-playbook.test.js'), [], 'Agent playbook test');
+runNode(path.join('tests', 'epics.test.js'), [], 'Epics test');