kanbango 2.1.0 → 2.5.0

package/LLM_AGENTS.md

@@ -68,7 +68,7 @@ Read tasks from kanban board. Can list all tasks, filter by column/epic, or get
 ```json
 {
   "operation": "list",  // "list" or "show"
-  "task_id": "PI-014-google-calendar",  // Required for "show"
+  "task_id": "014",  // Required for "show"
   "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done"
   "epic": "Phase 1"  // Optional: filter by epic group
 }
@@ -95,7 +95,7 @@ Get specific task details:
 ```json
 {
   "operation": "show",
-  "task_id": "PI-014-google-calendar"
+  "task_id": "014"
 }
 ```
 
@@ -103,12 +103,12 @@ Get specific task details:
 ```json
 [
   {
-    "id": "PI-014-google-calendar",
-    "title": "PI-014: Google Calendar Integration",
+    "id": "014",
+    "title": "Google Calendar Integration",
     "column": "active",
     "epic_group": "Phase 1",
     "created": "2026-03-15",
-    "tasks": [
+    "subtasks": [
       { "done": true, "text": "API authentication" },
       { "done": false, "text": "Event synchronization" }
     ]
@@ -119,232 +119,202 @@ Get specific task details:
 **Response (show):**
 ```json
 {
-  "id": "PI-014-google-calendar",
-  "title": "PI-014: Google Calendar Integration",
+  "id": "014",
+  "title": "Google Calendar Integration",
   "column": "active",
   "epic_group": "Phase 1",
   "created": "2026-03-15",
-  "tasks": [
-    { "done": true, "text": "API authentication" },
-    { "done": false, "text": "Event synchronization" }
-  ]
+    "subtasks": [
+      { "done": true, "text": "API authentication" },
+      { "done": false, "text": "Event synchronization" }
+    ]
 }
 ```
 
 ---
 
-### 2. kanban_create
-
-Create a new task on kanban board.
+### 2. kanban_manage
 
-**Parameters:**
-```json
-{
-  "title": "New feature implementation",  // Required
-  "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done" (default: "planned")
-  "epic": "Phase 1"  // Optional: epic group name (default: "—")
-}
-```
+Create, move, or patch-update kanban tasks. Single tool for all mutations.
 
-**Examples:**
+**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
 
-Create task with defaults:
+**Parameters (create):**
 ```json
 {
-  "title": "Add user authentication"
+  "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 task with custom column and epic:
+**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
 {
-  "title": "Database optimization",
-  "col": "planned",
-  "epic": "Performance"
+  "action": "move",
+  "task_id": "014",  // Required
+  "column": "done"  // Required: target column
 }
 ```
 
-**Response:**
+**Parameters (update):**
 ```json
 {
-  "id": "PI-015-database-optimization",
-  "title": "PI-015: Database optimization",
-  "column": "planned",
-  "epic_group": "Performance",
-  "created": "2026-03-16",
-  "tasks": []
+  "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")
 }
 ```
 
----
-
-### 3. kanban_update
-
-Update existing tasks on kanban board. Can move tasks between columns, toggle subtask completion, or update task details.
-
-**Operations:**
-- `move` - Move task to different column
-- `toggle` - Toggle subtask completion
-- `update` - Update task title and/or subtask list
+**Examples:**
 
-**Parameters:**
+Create a task:
 ```json
 {
-  "operation": "move",  // "move" | "toggle" | "update"
-  "task_id": "PI-014-google-calendar",  // Required
-  "column": "done",  // Required for "move"
-  "idx": 0,  // Required for "toggle"
-  "title": "Updated title",  // Optional for "update"
-  "tasks": [  // Optional for "update"
-    { "done": true, "text": "Task 1" },
-    { "done": false, "text": "Task 2" }
-  ]
+  "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"]
 }
 ```
 
-**Examples:**
-
 Move task to done:
 ```json
 {
-  "operation": "move",
-  "task_id": "PI-014-google-calendar",
+  "action": "move",
+  "task_id": "014",
   "column": "done"
 }
 ```
 
-Toggle first subtask:
+Patch-update task fields:
 ```json
 {
-  "operation": "toggle",
-  "task_id": "PI-014-google-calendar",
-  "idx": 0
+  "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 }
+    ]
+  }
 }
 ```
 
-Update task title:
-```json
-{
-  "operation": "update",
-  "task_id": "PI-014-google-calendar",
-  "title": "Google Calendar API Integration"
-}
-```
+---
 
-Update subtasks:
-```json
-{
-  "operation": "update",
-  "task_id": "PI-014-google-calendar",
-  "tasks": [
-    { "done": true, "text": "API authentication" },
-    { "done": true, "text": "Event synchronization" },
-    { "done": false, "text": "Error handling" }
-  ]
-}
-```
+### 3. kanban_gui
 
-**Response (move):**
-```json
-{
-  "success": true,
-  "message": "Moved PI-014-google-calendar to done"
-}
-```
+Control the web GUI server: start, stop, or check status.
 
-**Response (toggle/update):**
-```json
-{
-  "id": "PI-014-google-calendar",
-  "title": "PI-014: Google Calendar Integration",
-  "column": "active",
-  "epic_group": "Phase 1",
-  "created": "2026-03-15",
-  "tasks": [
-    { "done": false, "text": "API authentication" },
-    { "done": false, "text": "Event synchronization" }
-  ]
-}
-```
+**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`
 
----
+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`).
 
-### 4. kanban_gui_start
+**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.
 
-Start the web GUI server for the kanban board.
+**Actions:**
+- `start` - Launch the GUI server
+- `stop` - Kill the GUI server
+- `status` - Check if the GUI is running (reads live process or port file)
 
 **Parameters:**
 ```json
 {
-  "port": 5500  // Optional: port for GUI (default 5500)
+  "action": "start",  // "start" | "stop" | "status"
+  "port": 5821  // Optional, only for "start"
 }
 ```
 
 **Examples:**
 
-Start GUI on default port:
+Start GUI (stable project port):
 ```json
-{}
+{
+  "action": "start"
+}
 ```
 
 Start GUI on custom port:
 ```json
 {
+  "action": "start",
   "port": 8080
 }
 ```
 
-**Response:**
+Stop the GUI:
 ```json
 {
-  "status": "started",
-  "port": 5500,
-  "pid": 12345,
-  "url": "http://localhost:5500"
+  "action": "stop"
 }
 ```
 
----
-
-### 5. kanban_gui_stop
-
-Stop the web GUI server if it is running.
-
-**Parameters:**
+Check status:
 ```json
-{}
+{
+  "action": "status"
+}
 ```
 
-**Response:**
+**Response (start):**
 ```json
 {
-  "status": "stopping",
-  "port": 5500
+  "status": "started",
+  "port": 5623,
+  "pid": 12345,
+  "url": "http://localhost:5623"
 }
 ```
 
----
-
-### 6. kanban_gui_status
-
-Get status of the web GUI server.
-
-**Parameters:**
+**Response (stop):**
 ```json
-{}
+{
+  "status": "stopping",
+  "port": 5623,
+  "pid": 12345
+}
 ```
 
-**Response (running):**
+**Response (status - running):**
 ```json
 {
   "status": "running",
-  "port": 5500,
+  "port": 5623,
   "pid": 12345,
-  "url": "http://localhost:5500"
+  "url": "http://localhost:5623"
 }
 ```
 
-**Response (not running):**
+**Response (status - not running):**
 ```json
 {
   "status": "not_running"
@@ -359,15 +329,24 @@ Get status of the web GUI server.
 
 ```json
 {
-  "id": "string",  // Unique task identifier (e.g., "PI-014-google-calendar")
-  "title": "string",  // Full title with ID prefix
+  "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)
-  "tasks": [
+  "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": [
     {
-      "done": "boolean",  // Subtask completion status
-      "text": "string"  // Subtask description
+      "id": "string",
+      "done": "boolean",
+      "text": "string",
+      "description": "string"
     }
   ]
 }
@@ -387,51 +366,62 @@ Get status of the web GUI server.
 ### Pattern 1: Task Discovery
 
 ```json
-// List all active tasks
-{ "operation": "list", "col": "active" }
+{ "tool": "kanban_read", "arguments": { "operation": "list", "col": "active" } }
 ```
 
 ### Pattern 2: Task Creation Workflow
 
 ```json
-// 1. Create task
-{ "title": "New feature", "col": "planned", "epic": "Phase 1" }
+// 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
-{ "operation": "show", "task_id": "PI-015-new-feature" }
+{ "tool": "kanban_read", "arguments": { "operation": "show", "task_id": "015" } }
 
 // 3. Update with subtasks
-{
-  "operation": "update",
-  "task_id": "PI-015-new-feature",
-  "tasks": [
-    { "done": false, "text": "Research" },
-    { "done": false, "text": "Implementation" }
-  ]
-}
+{ "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
-{ "operation": "move", "task_id": "PI-015", "column": "active" }
+{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "active" } }
 
-// Mark subtask complete
-{ "operation": "toggle", "task_id": "PI-015", "idx": 0 }
+// 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
-{ "operation": "move", "task_id": "PI-015", "column": "done" }
+{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "done" } }
 ```
 
 ### Pattern 4: Epic Management
 
 ```json
 // List all tasks in an epic
-{ "operation": "list", "epic": "Performance" }
+{ "tool": "kanban_read", "arguments": { "operation": "list", "epic": "Performance" } }
 
-// Create task in specific epic
-{ "title": "Cache optimization", "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"]
+} }
 ```
 
 ---
@@ -439,30 +429,33 @@ Get status of the web GUI server.
 ## Best Practices for LLM Agents
 
 1. **Always use `kanban_read` first** - Discover existing tasks before creating new ones
-2. **Use `col` filter** - Narrow down to relevant column when listing
-3. **Use `epic` grouping** - Organize tasks by features/phases
-4. **Work through subtasks** - Toggle each subtask as you complete them
-5. **Move tasks through workflow** - planned → active → done progression
-6. **Use `show` operation** - Get full task details including subtasks
-7. **Handle task IDs** - Always use the full task ID returned from create/show
+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
 
 ---
 
 ## Error Handling
 
-All tools return error messages in this format:
+All tools return structured error responses:
 
 ```json
 {
-  "error": "Error message description"
+  "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
+  }
 }
 ```
 
-Common errors:
-- `"Task not found: PI-999"` - Task ID doesn't exist
-- `"Failed to move task: PI-999"` - Move operation failed
-- `"task_id is required for 'show' operation"` - Missing required parameter
-
 ---
 
 ## Installation for Users

package/README.md

@@ -25,7 +25,7 @@ npx kanbango --help
 # Initialize backlog directories
 kanban init
 
-# Start web GUI at http://localhost:5500
+# Start web GUI (stable project port; prints the real URL)
 kanban serve
 
 # List all tasks
@@ -35,13 +35,13 @@ kanban list --json
 kanban add "My task" --col planned --epic "Phase 1"
 
 # Show details
-kanban show PI-001
+kanban show 001
 
 # Move between columns (active | planned | icebox | done)
-kanban move PI-001 active
+kanban move 001 active
 
-# Toggle subtask completion
-kanban toggle PI-001 0
+# Update subtasks in one call
+kanban update 001 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
 ### Columns
@@ -59,14 +59,17 @@ Tasks are JSON files in `backlog/<column>/`:
 
 ```json
 {
-  "id": "PI-001-my-feature",
+  "id": "001",
   "title": "My Feature",
   "column": "planned",
   "epic_group": "Phase 1",
   "created": "2026-07-08",
   "description": "High-level context.",
   "specs": "Technical details.",
+  "in_scope": ["What this task covers"],
+  "out_of_scope": ["What is explicitly excluded"],
   "acceptance_criteria": ["Works as expected"],
+  "test_cases": ["Verify the happy path"],
   "subtasks": [
     { "id": "st-1", "text": "First step", "done": false }
   ]
@@ -96,6 +99,24 @@ Add this to your MCP client config (`.mcp.json`, `opencode.json`, or Claude Desk
 }
 ```
 
+Auto-start the web GUI with MCP (opt-in):
+
+```json
+{
+  "mcpServers": {
+    "kanbango": {
+      "command": "npx",
+      "args": ["kanbango", "mcp"],
+      "env": {
+        "KANBANGO_AUTO_GUI": "1"
+      }
+    }
+  }
+}
+```
+
+Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs).
+
 Or generate the config files automatically:
 
 ```bash
@@ -109,11 +130,8 @@ Once connected, your agent gets access to these tools:
 | Tool | What it does |
 |------|-------------|
 | `kanban_read` | List tasks, filter by column/epic, show details |
-| `kanban_create` | Add new tasks |
-| `kanban_update` | Move, edit, toggle subtasks |
-| `kanban_gui_start` | Start web GUI from the agent |
-| `kanban_gui_stop` | Stop web GUI |
-| `kanban_gui_status` | Check if GUI is running |
+| `kanban_manage` | Create, move, patch-update tasks |
+| `kanban_gui` | Start, stop, or check web GUI status (returns the real URL/port) |
 
 Your agent stays in sync with your real board — every change is persisted as JSON files.
 
@@ -122,12 +140,11 @@ Your agent stays in sync with your real board — every change is persisted as J
 | Command | Description |
 |---------|-------------|
 | `kanban init` | Create backlog directory structure |
-| `kanban serve [PORT]` | Start web GUI (default 5500) |
+| `kanban serve [PORT]` | Start web GUI (stable project port, or PORT / KANBANGO_GUI_PORT) |
 | `kanban list [--col <col>] [--json]` | List tasks |
 | `kanban show <ID>` | Show task details |
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
-| `kanban toggle <ID> <IDX>` | Toggle subtask |
 | `kanban mcp-init` | Generate MCP config files |
 
 ## Web GUI
@@ -152,4 +169,4 @@ Node.js 16+
 
 ## License
 
-MIT
+MIT