kanbango 2.4.0 → 3.0.2

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,37 @@ 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', 'help'],
+              description: 'list=scan board; show=one task (needs task_id); help=token playbook (no board I/O)',
               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'."
             },
             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 group'
             },
             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 +326,61 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'kanban_manage',
-        description: 'Mutate tasks and accepted plans. Required fields by action: create -> title; move -> task_id + column; update -> task_id plus patch or field shortcuts; plan_create -> title; plan_advance/plan_done/plan_status -> task_id; plan_evidence -> task_id + diff + test_command + stdout + stderr + exit_code. Example create: {"action":"create","title":"Ship Docker image","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', 'plan_create', 'plan_advance', 'plan_evidence', 'plan_done', 'plan_status'],
+              description: 'create|move|update daily; plan_* only for accepted multi-step work with tests'
             },
             title: {
               type: 'string',
-              description: "Non-empty title. Required for 'create' and 'plan_create'."
+              description: 'Required for create and plan_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 group (create/update/plan_create)'
             },
             description: {
               type: 'string',
-              description: "High-level context for 'create', 'update', or 'plan_create'."
+              description: 'Why/context (recommended on create)'
             },
             specs: {
               type: 'string',
-              description: "Technical constraints, APIs, and edge cases for 'create', 'update', or 'plan_create'."
+              description: 'Technical constraints (recommended on create)'
             },
             in_scope: {
               type: 'array',
-              description: "What this task includes for 'create', 'update', or 'plan_create'.",
+              description: 'In-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             out_of_scope: {
               type: 'array',
-              description: "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: "Completion requirements for 'create', 'update', or 'plan_create'.",
+              description: 'Done criteria (recommended on create)',
               items: { type: 'string' }
             },
             test_cases: {
               type: 'array',
-              description: "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 +393,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 response size. Prefer none. Default summary. create always returns full task 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 +453,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,6 +484,12 @@ 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') {
@@ -492,7 +515,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         } else {
           throw invalidRequest(
             `Unknown operation: ${operation}`,
-            'Use one of: list, show',
+            'Use one of: list, show, help',
             { operation }
           );
         }
@@ -505,7 +528,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         switch (action) {
           case 'create': {
-            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', {
+            const createPayload = {
               description: args.description,
               specs: args.specs,
               in_scope: args.in_scope,
@@ -514,8 +537,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               test_cases: args.test_cases,
               subtasks: args.subtasks,
               notes: args.notes
-            });
-            result = kanban.shapeTask(created, { view: 'full' });
+            };
+            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', createPayload);
+            const shaped = kanban.shapeTask(created, { view: 'full' });
+            const warnings = kanban.createFieldWarnings(createPayload);
+            result = warnings.length > 0
+              ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
+              : shaped;
             break;
           }
 
@@ -564,9 +592,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
 
-          case 'plan_create':
+          case 'plan_create': {
             result = await plan.create(args);
+            const planWarnings = kanban.createFieldWarnings(args);
+            if (planWarnings.length > 0 && result && typeof result === 'object') {
+              result = {
+                ...result,
+                warnings: planWarnings,
+                missing_recommended: kanban.missingRecommendedCreateFields(args)
+              };
+            }
             break;
+          }
           case 'plan_advance':
             result = await plan.advance({ task_id: args.task_id, index: args.index });
             break;
@@ -642,9 +679,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 {
@@ -653,7 +691,7 @@ function installGuiShutdownHooks() {
   }
 
   process.once('exit', () => {
-    if (guiProcess && guiProcess.exitCode === null) {
+    if (ownsGuiProcess()) {
       try {
         guiProcess.kill();
       } catch {
@@ -662,10 +700,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));
   });
 }
 
@@ -685,7 +723,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.4.0",
+  "version": "3.0.2",
   "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,5 @@ 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');