sqlew 2.1.4 → 3.0.2

package/docs/TASK_ACTIONS.md

@@ -0,0 +1,854 @@
+# Task Actions Reference
+
+**Version:** 3.0.0
+**Last Updated:** 2025-10-17
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Action: create](#action-create)
+3. [Action: update](#action-update)
+4. [Action: get](#action-get)
+5. [Action: list](#action-list)
+6. [Action: move](#action-move)
+7. [Action: link](#action-link)
+8. [Action: archive](#action-archive)
+9. [Action: batch_create](#action-batch_create)
+10. [Action: help](#action-help)
+11. [Best Practices](#best-practices)
+12. [Common Errors](#common-errors)
+13. [Related Documentation](#related-documentation)
+
+## Overview
+
+The `task` MCP tool provides 9 actions for managing tasks in the Kanban Task Watcher system. All actions require the `action` parameter.
+
+**Action-Based API Pattern:**
+```javascript
+{
+  action: "create",  // Required: specifies which action to execute
+  // ... action-specific parameters
+}
+```
+
+## Action: create
+
+Create a new task.
+
+### Parameters
+
+**Required:**
+- `action`: "create"
+- `title`: Task title (string)
+
+**Optional:**
+- `description`: Full task description (string)
+- `status`: Initial status (string: "todo", "in_progress", "waiting_review", "blocked", "done", "archived") - default: "todo"
+- `priority`: Priority level (string: "low", "medium", "high", "critical")
+- `assignee`: Agent or user assigned (string)
+- `tags`: Array of tags (string[])
+- `layer`: Architecture layer (string: "presentation", "business", "data", "infrastructure", "cross-cutting")
+
+### Examples
+
+**Minimal Task:**
+```javascript
+{
+  action: "create",
+  title: "Implement JWT authentication"
+}
+```
+
+**Complete Task:**
+```javascript
+{
+  action: "create",
+  title: "Implement JWT authentication",
+  description: "Add JWT-based authentication with refresh tokens",
+  status: "todo",
+  priority: "high",
+  assignee: "auth-agent",
+  tags: ["security", "authentication"],
+  layer: "business"
+}
+```
+
+**Task with Multiple Tags:**
+```javascript
+{
+  action: "create",
+  title: "Optimize database queries",
+  description: "Improve query performance for user listings",
+  priority: "medium",
+  tags: ["performance", "database", "optimization"],
+  layer: "data"
+}
+```
+
+### Response
+
+```javascript
+{
+  task_id: 1,
+  message: "Task created successfully"
+}
+```
+
+## Action: update
+
+Update existing task fields.
+
+### Parameters
+
+**Required:**
+- `action`: "update"
+- `task_id`: Task ID (number)
+
+**Optional (at least one required):**
+- `title`: New title (string)
+- `status`: New status (string) - bypasses validation, use `move` instead
+- `description`: New description (string)
+- `priority`: New priority (string)
+- `assignee`: New assignee (string)
+- `tags`: New tags array (string[]) - replaces existing tags
+- `layer`: New layer (string)
+
+### Examples
+
+**Update Description:**
+```javascript
+{
+  action: "update",
+  task_id: 1,
+  description: "Updated requirements: Add OAuth2 support"
+}
+```
+
+**Update Priority:**
+```javascript
+{
+  action: "update",
+  task_id: 1,
+  priority: "critical"
+}
+```
+
+**Update Multiple Fields:**
+```javascript
+{
+  action: "update",
+  task_id: 1,
+  description: "Add OAuth2 and SAML support",
+  priority: "critical",
+  tags: ["security", "authentication", "oauth2", "saml"]
+}
+```
+
+**Reassign Task:**
+```javascript
+{
+  action: "update",
+  task_id: 1,
+  assignee: "senior-auth-agent",
+  priority: "high"
+}
+```
+
+### Response
+
+```javascript
+{
+  success: true,
+  message: "Task updated successfully"
+}
+```
+
+### Important Notes
+
+- Use `move` action for status changes (validates transitions)
+- `update` bypasses state machine validation
+- Updating `tags` replaces all existing tags (not append)
+
+## Action: get
+
+Get single task with full details.
+
+### Parameters
+
+**Required:**
+- `action`: "get"
+- `task_id`: Task ID (number)
+
+### Example
+
+```javascript
+{
+  action: "get",
+  task_id: 1
+}
+```
+
+### Response
+
+```javascript
+{
+  task_id: 1,
+  title: "Implement JWT authentication",
+  description: "Add JWT-based authentication with refresh tokens",
+  status: "in_progress",
+  priority: "high",
+  assignee: "auth-agent",
+  layer: "business",
+  tags: ["security", "authentication"],
+  created_ts: 1697545200,
+  updated_ts: 1697545800,
+  decision_links: ["auth_method", "jwt_secret"],
+  constraint_links: [5],
+  file_links: ["/src/auth/jwt.ts", "/src/auth/middleware.ts"]
+}
+```
+
+### Token Efficiency
+
+- **~332 bytes/task** (includes description and links)
+- Use `list` for browsing, `get` only when details needed
+
+## Action: list
+
+List tasks with filtering (metadata only, no descriptions).
+
+### Parameters
+
+**Required:**
+- `action`: "list"
+
+**Optional:**
+- `status`: Filter by status (string)
+- `priority`: Filter by priority (string)
+- `assignee`: Filter by assignee (string)
+- `tags`: Filter by tags (string[])
+- `layer`: Filter by layer (string)
+- `limit`: Maximum results (number) - default: 100
+
+### Examples
+
+**List All Tasks:**
+```javascript
+{
+  action: "list"
+}
+```
+
+**Filter by Status:**
+```javascript
+{
+  action: "list",
+  status: "in_progress"
+}
+```
+
+**Filter by Assignee:**
+```javascript
+{
+  action: "list",
+  assignee: "auth-agent"
+}
+```
+
+**Multiple Filters:**
+```javascript
+{
+  action: "list",
+  status: "in_progress",
+  assignee: "auth-agent",
+  tags: ["security"],
+  priority: "high"
+}
+```
+
+**Limit Results:**
+```javascript
+{
+  action: "list",
+  status: "todo",
+  limit: 20
+}
+```
+
+### Response
+
+```javascript
+{
+  tasks: [
+    {
+      task_id: 1,
+      title: "Implement JWT authentication",
+      status_name: "in_progress",
+      priority_name: "high",
+      assignee: "auth-agent",
+      layer_name: "business",
+      tags: "security,authentication",
+      created_ts: 1697545200,
+      updated_ts: 1697545800
+    },
+    {
+      task_id: 2,
+      title: "Setup OAuth2 provider",
+      status_name: "in_progress",
+      priority_name: "high",
+      assignee: "auth-agent",
+      layer_name: "business",
+      tags: "security,oauth2",
+      created_ts: 1697545300,
+      updated_ts: 1697545900
+    }
+  ],
+  count: 2,
+  stale_tasks_transitioned: 0
+}
+```
+
+### Token Efficiency
+
+- **~100 bytes/task** (metadata only)
+- **70% reduction** vs full task with description
+- Auto-stale detection runs before list
+- Returns `stale_tasks_transitioned` count
+
+## Action: move
+
+Move task to new status with validation.
+
+### Parameters
+
+**Required:**
+- `action`: "move"
+- `task_id`: Task ID (number)
+- `new_status`: Target status (string: "todo", "in_progress", "waiting_review", "blocked", "done", "archived")
+
+### Examples
+
+**Move to Waiting Review:**
+```javascript
+{
+  action: "move",
+  task_id: 1,
+  new_status: "waiting_review"
+}
+```
+
+**Move to Blocked:**
+```javascript
+{
+  action: "move",
+  task_id: 1,
+  new_status: "blocked"
+}
+```
+
+**Move to Done:**
+```javascript
+{
+  action: "move",
+  task_id: 1,
+  new_status: "done"
+}
+```
+
+### Response (Success)
+
+```javascript
+{
+  success: true,
+  message: "Task moved from in_progress to waiting_review"
+}
+```
+
+### Response (Invalid Transition)
+
+```javascript
+{
+  error: "Invalid status transition from in_progress to archived. Valid transitions: waiting_review, blocked, done"
+}
+```
+
+### State Machine Validation
+
+**Valid Transitions:**
+
+| From Status | To Status(es) |
+|-------------|--------------|
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `waiting_review`, `blocked`, `done` |
+| `waiting_review` | `in_progress`, `todo`, `done` |
+| `blocked` | `todo`, `in_progress` |
+| `done` | `archived` |
+| `archived` | *(terminal state)* |
+
+**Auto-Stale Detection:**
+- Runs before move operation
+- Returns `stale_tasks_transitioned` count
+
+## Action: link
+
+Link task to decision, constraint, or file.
+
+### Parameters
+
+**Required:**
+- `action`: "link"
+- `task_id`: Task ID (number)
+- `link_type`: Link type (string: "decision", "constraint", "file")
+
+**Type-Specific Required Parameters:**
+- `link_type="decision"`: `link_key` (string) - Decision key
+- `link_type="constraint"`: `link_id` (number) - Constraint ID
+- `link_type="file"`: `link_path` (string) - File path
+
+### Examples
+
+**Link to Decision:**
+```javascript
+{
+  action: "link",
+  task_id: 1,
+  link_type: "decision",
+  link_key: "auth_method"
+}
+```
+
+**Link to Constraint:**
+```javascript
+{
+  action: "link",
+  task_id: 1,
+  link_type: "constraint",
+  link_id: 5
+}
+```
+
+**Link to File:**
+```javascript
+{
+  action: "link",
+  task_id: 1,
+  link_type: "file",
+  link_path: "/src/auth/jwt.ts"
+}
+```
+
+**Multiple Links:**
+```javascript
+// Link to decision
+{
+  action: "link",
+  task_id: 1,
+  link_type: "decision",
+  link_key: "auth_method"
+}
+
+// Link to constraint
+{
+  action: "link",
+  task_id: 1,
+  link_type: "constraint",
+  link_id: 5
+}
+
+// Link to file
+{
+  action: "link",
+  task_id: 1,
+  link_type: "file",
+  link_path: "/src/auth/jwt.ts"
+}
+```
+
+### Response
+
+```javascript
+{
+  success: true,
+  message: "Task linked to decision 'auth_method'"
+}
+```
+
+**See [TASK_LINKING.md](TASK_LINKING.md) for detailed linking strategies and use cases.**
+
+## Action: archive
+
+Archive completed task (soft delete).
+
+### Parameters
+
+**Required:**
+- `action`: "archive"
+- `task_id`: Task ID (number)
+
+### Example
+
+```javascript
+{
+  action: "archive",
+  task_id: 1
+}
+```
+
+### Response (Success)
+
+```javascript
+{
+  success: true,
+  message: "Task archived successfully"
+}
+```
+
+### Response (Error)
+
+```javascript
+{
+  error: "Cannot archive task not in done status"
+}
+```
+
+### Important Notes
+
+- Only tasks with `status="done"` can be archived
+- Archived tasks have `status="archived"` (terminal state)
+- Use `move` to transition to `done` first if needed
+
+**Workflow:**
+```javascript
+// 1. Complete task
+{ action: "move", task_id: 1, new_status: "done" }
+
+// 2. Archive task
+{ action: "archive", task_id: 1 }
+```
+
+## Action: batch_create
+
+Create multiple tasks atomically or best-effort.
+
+### Parameters
+
+**Required:**
+- `action`: "batch_create"
+- `tasks`: Array of task objects (max 50)
+
+**Optional:**
+- `atomic`: Boolean (default: true) - All-or-nothing vs best-effort mode
+
+### Examples
+
+**Atomic Batch (All-or-Nothing):**
+```javascript
+{
+  action: "batch_create",
+  tasks: [
+    {
+      title: "Setup database schema",
+      status: "todo",
+      priority: "high",
+      assignee: "db-agent"
+    },
+    {
+      title: "Implement API endpoints",
+      status: "todo",
+      priority: "medium",
+      assignee: "api-agent"
+    }
+  ],
+  atomic: true  // All succeed or all fail
+}
+```
+
+**Best-Effort Batch (Recommended for AI):**
+```javascript
+{
+  action: "batch_create",
+  tasks: [
+    {
+      title: "Setup database schema",
+      status: "todo",
+      priority: "high",
+      assignee: "db-agent",
+      tags: ["database", "setup"]
+    },
+    {
+      title: "Implement API endpoints",
+      status: "todo",
+      priority: "medium",
+      assignee: "api-agent",
+      tags: ["api", "development"]
+    },
+    {
+      title: "Write integration tests",
+      status: "todo",
+      priority: "low",
+      assignee: "test-agent",
+      tags: ["testing", "qa"]
+    }
+  ],
+  atomic: false  // Allows partial success
+}
+```
+
+### Response (Atomic=true, Success)
+
+```javascript
+{
+  success: true,
+  created_count: 2,
+  task_ids: [1, 2]
+}
+```
+
+### Response (Atomic=false, Partial Success)
+
+```javascript
+{
+  success: true,
+  created_count: 2,
+  failed_count: 1,
+  task_ids: [1, 2],
+  errors: ["Task 3: Invalid priority 'ultra-high'"]
+}
+```
+
+### Important Notes
+
+- **Max 50 tasks** per batch
+- **Atomic mode (true):** Transaction fails if any task fails
+- **Best-effort mode (false):** Partial success allowed (recommended for AI)
+- Each task follows same schema as `create` action
+
+## Action: help
+
+Get comprehensive on-demand documentation.
+
+### Parameters
+
+**Required:**
+- `action`: "help"
+
+### Example
+
+```javascript
+{
+  action: "help"
+}
+```
+
+### Response
+
+Returns complete tool documentation including:
+- Parameter matrices for all actions
+- Examples for each action
+- Status transition rules
+- Token efficiency tips
+- Common errors and solutions
+
+## Best Practices
+
+### For AI Agents
+
+**1. Always Use `action` Parameter**
+```javascript
+// ❌ WRONG
+{ task_id: 1 }
+
+// ✅ CORRECT
+{ action: "get", task_id: 1 }
+```
+
+**2. Use `move` for Status Changes (Not `update`)**
+```javascript
+// ❌ WRONG (bypasses validation)
+{ action: "update", task_id: 1, status: "archived" }
+
+// ✅ CORRECT (validates transition)
+{ action: "move", task_id: 1, new_status: "waiting_review" }
+```
+
+**3. Use `list` Before `get`**
+```javascript
+// ❌ WRONG (loads all descriptions)
+tasks.forEach(t => get({ action: "get", task_id: t.id }))
+
+// ✅ CORRECT (metadata first, details on demand)
+const tasks = list({ action: "list", status: "in_progress" });
+const details = get({ action: "get", task_id: tasks.tasks[0].task_id });
+```
+
+**4. Prefer Batch Operations**
+```javascript
+// ❌ INEFFICIENT (multiple calls)
+create({ action: "create", title: "Task 1" });
+create({ action: "create", title: "Task 2" });
+create({ action: "create", title: "Task 3" });
+
+// ✅ EFFICIENT (one call)
+batch_create({
+  action: "batch_create",
+  tasks: [
+    { title: "Task 1" },
+    { title: "Task 2" },
+    { title: "Task 3" }
+  ],
+  atomic: false
+});
+```
+
+**5. Link Tasks to Context**
+```javascript
+// Create task
+const task = create({ action: "create", title: "Implement auth" });
+
+// Link to decision
+link({
+  action: "link",
+  task_id: task.task_id,
+  link_type: "decision",
+  link_key: "auth_method"
+});
+
+// Link to file
+link({
+  action: "link",
+  task_id: task.task_id,
+  link_type: "file",
+  link_path: "/src/auth/jwt.ts"
+});
+```
+
+### For Multi-Agent Workflows
+
+**1. Use Assignee for Coordination**
+```javascript
+// Agent A creates task for Agent B
+{
+  action: "create",
+  title: "Implement auth middleware",
+  assignee: "auth-agent",
+  tags: ["handoff"]
+}
+
+// Agent B lists assigned tasks
+{
+  action: "list",
+  assignee: "auth-agent",
+  status: "todo"
+}
+```
+
+**2. Use Priority for Orchestration**
+```javascript
+// Critical blocker
+{ action: "create", title: "Fix DB connection", priority: "critical" }
+
+// High priority
+{ action: "create", title: "Implement API", priority: "high" }
+
+// Background work
+{ action: "create", title: "Update docs", priority: "low" }
+```
+
+**3. Track Dependencies with Links**
+```javascript
+// Task depends on constraint
+{
+  action: "link",
+  task_id: 5,
+  link_type: "constraint",
+  link_id: 3  // "DB schema must be finalized"
+}
+```
+
+## Common Errors
+
+### Error: "Invalid status transition"
+
+**Problem:**
+```javascript
+// Trying to move from in_progress to archived
+{ action: "move", task_id: 1, new_status: "archived" }
+```
+
+**Solution:**
+```javascript
+// Move to done first
+{ action: "move", task_id: 1, new_status: "done" }
+{ action: "archive", task_id: 1 }
+```
+
+### Error: "Task not found"
+
+**Problem:**
+```javascript
+// Invalid task_id
+{ action: "get", task_id: 9999 }
+```
+
+**Solution:**
+```javascript
+// List tasks first to get valid IDs
+{ action: "list" }
+```
+
+### Error: "Invalid link type"
+
+**Problem:**
+```javascript
+// Typo in link_type
+{ action: "link", task_id: 1, link_type: "decisions" }
+```
+
+**Solution:**
+```javascript
+// Use exact link_type
+{ action: "link", task_id: 1, link_type: "decision", link_key: "..." }
+```
+
+### Error: "Cannot archive task not in done status"
+
+**Problem:**
+```javascript
+// Trying to archive incomplete task
+{ action: "archive", task_id: 1 }  // Task is in_progress
+```
+
+**Solution:**
+```javascript
+// Complete task first
+{ action: "move", task_id: 1, new_status: "done" }
+{ action: "archive", task_id: 1 }
+```
+
+### Error: "Unknown action"
+
+**Problem:**
+```javascript
+// Missing action parameter
+{ task_id: 1 }
+```
+
+**Solution:**
+```javascript
+// Always include action
+{ action: "get", task_id: 1 }
+```
+
+## Related Documentation
+
+- **[TASK_OVERVIEW.md](TASK_OVERVIEW.md)** - Task system overview and core concepts
+- **[TASK_LINKING.md](TASK_LINKING.md)** - Linking tasks to decisions/constraints/files
+- **[TASK_MIGRATION.md](TASK_MIGRATION.md)** - Migrating from decision-based task tracking
+- **[TASK_SYSTEM.md](TASK_SYSTEM.md)** - Complete documentation (original)
+- **[AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md)** - Comprehensive AI agent guide
+
+---
+
+**Version:** 3.0.0
+**Last Updated:** 2025-10-17
+**Author:** sin5ddd