@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/tools/tasks.ts

@@ -1,575 +1,583 @@
-/**
- * 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)',
-				},
-				assigned_agent_name: {
-					type: 'string',
-					description: 'Pre-assign this task to a specific agent by persona name. Only that agent will pick it up via get_next_task.',
-				},
-			},
-			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)',
-				},
-				assigned_agent_name: {
-					type: ['string', 'null'],
-					description: 'Pre-assign this task to a specific agent by persona name. Set to null to unassign. Only the assigned agent will pick it up via get_next_task.',
-				},
-				skip_worktree_requirement: {
-					type: 'boolean',
-					description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
-				},
-				session_id: {
-					type: 'string',
-					description: 'Session ID from start_work_session. Required for cloud agents using mcporter (session context is not preserved between calls). Links the task to your agent on the dashboard.',
-				},
-			},
-			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.',
-				},
-				session_id: {
-					type: 'string',
-					description: 'Session ID from start_work_session. Required for cloud agents using mcporter.',
-				},
-				commit_hash: {
-					type: 'string',
-					description: 'Git commit hash (7-40 hex chars) of your last commit. Stored on the task for verification.',
-				},
-				check_results: {
-					type: 'array',
-					description: 'Results of pre-completion checks (required if project has pre_completion_commands configured). Each item: { command, passed, output? }',
-					items: {
-						type: 'object',
-						properties: {
-							command: { type: 'string', description: 'The command that was run' },
-							passed: { type: 'boolean', description: 'Whether the command succeeded' },
-							output: { type: 'string', description: 'First 500 chars of output if failed' },
-						},
-						required: ['command', 'passed'],
-					},
-				},
-			},
-			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'],
-		},
-	},
-];
+/**
+ * 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)',
+				},
+				assigned_agent_name: {
+					type: 'string',
+					description: 'Pre-assign this task to a specific agent by persona name. Only that agent will pick it up via get_next_task.',
+				},
+				is_human_task: {
+					type: 'boolean',
+					description: 'When true, only humans can claim and perform this task. Agents will skip it in get_next_task.',
+				},
+			},
+			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)',
+				},
+				assigned_agent_name: {
+					type: ['string', 'null'],
+					description: 'Pre-assign this task to a specific agent by persona name. Set to null to unassign. Only the assigned agent will pick it up via get_next_task.',
+				},
+				is_human_task: {
+					type: 'boolean',
+					description: 'When true, only humans can claim and perform this task. Agents will skip it in get_next_task.',
+				},
+				skip_worktree_requirement: {
+					type: 'boolean',
+					description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
+				},
+				session_id: {
+					type: 'string',
+					description: 'Session ID from start_work_session. Required for cloud agents using mcporter (session context is not preserved between calls). Links the task to your agent on the dashboard.',
+				},
+			},
+			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.',
+				},
+				session_id: {
+					type: 'string',
+					description: 'Session ID from start_work_session. Required for cloud agents using mcporter.',
+				},
+				commit_hash: {
+					type: 'string',
+					description: 'Git commit hash (7-40 hex chars) of your last commit. Stored on the task for verification.',
+				},
+				check_results: {
+					type: 'array',
+					description: 'Results of pre-completion checks (required if project has pre_completion_commands configured). Each item: { command, passed, output? }',
+					items: {
+						type: 'object',
+						properties: {
+							command: { type: 'string', description: 'The command that was run' },
+							passed: { type: 'boolean', description: 'Whether the command succeeded' },
+							output: { type: 'string', description: 'First 500 chars of output if failed' },
+						},
+						required: ['command', 'passed'],
+					},
+				},
+			},
+			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'],
+		},
+	},
+];