kanbango 3.8.0 → 5.1.0

package/LLM_AGENTS.md

@@ -1,20 +1,12 @@
 # MCP Server Guide for LLM Agents
 
-Human-oriented setup guide. **Agents do not load this file automatically.**
+Human-oriented setup. **Agents do not load this file.** Rules live in `agent-playbook.js`.
+`tools/list` is short; full playbook is `kanban_read` `operation=help`.
 
-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.
+## Config
 
-Optional refresh in-session: `kanban_read` with `operation: "help"`.
+**Claude Desktop / generic MCP:**
 
-## Quick Integration
-
-### Configuration
-
-Add to your MCP client configuration:
-
-**Claude Desktop:**
 ```json
 {
   "mcpServers": {
@@ -26,507 +18,34 @@ Add to your MCP client configuration:
 }
 ```
 
-**General MCP:**
-```json
-{
-  "mcpServers": {
-    "kanbango": {
-      "command": "node",
-      "args": ["path/to/mcp-server.js"]
-    }
-  }
-}
-```
-
-### Project Automation (Claude Code + OpenCode)
-
-Generate project configs automatically in the current folder:
-
-```bash
-# Local install (recommended)
-npx kanbango mcp-init
-
-# Use npx-based command in configs
-npx kanbango mcp-init --npx
-
-# Only Claude Code config
-npx kanbango mcp-init --claude
-
-# Only OpenCode config
-npx kanbango mcp-init --opencode
-```
-
-This creates:
-- `.mcp.json` for Claude Code (project-scoped MCP servers)
-- `opencode.json` for OpenCode (project-scoped MCP servers)
-
-## Available Tools
-
-### 1. kanban_read
-
-Read tasks from kanban board. Can list all tasks, filter by column/epic, or get details of a specific task.
-
-**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" | "show" | "help"
-  "task_id": "014",  // Required for "show"
-  "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done"
-  "epic": "Phase 1"  // Optional: filter by epic group
-}
-```
-
-**Examples:**
-
-List all tasks:
-```json
-{
-  "operation": "list"
-}
-```
-
-List tasks in active column:
-```json
-{
-  "operation": "list",
-  "col": "active"
-}
-```
-
-Get specific task details:
-```json
-{
-  "operation": "show",
-  "task_id": "014"
-}
-```
-
-**Response (list):**
-```json
-[
-  {
-    "id": "014",
-    "title": "Google Calendar Integration",
-    "column": "active",
-    "epic_group": "Phase 1",
-    "created": "2026-03-15",
-    "subtasks": [
-      { "done": true, "text": "API authentication" },
-      { "done": false, "text": "Event synchronization" }
-    ]
-  }
-]
-```
-
-**Response (show):**
-```json
-{
-  "id": "014",
-  "title": "Google Calendar Integration",
-  "column": "active",
-  "epic_group": "Phase 1",
-  "created": "2026-03-15",
-    "subtasks": [
-      { "done": true, "text": "API authentication" },
-      { "done": false, "text": "Event synchronization" }
-    ]
-}
-```
-
----
-
-### 2. kanban_manage
-
-Create, move, or patch-update kanban tasks. Single tool for all mutations.
-
-**Actions:**
-- `create` - Create a new task with optional rich planning fields
-- `move` - Move a task to a different column
-- `update` - Apply a field-level patch to any task attributes
-
-**Parameters (create):**
-```json
-{
-  "action": "create",
-  "title": "New feature",  // Required (only hard requirement)
-  "col": "planned",  // Optional, default "planned"
-  "epic": "Phase 1",  // Optional, default "—"
-  "description": "Context and plan",  // Strongly recommended
-  "specs": "Technical constraints",  // Strongly recommended
-  "in_scope": ["What is included"],  // Strongly recommended
-  "out_of_scope": ["What is excluded"],  // Strongly recommended
-  "acceptance_criteria": ["Must work"],  // Strongly recommended
-  "test_cases": ["Verify X"],  // Recommended
-  "subtasks": [{"text": "Do it", "done": false}],
-  "notes": "Freeform notes"
-}
-```
-
-**Create field policy:** only `title` is hard-required (GUI/CLI quick-add stays usable). For agent work, always send the strongly recommended fields. If any are missing, create still succeeds and the response includes `warnings` + `missing_recommended`.
-
-**Parameters (move):**
-```json
-{
-  "action": "move",
-  "task_id": "014",  // Required
-  "column": "done"  // Required: target column
-}
-```
-
-**Parameters (update):**
-```json
-{
-  "action": "update",
-  "task_id": "014",  // Required
-  "patch": {"description": "New context"},  // Field-level patch object
-  "title": "New title",  // Shortcut, equivalent to patch.title
-  "subtasks": [{"text": "A", "done": true}],  // Preferred full subtask list
-  "return": "summary"  // "none" | "summary" | "full" (default "summary")
-}
-```
-
-**Examples:**
-
-Create a task:
-```json
-{
-  "action": "create",
-  "title": "Database optimization",
-  "col": "planned",
-  "epic": "Performance",
-  "description": "Reduce N+1 queries on board list",
-  "specs": "Keep JSON storage; no new deps",
-  "in_scope": ["list query path"],
-  "out_of_scope": ["GUI redesign"],
-  "acceptance_criteria": ["list stays correct under load"]
-}
-```
-
-Move task to done:
-```json
-{
-  "action": "move",
-  "task_id": "014",
-  "column": "done"
-}
-```
-
-Patch-update task fields:
-```json
-{
-  "action": "update",
-  "task_id": "014",
-  "patch": {
-    "title": "Updated title",
-    "description": "New implementation plan",
-    "epic_group": "Phase 2",
-    "subtasks": [
-      { "id": "st-1", "text": "Research", "done": true },
-      { "id": "st-2", "text": "Implementation", "done": false }
-    ]
-  }
-}
-```
-
----
+Generate project files: `npx kanbango mcp-init` (optional `--npx`, `--claude`, `--opencode`).
+Writes `.mcp.json` and/or `opencode.json`.
 
-### 3. kanban_gui
+Auto-GUI: set `KANBANGO_AUTO_GUI=1`. Pin port with `KANBANGO_GUI_PORT`. Label with `KANBANGO_PROJECT_NAME`.
 
-Control the web GUI server: start, stop, or check status.
+## Tools
 
-**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`.
+| Tool | Role |
+|------|------|
+| `kanban_read` | Omit operation = context (wake). list `view=summary`. `operation=help` for the playbook |
+| `kanban_manage` | create / move / update / delete / epic_* / plan_*. Writes default `return=none` |
+| `kanban_gui` | `status` before `start`. `stop` only owned. `external_running` = do not kill |
 
-**Port resolution (start):**
-1. Explicit `port` argument, if provided
-2. Else `KANBANGO_GUI_PORT` env
-3. Else stable hash of project cwd in range `5510–5999`
+Create returns `{ok, id, missing?}`. List hides `column=done` and tasks under done/archived epics unless you pass `include_done` / `include_archived` / `col=done`.
 
-If the preferred port is busy, the server picks the next free port. Always trust the returned `url` / `port` (also written to `backlog/.kanbango-gui.json`). Responses also include `project` (basename of project cwd, or `KANBANGO_PROJECT_NAME`) so agents and humans can tell boards apart; the GUI tab title and header show the same label.
+Kanbango core does not require QA, review agents, OpenCode, or another runner. Testing/review gates and agent spawns are optional project configuration.
 
-**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.
+Wake: one `kanban_read` (no operation). Then `show` with `view=planning` or `view=execution`. Do not re-list the full board after every write. Context skips blocked active work, surfaces failed/blocked gates and manual testing/review, and only starts the next unblocked planned task. Writes (`create`/`move`/`update`/`plan_*`) default `return=none` — no full card, subtasks, or evidence echo. Cost probe: `node benchmarks/agent-workflow.js --size 0 --size 10 --size 1000` (MCP JSON bytes ≠ tokens).
 
-**Actions:**
-- `start` - Launch the GUI server (or report already_running owned/external)
-- `stop` - Stop only MCP-owned GUI
-- `status` - Check GUI state
+## Errors
 
-**Parameters:**
-```json
-{
-  "action": "start",  // "start" | "stop" | "status"
-  "port": 5821  // Optional, only for "start"
-}
-```
-
-**Examples:**
-
-Start GUI (stable project port):
-```json
-{
-  "action": "start"
-}
-```
-
-Start GUI on custom port:
-```json
-{
-  "action": "start",
-  "port": 8080
-}
-```
-
-Stop the GUI:
-```json
-{
-  "action": "stop"
-}
-```
-
-Check status:
-```json
-{
-  "action": "status"
-}
-```
-
-**Response (start):**
-```json
-{
-  "status": "started",
-  "owned": true,
-  "port": 5623,
-  "pid": 12345,
-  "url": "http://localhost:5623"
-}
-```
-
-**Response (stop - owned):**
-```json
-{
-  "status": "stopping",
-  "owned": true,
-  "port": 5623,
-  "pid": 12345
-}
-```
-
-**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
-{
-  "status": "not_running"
-}
-```
-
----
-
-## Data Structure
-
-### Task Object
-
-```json
-{
-  "id": "string",  // Numeric task identifier (e.g., "014")
-  "title": "string",  // Task title, kept separate from the ID
-  "column": "string",  // "active" | "planned" | "icebox" | "done"
-  "epic_group": "string",  // Epic group name or "—"
-  "created": "string",  // Creation date (YYYY-MM-DD)
-  "description": "string",  // High-level context
-  "specs": "string",  // Technical constraints
-  "in_scope": ["string"],  // What this task includes
-  "out_of_scope": ["string"],  // Explicit non-goals
-  "acceptance_criteria": ["string"],
-  "test_cases": ["string"],
-  "notes": "string",
-  "subtasks": [
-    {
-      "id": "string",
-      "done": "boolean",
-      "text": "string",
-      "description": "string"
-    }
-  ]
-}
-```
-
-### Columns
-
-- `active` - In progress (max 1-2 tasks recommended)
-- `planned` - Planned for implementation
-- `icebox` - Frozen / nice-to-have
-- `done` - Completed
-
----
-
-## Usage Patterns
-
-### Pattern 1: Task Discovery
-
-```json
-{ "tool": "kanban_read", "arguments": { "operation": "list", "col": "active" } }
-```
-
-### Pattern 2: Task Creation Workflow
-
-```json
-// 1. Create task with strongly recommended planning fields
-{ "tool": "kanban_manage", "arguments": {
-  "action": "create",
-  "title": "New feature",
-  "col": "planned",
-  "epic": "Phase 1",
-  "description": "Why this exists",
-  "specs": "APIs and constraints",
-  "in_scope": ["Core path"],
-  "out_of_scope": ["Mobile"],
-  "acceptance_criteria": ["npm test passes"]
-} }
-
-// 2. Get task details to see generated ID
-{ "tool": "kanban_read", "arguments": { "operation": "show", "task_id": "015" } }
-
-// 3. Update with subtasks
-{ "tool": "kanban_manage", "arguments": { "action": "update", "task_id": "015", "subtasks": [{"done": false, "text": "Research"}, {"done": false, "text": "Implementation"}] } }
-```
-
-### Pattern 3: Task Progression
-
-```json
-// Move from planned → active
-{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "active" } }
-
-// Update subtasks in one call
-{ "tool": "kanban_manage", "arguments": { "action": "update", "task_id": "015", "subtasks": [{ "done": true, "text": "Research" }, { "done": false, "text": "Implementation" }] } }
-
-// Move from active → done
-{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "done" } }
-```
-
-### Pattern 4: Epic Management
-
-```json
-// List all tasks in an epic
-{ "tool": "kanban_read", "arguments": { "operation": "list", "epic": "Performance" } }
-
-// Create task in specific epic (still include recommended fields)
-{ "tool": "kanban_manage", "arguments": {
-  "action": "create",
-  "title": "Cache optimization",
-  "epic": "Performance",
-  "description": "Reduce repeated board reads",
-  "specs": "In-memory cache with TTL",
-  "in_scope": ["list endpoint"],
-  "out_of_scope": ["distributed cache"],
-  "acceptance_criteria": ["p95 list latency down"]
-} }
-```
-
----
-
-## 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
-- steps on create/plan_create → subtasks (no forced TDD); runner optional; optional plan_*: plan_create → plan_advance → plan_evidence (diff|summary|test_command) → 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.
-
----
-
-## Error Handling
-
-All tools return structured error responses:
-
-```json
-{
-  "error": {
-    "code": "TASK_NOT_FOUND",
-    "message": "Task 999 was not found",
-    "hint": "Call kanban_read with operation=list to discover valid task ids",
-    "details": {},
-    "retryable": false
-  }
-}
-```
-
----
-
-## Installation for Users
-
-Tell users to run:
-
-```bash
-npm install -g kanbango
-```
+Structured `{error:{code,message,hint,details,retryable}}`. `next_tool_call` only when the repair is unique (`TASK_NOT_FOUND`, `INVALID_TRANSITION`). Concurrent writers on one local board may receive `BOARD_LOCKED` (`retryable=true`); retry the mutation. No lock across machines or shared/network storage. Corrupt task/epic JSON on list or context is `PARSE_ERROR` (`details.file`); never a partial board.
 
-Then add to their MCP configuration using the examples above.
+## Concurrency
 
----
+One local `backlog/` only. MCP, CLI, and GUI share `backlog/.board.lock`. Not a distributed store.
 
 ## Support
 
+- API map: [API.md](./API.md)
 - GitHub: https://github.com/k0r81/kanbango
-- Issues: https://github.com/k0r81/kanbango/issues
-- Full docs: https://github.com/k0r81/kanbango#readme

package/README.md

@@ -31,8 +31,9 @@ kanban config
 # Start web GUI (stable project port; prints the real URL)
 kanban serve
 
-# List all tasks
+# List tasks (hides column=done unless --col done)
 kanban list --json
+kanban list --col done --json
 
 # Add an epic (initiative container), then a task under it
 kanban epic add "Phase 1" --description "Why this initiative" --goals "Ship X"
@@ -52,7 +53,7 @@ kanban rm 001
 # Show details
 kanban show 001
 
-# Move between columns (active | planned | icebox | done)
+# Move between columns (active | planned | icebox | testing | review | done)
 kanban move 001 active
 
 # Update subtasks in one call
@@ -76,21 +77,22 @@ Epic status is **derived** from child task columns (not a board column).
 | `active` | In progress (keep to 1–2 tasks) |
 | `planned` | Ready to implement |
 | `icebox` | Nice-to-have / frozen |
-| `testing` | Optional QA gate (default on) |
-| `review` | Optional review gate (default on) |
+| `testing` | Optional project gate (default off) |
+| `review` | Optional project gate (default off) |
 | `done` | Completed |
 
 ### Project config (`backlog/kanbango.json`)
 
-Optional. Missing file = six columns, workflow agents off.
+Optional. Missing file = core board only: `icebox`, `planned`, `active`, and `done`.
+Workflow gates and agents are opt-in project configuration.
 
-On a **TTY**, `kanban init` / `kanban mcp-init` open a checkbox wizard when the file is missing (defaults: testing + qa-tester + review + temida all on). Non-TTY (CI, pipes, MCP) never blocks or creates a config; it prints a hint to run `kanban config` in a terminal. `kanban config` always opens the wizard (TTY required); invalid existing JSON is **not** overwritten (error + fix/remove).
+On a **TTY**, `kanban init` / `kanban mcp-init` open a checkbox wizard when the file is missing. The default is the core board with gates and agents off. Non-TTY (CI, pipes, MCP) never blocks or creates a config; it prints a hint to run `kanban config` in a terminal. `kanban config` always opens the wizard (TTY required); invalid existing JSON is **not** overwritten (error + fix/remove).
 
 ```json
 {
   "columns": {
-    "testing": { "enabled": false, "label": "QA" },
-    "review": { "enabled": true, "label": "Review" }
+    "testing": { "enabled": false, "label": "Testing" },
+    "review": { "enabled": false, "label": "Review" }
   },
   "workflow": {
     "enabled": true,
@@ -102,7 +104,7 @@ On a **TTY**, `kanban init` / `kanban mcp-init` open a checkbox wizard when the
 
 - Only `testing` and `review` are configurable (core columns stay on).
 - `enabled: false` on a gate column hides it and moves existing cards in that column to `planned`.
-- Agent `enabled: false` keeps the column as a **manual** gate (no auto spawn).
+- Agent `enabled: false` keeps an explicitly enabled column as a **manual** gate (no auto spawn).
 - Legacy string agent names still work: `"testing_agent": "qa-tester"`.
 
 ## Data Structure
@@ -181,11 +183,11 @@ Once connected, your agent gets access to these tools:
 
 | Tool | What it does |
 |------|-------------|
-| `kanban_read` | List/show tasks (`view=summary` by default — cheap) |
+| `kanban_read` | Omit operation = context (wake: unblocked active / gate / next planned). list `view=summary`; playbook via `operation=help` |
 | `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).
+**Token tip for agents:** `tools/list` is short. Full rules: `kanban_read` → `operation: "help"` (`agent-playbook.js`). Wake = context + one `show` (planning/execution), not `list` + `full`. Writes default `return=none`. Cost probe: `node benchmarks/agent-workflow.js`. Human setup: [LLM_AGENTS.md](./LLM_AGENTS.md).
 
 Your agent stays in sync with your real board — every change is persisted as JSON files.
 
@@ -196,7 +198,7 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban init` | Create backlog dirs; TTY wizard if `kanbango.json` missing |
 | `kanban config` | Interactive project config wizard (`backlog/kanbango.json`) |
 | `kanban serve [PORT]` | Start web GUI (stable project port, or PORT / KANBANGO_GUI_PORT) |
-| `kanban list [--col <col>] [--json]` | List tasks |
+| `kanban list [--col <col>] [--json]` | List tasks (hides `done` unless `--col done`) |
 | `kanban show <ID>` | Show task details |
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
@@ -209,14 +211,14 @@ Your agent stays in sync with your real board — every change is persisted as J
 ```bash
 kanban serve
 ```
-- Swimlanes grouped by epic
-- Drag-and-drop between columns
-- Inline editing and subtask checkboxes
+- Epic rail + NOW panel (`next_action` from `/api/context`)
+- Cards show blocked-by dependency ids
+- Drag-and-drop between columns; inline edit and subtask checkboxes
 
 ## Using as a Node.js module
 
 ```js
-const kanban = require('kanbango');
+const { kanban } = require('kanbango');
 const tasks = await kanban.allTasks();
 ```