@vibescope/mcp-server 0.5.0 → 0.5.1

package/src/handlers/sprints.ts

@@ -1,537 +1,537 @@
-/**
- * Sprint Handlers
- *
- * Handles sprint-specific operations, leveraging bodies of work infrastructure:
- * - create_sprint
- * - update_sprint
- * - get_sprint
- * - get_sprints
- * - delete_sprint
- * - start_sprint
- * - complete_sprint
- * - add_task_to_sprint
- * - remove_task_from_sprint
- * - get_sprint_backlog
- * - get_sprint_velocity
- */
-
-import type { Handler, HandlerRegistry } from './types.js';
-import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
-import { getApiClient } from '../api-client.js';
-
-const SPRINT_STATUSES = ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled', 'archived'] as const;
-const TASK_PHASES = ['pre', 'core', 'post'] as const;
-const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
-const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
-
-type SprintStatus = typeof SPRINT_STATUSES[number];
-type TaskPhase = typeof TASK_PHASES[number];
-type DeployEnvironment = typeof DEPLOY_ENVIRONMENTS[number];
-type VersionBump = typeof VERSION_BUMPS[number];
-
-// ============================================================================
-// Argument Schemas
-// ============================================================================
-
-const createSprintSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const, required: true as const },
-	goal: { type: 'string' as const },
-	start_date: { type: 'string' as const, required: true as const },
-	end_date: { type: 'string' as const, required: true as const },
-	auto_deploy_on_completion: { type: 'boolean' as const },
-	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
-	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
-};
-
-const updateSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const },
-	goal: { type: 'string' as const },
-	start_date: { type: 'string' as const },
-	end_date: { type: 'string' as const },
-	auto_deploy_on_completion: { type: 'boolean' as const },
-	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
-	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
-};
-
-const getSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	summary_only: { type: 'boolean' as const, default: false },
-};
-
-const getSprintsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	status: { type: 'string' as const, validate: createEnumValidator(SPRINT_STATUSES) },
-	limit: { type: 'number' as const, default: 20 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const deleteSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const startSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const completeSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	retrospective_notes: { type: 'string' as const },
-	skip_retrospective: { type: 'boolean' as const },
-};
-
-const addTaskToSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	story_points: { type: 'number' as const },
-	phase: { type: 'string' as const, validate: createEnumValidator(TASK_PHASES) },
-};
-
-const removeTaskFromSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const getSprintBacklogSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	sprint_id: { type: 'string' as const, validate: uuidValidator },
-};
-
-const getSprintVelocitySchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	limit: { type: 'number' as const, default: 10 },
-};
-
-export const createSprint: Handler = async (args, ctx) => {
-	const {
-		project_id,
-		title,
-		goal,
-		start_date,
-		end_date,
-		auto_deploy_on_completion,
-		deploy_environment,
-		deploy_version_bump,
-	} = parseArgs(args, createSprintSchema);
-
-	// Validate date format and order
-	const startDateObj = new Date(start_date);
-	const endDateObj = new Date(end_date);
-	if (isNaN(startDateObj.getTime())) {
-		return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
-	}
-	if (isNaN(endDateObj.getTime())) {
-		return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
-	}
-	if (endDateObj < startDateObj) {
-		return { result: { error: 'end_date must be on or after start_date' }, isError: true };
-	}
-
-	const { session } = ctx;
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		sprint_number: number;
-	}>('create_sprint', {
-		project_id,
-		title,
-		goal,
-		start_date,
-		end_date,
-		auto_deploy_on_completion,
-		deploy_environment,
-		deploy_version_bump,
-	}, {
-		session_id: session.currentSessionId,
-		persona: session.currentPersona,
-		instance_id: session.instanceId
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to create sprint' }, isError: true };
-	}
-
-	return {
-		result: {
-			success: true,
-			sprint_id: response.data?.sprint_id,
-			sprint_number: response.data?.sprint_number,
-			title,
-			status: 'planning',
-			start_date,
-			end_date,
-			message: 'Sprint created in planning status. Add tasks with add_task_to_sprint, then call start_sprint when ready.',
-		},
-	};
-};
-
-export const updateSprint: Handler = async (args, ctx) => {
-	const {
-		sprint_id,
-		title,
-		goal,
-		start_date,
-		end_date,
-		auto_deploy_on_completion,
-		deploy_environment,
-		deploy_version_bump,
-	} = parseArgs(args, updateSprintSchema);
-
-	// Validate dates if provided
-	if (start_date) {
-		const startDateObj = new Date(start_date);
-		if (isNaN(startDateObj.getTime())) {
-			return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
-		}
-	}
-	if (end_date) {
-		const endDateObj = new Date(end_date);
-		if (isNaN(endDateObj.getTime())) {
-			return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
-		}
-	}
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{ success: boolean }>('update_sprint', {
-		sprint_id,
-		title,
-		goal,
-		start_date,
-		end_date,
-		auto_deploy_on_completion,
-		deploy_environment,
-		deploy_version_bump,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to update sprint' }, isError: true };
-	}
-
-	return { result: { success: true, sprint_id } };
-};
-
-export const getSprint: Handler = async (args, ctx) => {
-	const { sprint_id, summary_only } = parseArgs(args, getSprintSchema);
-
-	const apiClient = getApiClient();
-
-	// Response type varies based on summary_only
-	const response = await apiClient.proxy<{
-		id: string;
-		title: string;
-		goal?: string;
-		sprint_number: number;
-		sprint_status: SprintStatus;
-		start_date: string;
-		end_date: string;
-		progress_percentage: number;
-		total_estimated_minutes?: number;
-		completed_estimated_minutes?: number;
-		velocity_points: number;
-		committed_points: number;
-		// Full response includes task arrays
-		pre_tasks?: unknown[];
-		core_tasks?: unknown[];
-		post_tasks?: unknown[];
-		total_tasks?: number;
-		// Summary response includes counts and next task
-		task_counts?: {
-			pre: { total: number; completed: number };
-			core: { total: number; completed: number };
-			post: { total: number; completed: number };
-			total: number;
-			completed: number;
-			in_progress: number;
-		};
-		current_task?: { id: string; title: string } | null;
-		next_task?: { id: string; title: string; priority: number } | null;
-	}>('get_sprint', { sprint_id, summary_only });
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const getSprints: Handler = async (args, ctx) => {
-	const { project_id, status, limit, offset } = parseArgs(args, getSprintsSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		sprints: Array<{
-			id: string;
-			title: string;
-			goal?: string;
-			sprint_number: number;
-			sprint_status: SprintStatus;
-			start_date: string;
-			end_date: string;
-			progress_percentage: number;
-			total_estimated_minutes?: number;
-			completed_estimated_minutes?: number;
-			velocity_points: number;
-			committed_points: number;
-		}>;
-		total_count: number;
-		has_more: boolean;
-	}>('get_sprints', {
-		project_id,
-		status,
-		limit: Math.min(limit ?? 20, 100),
-		offset,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch sprints' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const deleteSprint: Handler = async (args, ctx) => {
-	const { sprint_id } = parseArgs(args, deleteSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{ success: boolean }>('delete_sprint', {
-		sprint_id
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to delete sprint' }, isError: true };
-	}
-
-	return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
-};
-
-export const startSprint: Handler = async (args, ctx) => {
-	const { sprint_id } = parseArgs(args, startSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		sprint_status: SprintStatus;
-		committed_points: number;
-		message: string;
-	}>('start_sprint', { sprint_id });
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to start sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const completeSprint: Handler = async (args, ctx) => {
-	const { sprint_id, retrospective_notes, skip_retrospective } = parseArgs(args, completeSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		sprint_status: SprintStatus;
-		velocity_points: number;
-		committed_points: number;
-		deployment_triggered?: boolean;
-		message: string;
-	}>('complete_sprint', {
-		sprint_id,
-		retrospective_notes,
-		skip_retrospective,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to complete sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const addTaskToSprint: Handler = async (args, ctx) => {
-	const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
-
-	if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
-		return { result: { error: 'story_points must be a non-negative integer' }, isError: true };
-	}
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		task_id: string;
-		story_points?: number;
-		phase: TaskPhase;
-		committed_points: number;
-	}>('add_task_to_sprint', {
-		sprint_id,
-		task_id,
-		story_points,
-		phase: phase || 'core',
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to add task to sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const removeTaskFromSprint: Handler = async (args, ctx) => {
-	const { sprint_id, task_id } = parseArgs(args, removeTaskFromSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		task_id: string;
-		committed_points: number;
-		message: string;
-	}>('remove_task_from_sprint', {
-		sprint_id,
-		task_id,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to remove task from sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const getSprintBacklog: Handler = async (args, ctx) => {
-	const { project_id, sprint_id } = parseArgs(args, getSprintBacklogSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		tasks: Array<{
-			id: string;
-			title: string;
-			priority: number;
-			status: string;
-			story_points?: number;
-			estimated_minutes?: number;
-		}>;
-		total_count: number;
-	}>('get_sprint_backlog', {
-		project_id,
-		sprint_id,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get sprint backlog' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const getSprintVelocity: Handler = async (args, ctx) => {
-	const { project_id, limit } = parseArgs(args, getSprintVelocitySchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		sprints: Array<{
-			sprint_number: number;
-			title: string;
-			committed_points: number;
-			velocity_points: number;
-			completion_rate: number;
-		}>;
-		average_velocity: number;
-		total_sprints: number;
-	}>('get_sprint_velocity', {
-		project_id,
-		limit: Math.min(limit ?? 10, 50),
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get sprint velocity' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-// ============================================================================
-// Archive / Unarchive Handlers
-// ============================================================================
-
-const archiveSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const unarchiveSprintSchema = {
-	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-export const archiveSprint: Handler = async (args, ctx) => {
-	const { sprint_id } = parseArgs(args, archiveSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		title: string;
-		sprint_number: number;
-		previous_status: string;
-		new_status: string;
-	}>('archive_sprint', { sprint_id });
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to archive sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const unarchiveSprint: Handler = async (args, ctx) => {
-	const { sprint_id } = parseArgs(args, unarchiveSprintSchema);
-
-	const apiClient = getApiClient();
-
-	const response = await apiClient.proxy<{
-		success: boolean;
-		sprint_id: string;
-		title: string;
-		sprint_number: number;
-		previous_status: string;
-		new_status: string;
-	}>('unarchive_sprint', { sprint_id });
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to unarchive sprint' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-/**
- * Sprint handlers registry
- */
-export const sprintHandlers: HandlerRegistry = {
-	create_sprint: createSprint,
-	update_sprint: updateSprint,
-	get_sprint: getSprint,
-	get_sprints: getSprints,
-	delete_sprint: deleteSprint,
-	start_sprint: startSprint,
-	complete_sprint: completeSprint,
-	add_task_to_sprint: addTaskToSprint,
-	remove_task_from_sprint: removeTaskFromSprint,
-	get_sprint_backlog: getSprintBacklog,
-	get_sprint_velocity: getSprintVelocity,
-	archive_sprint: archiveSprint,
-	unarchive_sprint: unarchiveSprint,
-};
+/**
+ * Sprint Handlers
+ *
+ * Handles sprint-specific operations, leveraging bodies of work infrastructure:
+ * - create_sprint
+ * - update_sprint
+ * - get_sprint
+ * - get_sprints
+ * - delete_sprint
+ * - start_sprint
+ * - complete_sprint
+ * - add_task_to_sprint
+ * - remove_task_from_sprint
+ * - get_sprint_backlog
+ * - get_sprint_velocity
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const SPRINT_STATUSES = ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled', 'archived'] as const;
+const TASK_PHASES = ['pre', 'core', 'post'] as const;
+const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
+
+type SprintStatus = typeof SPRINT_STATUSES[number];
+type TaskPhase = typeof TASK_PHASES[number];
+type DeployEnvironment = typeof DEPLOY_ENVIRONMENTS[number];
+type VersionBump = typeof VERSION_BUMPS[number];
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const createSprintSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	goal: { type: 'string' as const },
+	start_date: { type: 'string' as const, required: true as const },
+	end_date: { type: 'string' as const, required: true as const },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+};
+
+const updateSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	goal: { type: 'string' as const },
+	start_date: { type: 'string' as const },
+	end_date: { type: 'string' as const },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+};
+
+const getSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary_only: { type: 'boolean' as const, default: false },
+};
+
+const getSprintsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(SPRINT_STATUSES) },
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const deleteSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const startSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const completeSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	retrospective_notes: { type: 'string' as const },
+	skip_retrospective: { type: 'boolean' as const },
+};
+
+const addTaskToSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	story_points: { type: 'number' as const },
+	phase: { type: 'string' as const, validate: createEnumValidator(TASK_PHASES) },
+};
+
+const removeTaskFromSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const getSprintBacklogSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	sprint_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const getSprintVelocitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	limit: { type: 'number' as const, default: 10 },
+};
+
+export const createSprint: Handler = async (args, ctx) => {
+	const {
+		project_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	} = parseArgs(args, createSprintSchema);
+
+	// Validate date format and order
+	const startDateObj = new Date(start_date);
+	const endDateObj = new Date(end_date);
+	if (isNaN(startDateObj.getTime())) {
+		return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
+	}
+	if (isNaN(endDateObj.getTime())) {
+		return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
+	}
+	if (endDateObj < startDateObj) {
+		return { result: { error: 'end_date must be on or after start_date' }, isError: true };
+	}
+
+	const { session } = ctx;
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_number: number;
+	}>('create_sprint', {
+		project_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	}, {
+		session_id: session.currentSessionId,
+		persona: session.currentPersona,
+		instance_id: session.instanceId
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to create sprint' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			sprint_id: response.data?.sprint_id,
+			sprint_number: response.data?.sprint_number,
+			title,
+			status: 'planning',
+			start_date,
+			end_date,
+			message: 'Sprint created in planning status. Add tasks with add_task_to_sprint, then call start_sprint when ready.',
+		},
+	};
+};
+
+export const updateSprint: Handler = async (args, ctx) => {
+	const {
+		sprint_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	} = parseArgs(args, updateSprintSchema);
+
+	// Validate dates if provided
+	if (start_date) {
+		const startDateObj = new Date(start_date);
+		if (isNaN(startDateObj.getTime())) {
+			return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
+		}
+	}
+	if (end_date) {
+		const endDateObj = new Date(end_date);
+		if (isNaN(endDateObj.getTime())) {
+			return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
+		}
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{ success: boolean }>('update_sprint', {
+		sprint_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to update sprint' }, isError: true };
+	}
+
+	return { result: { success: true, sprint_id } };
+};
+
+export const getSprint: Handler = async (args, ctx) => {
+	const { sprint_id, summary_only } = parseArgs(args, getSprintSchema);
+
+	const apiClient = getApiClient();
+
+	// Response type varies based on summary_only
+	const response = await apiClient.proxy<{
+		id: string;
+		title: string;
+		goal?: string;
+		sprint_number: number;
+		sprint_status: SprintStatus;
+		start_date: string;
+		end_date: string;
+		progress_percentage: number;
+		total_estimated_minutes?: number;
+		completed_estimated_minutes?: number;
+		velocity_points: number;
+		committed_points: number;
+		// Full response includes task arrays
+		pre_tasks?: unknown[];
+		core_tasks?: unknown[];
+		post_tasks?: unknown[];
+		total_tasks?: number;
+		// Summary response includes counts and next task
+		task_counts?: {
+			pre: { total: number; completed: number };
+			core: { total: number; completed: number };
+			post: { total: number; completed: number };
+			total: number;
+			completed: number;
+			in_progress: number;
+		};
+		current_task?: { id: string; title: string } | null;
+		next_task?: { id: string; title: string; priority: number } | null;
+	}>('get_sprint', { sprint_id, summary_only });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getSprints: Handler = async (args, ctx) => {
+	const { project_id, status, limit, offset } = parseArgs(args, getSprintsSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		sprints: Array<{
+			id: string;
+			title: string;
+			goal?: string;
+			sprint_number: number;
+			sprint_status: SprintStatus;
+			start_date: string;
+			end_date: string;
+			progress_percentage: number;
+			total_estimated_minutes?: number;
+			completed_estimated_minutes?: number;
+			velocity_points: number;
+			committed_points: number;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>('get_sprints', {
+		project_id,
+		status,
+		limit: Math.min(limit ?? 20, 100),
+		offset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch sprints' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const deleteSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = parseArgs(args, deleteSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{ success: boolean }>('delete_sprint', {
+		sprint_id
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to delete sprint' }, isError: true };
+	}
+
+	return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
+};
+
+export const startSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = parseArgs(args, startSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_status: SprintStatus;
+		committed_points: number;
+		message: string;
+	}>('start_sprint', { sprint_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to start sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const completeSprint: Handler = async (args, ctx) => {
+	const { sprint_id, retrospective_notes, skip_retrospective } = parseArgs(args, completeSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_status: SprintStatus;
+		velocity_points: number;
+		committed_points: number;
+		deployment_triggered?: boolean;
+		message: string;
+	}>('complete_sprint', {
+		sprint_id,
+		retrospective_notes,
+		skip_retrospective,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to complete sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const addTaskToSprint: Handler = async (args, ctx) => {
+	const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
+
+	if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
+		return { result: { error: 'story_points must be a non-negative integer' }, isError: true };
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		task_id: string;
+		story_points?: number;
+		phase: TaskPhase;
+		committed_points: number;
+	}>('add_task_to_sprint', {
+		sprint_id,
+		task_id,
+		story_points,
+		phase: phase || 'core',
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to add task to sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const removeTaskFromSprint: Handler = async (args, ctx) => {
+	const { sprint_id, task_id } = parseArgs(args, removeTaskFromSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		task_id: string;
+		committed_points: number;
+		message: string;
+	}>('remove_task_from_sprint', {
+		sprint_id,
+		task_id,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to remove task from sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getSprintBacklog: Handler = async (args, ctx) => {
+	const { project_id, sprint_id } = parseArgs(args, getSprintBacklogSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			priority: number;
+			status: string;
+			story_points?: number;
+			estimated_minutes?: number;
+		}>;
+		total_count: number;
+	}>('get_sprint_backlog', {
+		project_id,
+		sprint_id,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get sprint backlog' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getSprintVelocity: Handler = async (args, ctx) => {
+	const { project_id, limit } = parseArgs(args, getSprintVelocitySchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		sprints: Array<{
+			sprint_number: number;
+			title: string;
+			committed_points: number;
+			velocity_points: number;
+			completion_rate: number;
+		}>;
+		average_velocity: number;
+		total_sprints: number;
+	}>('get_sprint_velocity', {
+		project_id,
+		limit: Math.min(limit ?? 10, 50),
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get sprint velocity' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+// ============================================================================
+// Archive / Unarchive Handlers
+// ============================================================================
+
+const archiveSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const unarchiveSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const archiveSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = parseArgs(args, archiveSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		title: string;
+		sprint_number: number;
+		previous_status: string;
+		new_status: string;
+	}>('archive_sprint', { sprint_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to archive sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const unarchiveSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = parseArgs(args, unarchiveSprintSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		title: string;
+		sprint_number: number;
+		previous_status: string;
+		new_status: string;
+	}>('unarchive_sprint', { sprint_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to unarchive sprint' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Sprint handlers registry
+ */
+export const sprintHandlers: HandlerRegistry = {
+	create_sprint: createSprint,
+	update_sprint: updateSprint,
+	get_sprint: getSprint,
+	get_sprints: getSprints,
+	delete_sprint: deleteSprint,
+	start_sprint: startSprint,
+	complete_sprint: completeSprint,
+	add_task_to_sprint: addTaskToSprint,
+	remove_task_from_sprint: removeTaskFromSprint,
+	get_sprint_backlog: getSprintBacklog,
+	get_sprint_velocity: getSprintVelocity,
+	archive_sprint: archiveSprint,
+	unarchive_sprint: unarchiveSprint,
+};