kanbango 2.4.0 → 2.5.0

package/.ai/retro/close.json

@@ -0,0 +1 @@
+{"goal":"push do npm","done":["session had mutations"],"next":[],"block":[],"lessons":[],"files":["/Users/mkorbas/projects/personal/markdown-kanban/mcp-server.js","/Users/mkorbas/projects/personal/markdown-kanban/kanban.js","/Users/mkorbas/projects/personal/markdown-kanban/tests/mcp-server.test.js","/Users/mkorbas/projects/personal/markdown-kanban/plan.js","/Users/mkorbas/projects/personal/markdown-kanban/CHANGELOG.md","/Users/mkorbas/projects/personal/markdown-kanban/bin/kanban.js","/Users/mkorbas/projects/personal/markdown-kanban/tests/update-tasks.test.js"],"verify":""}

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

@@ -0,0 +1 @@
+{"ts":"2026-07-29T09:29:19.070Z","sessionID":"ses_05beb2173ffe1rCJQhZBUHuLgs","added":[],"bumped":[],"error":"llm-parse-fallback"}

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [2.5.0] - 2026-07-27
+
+### 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.4.0] - 2026-07-27
 
 ### Added

package/LLM_AGENTS.md

@@ -146,20 +146,22 @@ Create, move, or patch-update kanban tasks. Single tool for all mutations.
 ```json
 {
   "action": "create",
-  "title": "New feature",  // Required
+  "title": "New feature",  // Required (only hard requirement)
   "col": "planned",  // Optional, default "planned"
   "epic": "Phase 1",  // Optional, default "—"
-  "description": "Context and plan",
-  "specs": "Technical constraints",
-  "in_scope": ["What is included"],
-  "out_of_scope": ["What is excluded"],
-  "acceptance_criteria": ["Must work"],
-  "test_cases": ["Verify X"],
+  "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
 {
@@ -189,7 +191,12 @@ Create a task:
   "action": "create",
   "title": "Database optimization",
   "col": "planned",
-  "epic": "Performance"
+  "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"]
 }
 ```
 
@@ -365,8 +372,18 @@ Check status:
 ### Pattern 2: Task Creation Workflow
 
 ```json
-// 1. Create task
-{ "tool": "kanban_manage", "arguments": { "action": "create", "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
 { "tool": "kanban_read", "arguments": { "operation": "show", "task_id": "015" } }
@@ -394,8 +411,17 @@ Check status:
 // List all tasks in an epic
 { "tool": "kanban_read", "arguments": { "operation": "list", "epic": "Performance" } }
 
-// Create task in specific epic
-{ "tool": "kanban_manage", "arguments": { "action": "create", "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"]
+} }
 ```
 
 ---
@@ -406,10 +432,11 @@ Check status:
 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. **Work through subtasks** - Toggle each subtask as you complete them
-6. **Move tasks through workflow** - planned → active → done progression
-7. **Use `show` operation** - Get full task details including subtasks
-8. **Handle task IDs** - Always use the full task ID returned from create/show
+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
 
 ---
 

package/kanban.js

@@ -62,6 +62,16 @@ const VIEW_FIELDS = {
   ]
 };
 
+// Hard-required on create: title only (keeps GUI/CLI quick-add usable).
+// Strongly recommended for agent/planned work — missing ones yield warnings, not errors.
+const RECOMMENDED_CREATE_FIELDS = [
+  'description',
+  'specs',
+  'in_scope',
+  'out_of_scope',
+  'acceptance_criteria'
+];
+
 function createKanbanError(code, message, hint, details = {}, retryable = false, status = 400) {
   const error = new Error(message);
   error.code = code;
@@ -96,6 +106,36 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function isPresentCreateField(field, value) {
+  if (field === 'description' || field === 'specs' || field === 'notes') {
+    return Boolean(normalizeString(value));
+  }
+  if (
+    field === 'in_scope' ||
+    field === 'out_of_scope' ||
+    field === 'acceptance_criteria' ||
+    field === 'test_cases' ||
+    field === 'subtasks'
+  ) {
+    if (field === 'subtasks') return normalizeSubtasks(value).length > 0;
+    return normalizeStringArray(value).length > 0;
+  }
+  return value !== undefined && value !== null && value !== '';
+}
+
+function missingRecommendedCreateFields(payload = {}) {
+  return RECOMMENDED_CREATE_FIELDS.filter((field) => !isPresentCreateField(field, payload[field]));
+}
+
+function createFieldWarnings(payload = {}) {
+  const missing = missingRecommendedCreateFields(payload);
+  if (missing.length === 0) return [];
+  return [
+    `Strongly recommended fields missing: ${missing.join(', ')}. ` +
+      'Fill them on create (or via update) so scope and done-criteria are explicit.'
+  ];
+}
+
 function normalizeSubtasks(value) {
   if (!Array.isArray(value)) return [];
   return value.map((subtask, idx) => ({
@@ -855,6 +895,8 @@ module.exports = {
   doUpdate,
   doCreate,
   createKanbanError,
+  createFieldWarnings,
+  missingRecommendedCreateFields,
   getProgress,
   resolveTaskId,
   hashCwdToPort,
@@ -869,6 +911,7 @@ module.exports = {
   COLS,
   STATUS_MAP,
   VIEW_FIELDS,
+  RECOMMENDED_CREATE_FIELDS,
   GUI_PORT_MIN,
   GUI_PORT_MAX
 };

package/mcp-server.js

@@ -309,7 +309,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'kanban_manage',
-        description: 'Mutate tasks and accepted plans. Required fields by action: create -> title; move -> task_id + column; update -> task_id plus patch or field shortcuts; plan_create -> title; plan_advance/plan_done/plan_status -> task_id; plan_evidence -> task_id + diff + test_command + stdout + stderr + exit_code. Example create: {"action":"create","title":"Ship Docker image","col":"planned","epic":"Release"}.',
+        description: '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"}.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -335,30 +335,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             description: {
               type: 'string',
-              description: "High-level context for 'create', 'update', or 'plan_create'."
+              description: "Strongly recommended. High-level context/why for 'create', 'update', or 'plan_create'."
             },
             specs: {
               type: 'string',
-              description: "Technical constraints, APIs, and edge cases for 'create', 'update', or 'plan_create'."
+              description: "Strongly recommended. Technical constraints, APIs, and edge cases for 'create', 'update', or 'plan_create'."
             },
             in_scope: {
               type: 'array',
-              description: "What this task includes for 'create', 'update', or 'plan_create'.",
+              description: "Strongly recommended. What this task includes (boundaries) for 'create', 'update', or 'plan_create'.",
               items: { type: 'string' }
             },
             out_of_scope: {
               type: 'array',
-              description: "Explicit non-goals / exclusions for 'create', 'update', or 'plan_create'.",
+              description: "Strongly recommended. Explicit non-goals / exclusions for 'create', 'update', or 'plan_create'.",
               items: { type: 'string' }
             },
             acceptance_criteria: {
               type: 'array',
-              description: "Completion requirements for 'create', 'update', or 'plan_create'.",
+              description: "Strongly recommended. Completion requirements for 'create', 'update', or 'plan_create'.",
               items: { type: 'string' }
             },
             test_cases: {
               type: 'array',
-              description: "Verification scenarios for 'create', 'update', or 'plan_create'.",
+              description: "Recommended. Verification scenarios for 'create', 'update', or 'plan_create'.",
               items: { type: 'string' }
             },
             subtasks: {
@@ -505,7 +505,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         switch (action) {
           case 'create': {
-            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', {
+            const createPayload = {
               description: args.description,
               specs: args.specs,
               in_scope: args.in_scope,
@@ -514,8 +514,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               test_cases: args.test_cases,
               subtasks: args.subtasks,
               notes: args.notes
-            });
-            result = kanban.shapeTask(created, { view: 'full' });
+            };
+            const created = await kanban.doCreate(args.title, args.col || 'planned', args.epic || '—', createPayload);
+            const shaped = kanban.shapeTask(created, { view: 'full' });
+            const warnings = kanban.createFieldWarnings(createPayload);
+            result = warnings.length > 0
+              ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
+              : shaped;
             break;
           }
 
@@ -564,9 +569,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
 
-          case 'plan_create':
+          case 'plan_create': {
             result = await plan.create(args);
+            const planWarnings = kanban.createFieldWarnings(args);
+            if (planWarnings.length > 0 && result && typeof result === 'object') {
+              result = {
+                ...result,
+                warnings: planWarnings,
+                missing_recommended: kanban.missingRecommendedCreateFields(args)
+              };
+            }
             break;
+          }
           case 'plan_advance':
             result = await plan.advance({ task_id: args.task_id, index: args.index });
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {