kanbango 2.5.0 → 3.1.0

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,20 @@
 
 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`).
+
+- hierarchy: epic (context) → task (work+plan) → subtasks (steps)
+- list: `col` filter, `view=summary`; keep `task_id`s; no full-board re-list after every write
+- list_epics / show_epic for initiatives; filter tasks with `epic=E001`
+- show: `view=execution` while coding; `full` only if needed
+- epic_create with description/goals; create tasks with `epic=E001` (prefer id)
+- 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,60 @@ 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.1.0] - 2026-07-30
+
+### Added
+- First-class epic containers under `backlog/epics/E00N.json` (description, goals, in/out scope, notes)
+- Task field `epic_id` with denormalized `epic_group` title for lists/GUI
+- Derived epic status/progress from child task columns (no epic board column)
+- MCP: `list_epics`, `show_epic`, `epic_create`, `epic_update`
+- CLI: `kanban epic list|show|add|update`
+- HTTP: `GET/POST /api/epics` for real epics; `POST /api/tasks` for tasks (legacy `/api/epics` + `column` still creates tasks)
+- Auto-migration of legacy `epic_group` string labels into epic entities
+- GUI swimlanes group by `epic_id` and show epic context
+- Regression tests in `tests/epics.test.js`
+
+### Changed
+- Hierarchy documented for agents: epic → task → subtasks
+- Task summary view includes `epic_id`
+- Agent playbook includes epic discovery/create rules
+
+## [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

@@ -31,8 +31,13 @@ kanban serve
 # List all tasks
 kanban list --json
 
-# Add a task
-kanban add "My task" --col planned --epic "Phase 1"
+# Add an epic (initiative container), then a task under it
+kanban epic add "Phase 1" --description "Why this initiative" --goals "Ship X"
+kanban add "My task" --col planned --epic E001
+
+# List epics / show epic with child rollup
+kanban epic list --json
+kanban epic show E001
 
 # Show details
 kanban show 001
@@ -44,6 +49,16 @@ kanban move 001 active
 kanban update 001 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
+### Hierarchy
+
+| Level | What | Storage |
+|-------|------|---------|
+| **Epic** | Initiative context (description, goals) | `backlog/epics/E001.json` |
+| **Task** | Kanban card (column, AC, plan) | `backlog/{col}/001.json` |
+| **Subtask** | Checklist / plan steps | `subtasks[]` on task |
+
+Epic status is **derived** from child task columns (not a board column).
+
 ### Columns
 
 | Column | Purpose |
@@ -129,9 +144,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 +163,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
 
@@ -160,7 +178,7 @@ kanban serve
 
 ```js
 const kanban = require('kanbango');
-const tasks = await kanban.allEpics();
+const tasks = await kanban.allTasks();
 ```
 
 ## Requirements

package/agent-playbook.js

@@ -0,0 +1,79 @@
+/**
+ * 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:',
+  '- hierarchy: epic (context) → task (work+plan) → subtasks (steps)',
+  '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
+  '- list_epics / show_epic for initiatives; list tasks with epic=E001 for work',
+  '- show: view=execution while coding; full only if needed',
+  '- epic_create with description/goals; create tasks with epic=E001 (prefer id)',
+  '- 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).',
+    'Hierarchy: epic (container/context) → task (work) → subtasks (steps).',
+    'Always pass col when possible. Prefer show+view=execution over full.',
+    'list_epics/show_epic for initiatives; filter list with epic=E001 or epic title.',
+    'Do not re-list the whole board after every write — keep task_id from create/move.',
+    'Task IDs numeric ("014"); epic IDs "E001". 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); epic_create|epic_update (containers);',
+    'plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'epic_create: title + description/goals/in_scope/out_of_scope. Link tasks via epic=E001.',
+    '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","epic":"E001","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',
+  'epic_create'
+];
+
+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;
     }
   }