@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/tools/tasks.ts

@@ -0,0 +1,542 @@
+/**
+ * Task Tool Definitions
+ *
+ * Tools for task CRUD and management:
+ * - get_task
+ * - search_tasks
+ * - get_tasks_by_priority
+ * - get_recent_tasks
+ * - get_task_stats
+ * - get_next_task
+ * - add_task
+ * - update_task
+ * - complete_task
+ * - delete_task
+ * - cancel_task
+ * - release_task
+ * - add_task_reference
+ * - remove_task_reference
+ * - batch_update_tasks
+ * - batch_complete_tasks
+ * - add_subtask
+ * - get_subtasks
+ * - get_stale_worktrees
+ * - clear_worktree_path
+ */
+
+import type { Tool } from './types.js';
+
+export const taskTools: Tool[] = [
+	{
+		name: 'get_task',
+		description: `Get a single task by ID with optional subtasks and milestones.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				include_subtasks: {
+					type: 'boolean',
+					description: 'Include subtasks array (default: false)',
+				},
+				include_milestones: {
+					type: 'boolean',
+					description: 'Include milestones array (default: false)',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'search_tasks',
+		description: `Search tasks by text query. Supports pagination with offset. Use for finding specific tasks by title or description.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				query: {
+					type: 'string',
+					description: 'Search query (min 2 chars). Searches title and description.',
+				},
+				status: {
+					type: 'array',
+					items: { type: 'string', enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] },
+					description: 'Filter by status (optional, array)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max results per page (1-20, default: 10)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of results to skip for pagination (default: 0)',
+				},
+			},
+			required: ['project_id', 'query'],
+		},
+	},
+	{
+		name: 'get_tasks_by_priority',
+		description: `Get tasks filtered by priority. Supports pagination with offset. Use for finding high-priority or low-priority tasks.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Exact priority to match (1=highest, 5=lowest)',
+				},
+				priority_max: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Max priority (for range, e.g., priority=1, priority_max=2 gets P1 and P2)',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Filter by status (default: pending)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max results per page (1-20, default: 10)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of results to skip for pagination (default: 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_recent_tasks',
+		description: `Get tasks ordered by creation date. Supports pagination with offset. Use to find oldest pending tasks or newest additions.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				order: {
+					type: 'string',
+					enum: ['newest', 'oldest'],
+					description: 'Sort order (default: newest)',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max results per page (1-20, default: 10)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of results to skip for pagination (default: 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_task_stats',
+		description: `Get aggregate task statistics for a project. Returns counts by status and priority, no task data. Most token-efficient way to understand project state.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_next_task',
+		description: `Get highest priority pending task. Start it IMMEDIATELY by calling update_task(task_id, status: "in_progress").
+
+Do NOT ask the user for permission. Follow the directive in the response.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'add_task',
+		description: `Add a new task. Priority 1=highest, 5=lowest. Include estimated_minutes. Use blocking=true for deployment finalization tasks that must complete before other work.
+
+WHEN TO USE: If the user gives you work directly (e.g., "implement feature X", "fix this bug") that isn't already tracked as a task in Vibescope, you MUST create a task first using this tool. This ensures:
+- The work is visible on the dashboard
+- Progress can be tracked
+- Other agents won't duplicate the work
+- The human can see what you're working on`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Task title',
+				},
+				description: {
+					type: 'string',
+					description: 'Detailed description',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Priority 1-5 (1 = highest)',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Estimated time to complete in minutes',
+				},
+				blocking: {
+					type: 'boolean',
+					description: 'When true, this task blocks all other work until complete (used for deployment finalization)',
+				},
+				model_capability: {
+					type: 'string',
+					enum: ['haiku', 'sonnet', 'opus'],
+					description: 'Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning)',
+				},
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'update_task',
+		description: `Update task status, progress, or details. Include progress_note with progress_percentage.
+
+CRITICAL - WORKTREE REQUIRED: For projects using github-flow or git-flow, you MUST use a git worktree to isolate your work. This prevents conflicts with other agents working on the same repository.
+
+When setting status to "in_progress":
+1. Create worktree FIRST: git worktree add ../PROJECT-PERSONA-task-desc -b feature/TASKID-description BASE_BRANCH
+2. cd into the worktree directory
+3. THEN call update_task with git_branch AND worktree_path
+
+Example: update_task(task_id, status: "in_progress", git_branch: "feature/abc123-add-login", worktree_path: "../MyProject-Edge-add-login")
+
+For projects without git branching (trunk-based or none), use skip_worktree_requirement: true.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				title: { type: 'string', description: 'New task title' },
+				description: { type: 'string', description: 'New task description' },
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Task priority (1=highest, 5=lowest)',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Task status',
+				},
+				progress_percentage: {
+					type: 'number',
+					minimum: 0,
+					maximum: 100,
+					description: '0-100 completion percentage',
+				},
+				progress_note: {
+					type: 'string',
+					description: 'Brief note (auto-logged)',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Revised time estimate',
+				},
+				git_branch: {
+					type: 'string',
+					description: 'Git branch associated with this task. REQUIRED when status is "in_progress" (unless skip_worktree_requirement is true)',
+				},
+				worktree_path: {
+					type: 'string',
+					description: 'Git worktree path for this task (e.g., "../project-task-abc123"). Store this for cleanup tracking across sessions.',
+				},
+				worktree_hostname: {
+					type: 'string',
+					description: 'Machine hostname where worktree was created (os.hostname()). Required with worktree_path to enable machine-aware cleanup.',
+				},
+				model_capability: {
+					type: 'string',
+					enum: ['haiku', 'sonnet', 'opus'],
+					description: 'Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning)',
+				},
+				skip_worktree_requirement: {
+					type: 'boolean',
+					description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'complete_task',
+		description: `Mark task done. Returns next_task which you MUST start immediately without asking the user.
+
+CRITICAL: Before calling complete_task on branching workflows (github-flow, git-flow):
+1. Create your PR targeting the correct branch (develop for git-flow, main for github-flow)
+2. Call add_task_reference(task_id, pr_url) to link the PR to your task
+3. THEN call complete_task - validators CANNOT approve tasks without a PR reference
+
+CRITICAL: After calling this tool, you must:
+1. If next_task is returned → Start it immediately by calling update_task(task_id, status: "in_progress")
+2. If no next_task → Call get_next_task() or start a fallback_activity
+3. NEVER ask the user "What should I do next?" or "Should I continue?"
+
+The auto_continue: true flag in the response means you are expected to continue working autonomously.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				summary: {
+					type: 'string',
+					description: 'Brief summary of what was done. This is stored on the task as completion_summary and displayed when reviewing completed tasks.',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'delete_task',
+		description: `Delete a task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'cancel_task',
+		description: `Cancel a task with an optional reason. Use this when a task should be marked as cancelled rather than deleted (e.g., PR was closed, work was superseded). The task remains visible with a cancelled status for historical tracking.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				cancelled_reason: {
+					type: 'string',
+					description: 'Reason for cancellation',
+					enum: ['pr_closed', 'superseded', 'user_cancelled', 'validation_failed', 'obsolete', 'blocked'],
+				},
+				cancellation_note: {
+					type: 'string',
+					description: 'Optional note explaining the cancellation (logged to progress)',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'release_task',
+		description: `Release a claimed task back to pending status. Use when you need to give up a task you've started but cannot complete (e.g., context limits reached, conflicts with other work, user requested different approach). The task becomes available for other agents to claim.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				reason: {
+					type: 'string',
+					description: 'Optional reason for releasing the task (logged to progress)',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'add_task_reference',
+		description: 'Add a reference URL to a task (docs, PRs, issues).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				url: {
+					type: 'string',
+					description: 'URL to add as reference',
+				},
+				label: {
+					type: 'string',
+					description: 'Optional label/title for the reference',
+				},
+			},
+			required: ['task_id', 'url'],
+		},
+	},
+	{
+		name: 'remove_task_reference',
+		description: `Remove a reference link from a task by URL.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				url: {
+					type: 'string',
+					description: 'URL of the reference to remove',
+				},
+			},
+			required: ['task_id', 'url'],
+		},
+	},
+	{
+		name: 'batch_update_tasks',
+		description: 'Update multiple tasks at once. Include progress_note with progress_percentage.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				updates: {
+					type: 'array',
+					description: 'Array of task updates to apply',
+					items: {
+						type: 'object',
+						properties: {
+							task_id: { type: 'string', description: 'Task UUID' },
+							status: { type: 'string', enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] },
+							progress_percentage: { type: 'number', minimum: 0, maximum: 100 },
+							progress_note: { type: 'string', description: 'Brief note about what was achieved' },
+							priority: { type: 'number', minimum: 1, maximum: 5 },
+						},
+						required: ['task_id'],
+					},
+				},
+			},
+			required: ['updates'],
+		},
+	},
+	{
+		name: 'batch_complete_tasks',
+		description: `Mark multiple tasks as completed at once.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				completions: {
+					type: 'array',
+					description: 'Array of task completions',
+					items: {
+						type: 'object',
+						properties: {
+							task_id: { type: 'string', description: 'Task UUID' },
+							summary: { type: 'string', description: 'Optional completion summary' },
+						},
+						required: ['task_id'],
+					},
+				},
+			},
+			required: ['completions'],
+		},
+	},
+	{
+		name: 'add_subtask',
+		description: `Add a subtask to break down a larger task into smaller workable pieces.
+Subtasks can be claimed and worked on independently by any agent.
+Subtasks inherit the project from their parent task.
+Max depth is 1 (subtasks cannot have their own subtasks).`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				parent_task_id: {
+					type: 'string',
+					description: 'UUID of the parent task to add subtask to',
+				},
+				title: {
+					type: 'string',
+					description: 'Subtask title',
+				},
+				description: {
+					type: 'string',
+					description: 'Detailed description (optional)',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Priority 1-5 (1 = highest). Defaults to parent task priority.',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Estimated time to complete in minutes',
+				},
+			},
+			required: ['parent_task_id', 'title'],
+		},
+	},
+	{
+		name: 'get_subtasks',
+		description: `Get subtasks for a parent task with pagination.
+Returns subtasks with aggregate completion stats.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				parent_task_id: {
+					type: 'string',
+					description: 'UUID of the parent task',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max subtasks to return (default: 20, max: 50)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of subtasks to skip (default: 0)',
+				},
+			},
+			required: ['parent_task_id'],
+		},
+	},
+];