kanbango 2.5.0 → 3.0.2

package/.ai/lessons.jsonl

@@ -0,0 +1,4 @@
+{"id":"260729-3h4","ts":"2026-07-29","scope":"proj","tags":["tests","mcp","cli","review"],"rule":"DO Add automated tests for every new public CLI/MCP workflow before shipping","when":"api-review","sev":2,"hits":1}
+{"id":"260729-1ur","ts":"2026-07-29","scope":"proj","tags":["javascript","objects"],"rule":"DON'T Use empty object fallbacks in spreads like `...(obj || {})` since spreading falsy is safe","when":"object spread","sev":2,"hits":1}
+{"id":"260729-5eo","ts":"2026-07-29","scope":"proj","tags":["processes","mcp","ownership"],"rule":"DO Track process ownership before stopping or cleaning up discovered services","when":"gui-process management","sev":2,"hits":1}
+{"id":"260729-1ch","ts":"2026-07-29","scope":"proj","tags":["gui","process","mcp"],"rule":"DO GUI/MCP stop must only SIGTERM processes spawned by the current process; treat port-file PIDs as external_running","when":"gui-process management","sev":2,"hits":1}

package/.ai/retro/last-run.json

@@ -1 +1 @@
-{"ts":"2026-07-29T09:29:19.070Z","sessionID":"ses_05beb2173ffe1rCJQhZBUHuLgs","added":[],"bumped":[],"error":"llm-parse-fallback"}
+{"ts":"2026-07-29T10:38:42.184Z","sessionID":"ses_052c1be3fffeNPoV7VO6z40X2I","added":["260729-1ch"],"bumped":[]}

package/AGENTS.md

@@ -2,6 +2,17 @@
 
 This document provides build commands, testing procedures, and code style guidelines for working with the kanbango codebase.
 
+## Kanbango MCP — token rules (when using this board)
+
+Source of truth: `agent-playbook.js` (also MCP tool descriptions + `kanban_read` `operation=help`).
+
+- list: `col` filter, `view=summary`; keep `task_id`s; no full-board re-list after every write
+- show: `view=execution` while coding; `full` only if needed
+- create once with `description`, `specs`, `in_scope`, `out_of_scope`, `acceptance_criteria`
+- move/update: `return=none`; subtasks = full array replace (no toggle)
+- non-trivial work: `plan_create` → `plan_advance` → `plan_evidence` (real tests, truncated logs) → `plan_done`
+- gui: `status` before `start`; `stop` only owned; `external_running` = do not kill
+
 ## Build & Development Commands
 
 ### Available Scripts

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to kanbango will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.2] - 2026-07-29
+
+### Added
+- `agent-playbook.js` — single source of truth for agent token rules
+- `kanban_read` `operation=help` returns the playbook (no board I/O)
+- Test that `tools/list` descriptions match the playbook module
+
+### Changed
+- MCP tool descriptions are loaded from `agent-playbook.js` (not duplicated prose)
+- `LLM_AGENTS.md` clarified as human setup docs; agents rely on tool descriptions
+
+## [3.0.1] - 2026-07-29
+
+### Changed
+- MCP tool descriptions encode a token-efficient agent playbook (cheap list/show, fat create once, `return=none`, plan_* only when needed, GUI ownership)
+- `LLM_AGENTS.md`, `AGENTS.md`, and `README.md` document the same rules for project-scoped agents
+
+## [3.0.0] - 2026-07-29
+
+### Breaking
+- New task IDs are zero-padded numeric strings (`001`), not `PI-001-slug`
+- MCP/CLI `toggle` removed; update the full `subtasks` list via `update`
+- Legacy task field alias `tasks` removed; use `subtasks` only
+- `kanban_gui` `stop` only stops a GUI **spawned by the current MCP process**. An external GUI returns `status: "external_running"` and is **not** sent SIGTERM (PID-reuse safety)
+- `kanban_gui` `status` may return `running` (owned), `external_running` (discovered), or `not_running`
+
+### Added
+- Accepted-plan workflow: `plan.js` + CLI `kanban plan <action> --json` + MCP `plan_*` actions on `kanban_manage`
+- `gui-registry.js` — GUI port file, preferred port, discover helpers (extracted from `kanban.js`)
+- Regression tests for plan workflow and GUI process ownership
+
+### Changed
+- Create field policy: only `title` is hard-required; `description`, `specs`, `in_scope`, `out_of_scope`, and `acceptance_criteria` are strongly recommended
+- MCP `kanban_manage` create/plan_create returns `warnings` + `missing_recommended` when recommended fields are omitted (still succeeds)
+- MCP tool descriptions and LLM agent docs push agents to always fill planning boundaries
+
 ## [2.5.0] - 2026-07-27
 
 ### Changed

package/LLM_AGENTS.md

@@ -1,6 +1,12 @@
 # MCP Server Guide for LLM Agents
 
-Complete guide for integrating kanbango MCP server into LLM agents and AI assistants.
+Human-oriented setup guide. **Agents do not load this file automatically.**
+
+Canonical usage rules live in code (`agent-playbook.js`) and are injected into MCP
+`tools/list` descriptions. After install, the agent only needs the MCP server —
+not this markdown.
+
+Optional refresh in-session: `kanban_read` with `operation: "help"`.
 
 ## Quick Integration
 
@@ -63,11 +69,12 @@ Read tasks from kanban board. Can list all tasks, filter by column/epic, or get
 **Operations:**
 - `list` - Get all tasks (with optional filters)
 - `show` - Get specific task details
+- `help` - Return token playbook from `agent-playbook.js` (no board I/O)
 
 **Parameters:**
 ```json
 {
-  "operation": "list",  // "list" or "show"
+  "operation": "list",  // "list" | "show" | "help"
   "task_id": "014",  // Required for "show"
   "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done"
   "epic": "Phase 1"  // Optional: filter by epic group
@@ -232,6 +239,11 @@ Patch-update task fields:
 
 Control the web GUI server: start, stop, or check status.
 
+**Ownership (important):**
+- `stop` only sends SIGTERM to a GUI **spawned by this MCP process** (`owned: true`).
+- If the GUI was started elsewhere (CLI `kanban serve`, another MCP), `stop` returns `external_running` and does **not** kill that PID.
+- `status` distinguishes `running` (owned), `external_running` (discovered via port file), and `not_running`.
+
 **Port resolution (start):**
 1. Explicit `port` argument, if provided
 2. Else `KANBANGO_GUI_PORT` env
@@ -242,9 +254,9 @@ If the preferred port is busy, the server picks the next free port. Always trust
 **Auto-start with MCP:** set `KANBANGO_AUTO_GUI=1` in the MCP server env. GUI starts when MCP starts; use `status` to read the URL.
 
 **Actions:**
-- `start` - Launch the GUI server
-- `stop` - Kill the GUI server
-- `status` - Check if the GUI is running (reads live process or port file)
+- `start` - Launch the GUI server (or report already_running owned/external)
+- `stop` - Stop only MCP-owned GUI
+- `status` - Check GUI state
 
 **Parameters:**
 ```json
@@ -289,31 +301,57 @@ Check status:
 ```json
 {
   "status": "started",
+  "owned": true,
   "port": 5623,
   "pid": 12345,
   "url": "http://localhost:5623"
 }
 ```
 
-**Response (stop):**
+**Response (stop - owned):**
 ```json
 {
   "status": "stopping",
+  "owned": true,
   "port": 5623,
   "pid": 12345
 }
 ```
 
-**Response (status - running):**
+**Response (stop - external refused):**
+```json
+{
+  "status": "external_running",
+  "owned": false,
+  "port": 5623,
+  "pid": 12345,
+  "url": "http://localhost:5623",
+  "hint": "GUI was not started by this MCP process; stop refused."
+}
+```
+
+**Response (status - running owned):**
 ```json
 {
   "status": "running",
+  "owned": true,
   "port": 5623,
   "pid": 12345,
   "url": "http://localhost:5623"
 }
 ```
 
+**Response (status - external):**
+```json
+{
+  "status": "external_running",
+  "owned": false,
+  "port": 5623,
+  "pid": 99999,
+  "url": "http://localhost:5623"
+}
+```
+
 **Response (status - not running):**
 ```json
 {
@@ -426,17 +464,34 @@ Check status:
 
 ---
 
-## Best Practices for LLM Agents
-
-1. **Always use `kanban_read` first** - Discover existing tasks before creating new ones
-2. **Numeric task lookup** - Task IDs are zero-padded numbers (e.g. `"035"`). Unpadded numbers such as `"35"` also work in any `task_id` parameter.
-3. **Use `col` filter** - Narrow down to relevant column when listing
-4. **Use `epic` grouping** - Organize tasks by features/phases
-5. **Create with planning fields** - Always include description, specs, in_scope, out_of_scope, acceptance_criteria; treat `warnings`/`missing_recommended` as a signal to fill gaps
-6. **Work through subtasks** - Toggle each subtask as you complete them
-7. **Move tasks through workflow** - planned → active → done progression
-8. **Use `show` operation** - Get full task details including subtasks
-9. **Handle task IDs** - Always use the full task ID returned from create/show
+## Token-efficient playbook (source of truth)
+
+**Edit `agent-playbook.js` only.** MCP tool descriptions and `operation=help` are built from it.
+
+At runtime agents already receive the rules via tool descriptions. Humans can also call:
+
+```json
+{ "operation": "help" }
+```
+
+on `kanban_read` (no board I/O).
+
+### Drop-in for project `AGENTS.md` (optional)
+
+Same bullets as `DROP_IN_RULE` in `agent-playbook.js` — copy if you want them outside MCP:
+
+```text
+Kanbango MCP — token rules:
+- list: col filter, view=summary; keep task_ids; no full-board re-list after writes
+- show: view=execution while coding; full only if needed
+- create once with description,specs,in_scope,out_of_scope,acceptance_criteria
+- move/update: return=none; subtasks=full array replace
+- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done
+- gui: status before start; stop only owned; external_running = do not kill
+```
+
+### Columns
+`planned` → `active` (few at a time) → `done`. Use `icebox` for parked work.
 
 ---
 

package/README.md

@@ -129,9 +129,11 @@ Once connected, your agent gets access to these tools:
 
 | Tool | What it does |
 |------|-------------|
-| `kanban_read` | List tasks, filter by column/epic, show details |
-| `kanban_manage` | Create, move, patch-update tasks |
-| `kanban_gui` | Start, stop, or check web GUI status (returns the real URL/port) |
+| `kanban_read` | List/show tasks (`view=summary` by default — cheap) |
+| `kanban_manage` | Create, move, update, plan_* workflow |
+| `kanban_gui` | Start / status / stop (stop only kills GUI this MCP started) |
+
+**Token tip for agents:** rules ship inside MCP tool descriptions (`agent-playbook.js`). Optional: `kanban_read` → `operation: "help"`. Human setup notes: [LLM_AGENTS.md](./LLM_AGENTS.md).
 
 Your agent stays in sync with your real board — every change is persisted as JSON files.
 
@@ -146,6 +148,7 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
 | `kanban mcp-init` | Generate MCP config files |
+| `kanban plan <action> --json '{...}'` | Accepted-plan workflow (create/advance/evidence/done/status) |
 
 ## Web GUI
 

package/agent-playbook.js

@@ -0,0 +1,71 @@
+/**
+ * Single source of truth for agent-facing kanbango usage rules.
+ * MCP tool descriptions are built from this module — not from LLM_AGENTS.md.
+ * Docs may quote DROP_IN_RULE; keep them in sync by editing here only.
+ */
+
+const DROP_IN_RULE = [
+  'Kanbango MCP — token rules:',
+  '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
+  '- show: view=execution while coding; full only if needed',
+  '- create once with description,specs,in_scope,out_of_scope,acceptance_criteria',
+  '- move/update: return=none; subtasks=full array replace',
+  '- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done',
+  '- gui: status before start; stop only owned; external_running = do not kill'
+].join('\n');
+
+const TOOL_DESCRIPTIONS = {
+  kanban_read: [
+    'Read board. TOKEN RULES: list defaults to view=summary (id/title/col/progress only).',
+    'Always pass col when possible. Prefer show+view=execution over full.',
+    'Do not re-list the whole board after every write — keep task_id from create/move.',
+    'IDs are numeric ("014" or "14"). views: summary|planning|execution|full; fields[] overrides view.',
+    'operation=help returns this playbook as short text (no board I/O).'
+  ].join(' '),
+
+  kanban_manage: [
+    'Write board / plan. TOKEN RULES: one create with all planning fields beats many updates;',
+    'after write use return=none (or summary). Do not dump full task unless needed.',
+    'Actions: create|move|update (daily); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
+    '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
+    '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
+    'Example create: {"action":"create","title":"Ship image","description":"...","specs":"...","in_scope":["CLI"],',
+    '"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
+  ].join(' '),
+
+  kanban_gui: [
+    'Web GUI control. Prefer status before start. stop only kills GUI this MCP spawned;',
+    'external_running = do not retry kill — use the returned url or leave it.',
+    'status: running|external_running|not_running. Rarely needed mid-task — open once if user wants UI.'
+  ].join(' ')
+};
+
+const MUST_CONTAIN = [
+  'TOKEN RULES',
+  'view=summary',
+  'return=none',
+  'plan_create',
+  'external_running',
+  'subtasks'
+];
+
+function playbookHelpPayload() {
+  return {
+    source: 'agent-playbook.js',
+    note: 'Canonical rules for agents. Same text drives MCP tool descriptions. LLM_AGENTS.md is human docs only.',
+    drop_in_rule: DROP_IN_RULE,
+    tools: {
+      kanban_read: TOOL_DESCRIPTIONS.kanban_read,
+      kanban_manage: TOOL_DESCRIPTIONS.kanban_manage,
+      kanban_gui: TOOL_DESCRIPTIONS.kanban_gui
+    }
+  };
+}
+
+module.exports = {
+  DROP_IN_RULE,
+  TOOL_DESCRIPTIONS,
+  MUST_CONTAIN,
+  playbookHelpPayload
+};

package/bin/kanban-cmd.js

@@ -13,7 +13,7 @@ function findPython() {
       if (result.status === 0) {
         return cmd;
       }
-    } catch (e) {
+    } catch {
       continue;
     }
   }

package/bin/kanban.js

@@ -2,12 +2,12 @@
 
 const kanban = require('../kanban.js');
 const plan = require('../plan.js');
+const guiRegistry = require('../gui-registry.js');
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
-const COLS = kanban.COLS;
 
 function shortId(taskId) {
   const match = taskId.match(/^(?:[A-Z]+-)?(\d+)/);
@@ -357,11 +357,11 @@ async function serveWeb(port) {
   }
 
   const actualPort = server.address().port;
-  const portInfo = await kanban.writeGuiPortFile({ port: actualPort, pid: process.pid });
+  const portInfo = await guiRegistry.writeGuiPortFile({ port: actualPort, pid: process.pid });
 
   async function cleanupGuiPortFile() {
     try {
-      await kanban.clearGuiPortFile({ pid: process.pid });
+      await guiRegistry.clearGuiPortFile({ pid: process.pid });
     } catch {
       // best-effort cleanup
     }
@@ -458,9 +458,9 @@ async function main() {
   const args = process.argv.slice(2);
   const cmd = args[0];
 
-if (!cmd || cmd === 'serve') {
-  const port = kanban.resolvePreferredGuiPort(args[1]);
-  await serveWeb(port);
+  if (!cmd || cmd === 'serve') {
+    const port = guiRegistry.resolvePreferredGuiPort(args[1]);
+    await serveWeb(port);
   } else if (cmd === 'init') {
     await cliInit();
   } else if (cmd === 'mcp-init') {

package/gui-registry.js

@@ -0,0 +1,148 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+const BACKLOG = path.join(process.cwd(), 'backlog');
+const GUI_PORT_FILE = '.kanbango-gui.json';
+const GUI_PORT_MIN = 5510;
+const GUI_PORT_MAX = 5999;
+const GUI_PORT_SPAN = GUI_PORT_MAX - GUI_PORT_MIN + 1;
+
+function createGuiError(code, message, hint, details = {}, retryable = false, status = 400) {
+  const error = new Error(message);
+  error.code = code;
+  error.hint = hint;
+  error.details = details;
+  error.retryable = retryable;
+  error.status = status;
+  return error;
+}
+
+function guiPortFilePath() {
+  return path.join(BACKLOG, GUI_PORT_FILE);
+}
+
+function hashCwdToPort(cwd = process.cwd()) {
+  let hash = 0;
+  const input = String(cwd);
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
+  }
+  return GUI_PORT_MIN + (Math.abs(hash) % GUI_PORT_SPAN);
+}
+
+function normalizeGuiPort(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+    return null;
+  }
+  return parsed;
+}
+
+function resolvePreferredGuiPort(explicitPort) {
+  if (explicitPort !== undefined && explicitPort !== null && explicitPort !== '') {
+    const fromArg = normalizeGuiPort(explicitPort);
+    if (fromArg) return fromArg;
+  }
+
+  const fromEnv = normalizeGuiPort(process.env.KANBANGO_GUI_PORT);
+  if (fromEnv) return fromEnv;
+
+  return hashCwdToPort(process.cwd());
+}
+
+function isPidAlive(pid) {
+  const n = Number.parseInt(pid, 10);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureBacklogDir() {
+  await fs.mkdir(BACKLOG, { recursive: true });
+}
+
+async function writeGuiPortFile({ port, pid = process.pid } = {}) {
+  const normalizedPort = normalizeGuiPort(port);
+  if (!normalizedPort) {
+    throw createGuiError(
+      'VALIDATION_ERROR',
+      'Invalid GUI port',
+      'Use an integer between 1 and 65535',
+      { port },
+      false,
+      400
+    );
+  }
+
+  await ensureBacklogDir();
+  const data = {
+    port: normalizedPort,
+    pid,
+    url: `http://localhost:${normalizedPort}`,
+    cwd: process.cwd(),
+    started_at: new Date().toISOString()
+  };
+  await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+async function readGuiPortFile() {
+  try {
+    const raw = await fs.readFile(guiPortFilePath(), 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || !normalizeGuiPort(data.port)) return null;
+    return data;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+async function clearGuiPortFile({ pid, force = false } = {}) {
+  const info = await readGuiPortFile();
+  if (!info) return false;
+  if (!force && pid !== undefined && info.pid !== pid) return false;
+  if (!force && pid === undefined && info.pid !== process.pid) return false;
+
+  try {
+    await fs.unlink(guiPortFilePath());
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function discoverRunningGui() {
+  const info = await readGuiPortFile();
+  if (!info || !isPidAlive(info.pid)) {
+    if (info) await clearGuiPortFile({ force: true });
+    return null;
+  }
+  return {
+    status: 'running',
+    port: info.port,
+    pid: info.pid,
+    url: info.url || `http://localhost:${info.port}`,
+    cwd: info.cwd,
+    started_at: info.started_at
+  };
+}
+
+module.exports = {
+  hashCwdToPort,
+  normalizeGuiPort,
+  resolvePreferredGuiPort,
+  isPidAlive,
+  writeGuiPortFile,
+  readGuiPortFile,
+  clearGuiPortFile,
+  discoverRunningGui,
+  guiPortFilePath,
+  GUI_PORT_MIN,
+  GUI_PORT_MAX
+};

package/index.js

@@ -10,8 +10,12 @@
 
 const kanban = require('./kanban.js');
 const plan = require('./plan.js');
+const guiRegistry = require('./gui-registry.js');
+const playbook = require('./agent-playbook.js');
 
 module.exports = {
   kanban,
   plan,
+  guiRegistry,
+  playbook,
 };

package/kanban.js

@@ -3,10 +3,6 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const COLS = ['active', 'planned', 'icebox', 'done'];
-const GUI_PORT_FILE = '.kanbango-gui.json';
-const GUI_PORT_MIN = 5510;
-const GUI_PORT_MAX = 5999;
-const GUI_PORT_SPAN = GUI_PORT_MAX - GUI_PORT_MIN + 1;
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
@@ -383,7 +379,7 @@ async function findFile(epicId) {
       const candidates = files
         .filter((file) => (file.endsWith('.json') || file.endsWith('.md'))
           && path.basename(file, path.extname(file)) === epicId)
-        .sort((left, right) => (left.endsWith('.json') ? -1 : 1));
+        .sort((left, _right) => (left.endsWith('.json') ? -1 : 1));
       if (candidates[0]) {
         return path.join(colDir, candidates[0]);
       }
@@ -564,11 +560,6 @@ async function doCreate(title, column = 'planned', epicGroup = '—', extra = {}
   validateColumn(column, 'col');
 
   const nextId = await nextTaskNumber();
-  const slug = title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .substring(0, 25);
   const task = normalizeTask({
     id: String(nextId).padStart(3, '0'),
     title,
@@ -769,118 +760,6 @@ async function doUpdate(epicId, newTitle, newTasks) {
   }
 }
 
-function guiPortFilePath() {
-  return path.join(BACKLOG, GUI_PORT_FILE);
-}
-
-function hashCwdToPort(cwd = process.cwd()) {
-  let hash = 0;
-  const input = String(cwd);
-  for (let i = 0; i < input.length; i++) {
-    hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
-  }
-  return GUI_PORT_MIN + (Math.abs(hash) % GUI_PORT_SPAN);
-}
-
-function normalizeGuiPort(value) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
-    return null;
-  }
-  return parsed;
-}
-
-function resolvePreferredGuiPort(explicitPort) {
-  if (explicitPort !== undefined && explicitPort !== null && explicitPort !== '') {
-    const fromArg = normalizeGuiPort(explicitPort);
-    if (fromArg) return fromArg;
-  }
-
-  const fromEnv = normalizeGuiPort(process.env.KANBANGO_GUI_PORT);
-  if (fromEnv) return fromEnv;
-
-  return hashCwdToPort(process.cwd());
-}
-
-function isPidAlive(pid) {
-  const n = Number.parseInt(pid, 10);
-  if (!Number.isFinite(n) || n <= 0) return false;
-  try {
-    process.kill(n, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function writeGuiPortFile({ port, pid = process.pid } = {}) {
-  const normalizedPort = normalizeGuiPort(port);
-  if (!normalizedPort) {
-    throw createKanbanError(
-      'VALIDATION_ERROR',
-      'Invalid GUI port',
-      'Use an integer between 1 and 65535',
-      { port },
-      false,
-      400
-    );
-  }
-
-  await ensureBacklogDir();
-  const data = {
-    port: normalizedPort,
-    pid,
-    url: `http://localhost:${normalizedPort}`,
-    cwd: process.cwd(),
-    started_at: new Date().toISOString()
-  };
-  await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
-  return data;
-}
-
-async function readGuiPortFile() {
-  try {
-    const raw = await fs.readFile(guiPortFilePath(), 'utf-8');
-    const data = JSON.parse(raw);
-    if (!data || !normalizeGuiPort(data.port)) return null;
-    return data;
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    return null;
-  }
-}
-
-async function clearGuiPortFile({ pid, force = false } = {}) {
-  const info = await readGuiPortFile();
-  if (!info) return false;
-  if (!force && pid !== undefined && info.pid !== pid) return false;
-  if (!force && pid === undefined && info.pid !== process.pid) return false;
-
-  try {
-    await fs.unlink(guiPortFilePath());
-    return true;
-  } catch (error) {
-    if (error.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-async function discoverRunningGui() {
-  const info = await readGuiPortFile();
-  if (!info || !isPidAlive(info.pid)) {
-    if (info) await clearGuiPortFile({ force: true });
-    return null;
-  }
-  return {
-    status: 'running',
-    port: info.port,
-    pid: info.pid,
-    url: info.url || `http://localhost:${info.port}`,
-    cwd: info.cwd,
-    started_at: info.started_at
-  };
-}
-
 module.exports = {
   ensureBacklogDir,
   parseEpic,
@@ -899,19 +778,8 @@ module.exports = {
   missingRecommendedCreateFields,
   getProgress,
   resolveTaskId,
-  hashCwdToPort,
-  normalizeGuiPort,
-  resolvePreferredGuiPort,
-  isPidAlive,
-  writeGuiPortFile,
-  readGuiPortFile,
-  clearGuiPortFile,
-  discoverRunningGui,
-  guiPortFilePath,
   COLS,
   STATUS_MAP,
   VIEW_FIELDS,
-  RECOMMENDED_CREATE_FIELDS,
-  GUI_PORT_MIN,
-  GUI_PORT_MAX
+  RECOMMENDED_CREATE_FIELDS
 };

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 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', '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: "Strongly recommended. High-level context/why for 'create', 'update', or 'plan_create'."
+              description: 'Why/context (recommended on 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 +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 }
           );
         }
@@ -656,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 {
@@ -667,7 +691,7 @@ function installGuiShutdownHooks() {
   }
 
   process.once('exit', () => {
-    if (guiProcess && guiProcess.exitCode === null) {
+    if (ownsGuiProcess()) {
       try {
         guiProcess.kill();
       } catch {
@@ -676,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));
   });
 }
 
@@ -699,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.5.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');