@vibescope/mcp-server 0.4.0 → 0.4.2

package/src/handlers/session.ts

@@ -179,10 +179,29 @@ export const startWorkSession: Handler = async (args, ctx) => {
 
 	// Session info
 	result.session_id = data.session_id;
+	result.IMPORTANT_session_id_reminder = `Save this session_id ("${data.session_id}") and pass it on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.`;
 	result.persona = data.persona;
 	result.role = data.role;
 	result.project = data.project;
 
+	// For cloud agents: include workspace setup instructions if repo not yet cloned
+	// Cloud agents pass git_url; check if workspace needs setup
+	if (git_url && data.project?.git_url) {
+		result.workspace_setup = {
+			message: 'If the project repo is NOT already cloned to your workspace, follow these steps:',
+			steps: [
+				`git clone ${data.project.git_url} ~/workspace/project`,
+				'cd ~/workspace/project',
+				...(data.project.git_workflow === 'git-flow'
+					? [`git checkout ${data.project.git_develop_branch || 'develop'}`]
+					: []),
+				'Install dependencies (check for pnpm-lock.yaml, package-lock.json, etc.)',
+				'If using SvelteKit: run `pnpm exec svelte-kit sync` or equivalent',
+			],
+			note: 'Skip these steps if ~/workspace/project already exists and has the repo.',
+		};
+	}
+
 	// Inform agent if git_url was normalized (helps explain URL matching behavior)
 	if (gitUrlWasNormalized) {
 		result.git_url_normalized = {
@@ -302,6 +321,111 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		}
 	}
 
+	// Build dynamic AGENT_RULES from project settings
+	const agentRules: string[] = [];
+	const projectWorkflow = data.project?.git_workflow;
+	const isBranching = projectWorkflow === 'git-flow' || projectWorkflow === 'github-flow';
+	const ruleBaseBranch = projectWorkflow === 'git-flow'
+		? (data.project?.git_develop_branch || 'develop')
+		: (data.project?.git_main_branch || 'main');
+
+	// Git workflow rules (dynamic based on project settings)
+	if (isBranching) {
+		agentRules.push(`WORKTREE REQUIRED: Create a git worktree BEFORE making ANY file edits. Command: git worktree add ../PROJECT-PERSONA-task -b feature/TASKID-desc ${ruleBaseBranch}`);
+		agentRules.push(`REBASE BEFORE PR: Always rebase onto ${ruleBaseBranch} before creating a PR. Run: git fetch origin && git rebase origin/${ruleBaseBranch} && git push --force-with-lease. This prevents overwriting other agents' work.`);
+	}
+	if (projectWorkflow && projectWorkflow !== 'none') {
+		agentRules.push(`GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
+	}
+
+	// Task lifecycle rules
+	agentRules.push('COMPLETE TASKS: Always call complete_task(task_id, summary, session_id) immediately after creating a PR. This is mandatory — it updates the dashboard and triggers validation.');
+	agentRules.push('SESSION ID: Pass session_id on EVERY update_task and complete_task call. Without it, the dashboard shows "Agent" instead of your name.');
+	agentRules.push(`STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE", project_id: "${data.project?.id || ''}", agent_name: "${result.persona || ''}") whenever you start or finish a task.`);
+	agentRules.push('TRACK PROGRESS: Call update_task with progress_percentage (0-100) every 15-20% of task completion.');
+
+	// Validation rules (dynamic based on project settings)
+	if (data.project?.validation_required !== false) {
+		agentRules.push('REVIEW REQUIRED: All completed tasks must be reviewed/validated by another agent before merging.');
+	}
+	if (data.project?.auto_merge_on_approval !== false) {
+		agentRules.push('AUTO-MERGE: After approving a PR during validation, merge it immediately with `gh pr merge --squash`.');
+	}
+
+	// Autonomy rules
+	agentRules.push('BE AUTONOMOUS: Pick up tasks without asking permission. Never ask "Should I continue?" — just continue to the next task.');
+	agentRules.push('BREAK DOWN COMPLEX TASKS: If a task is too large, create subtasks with add_subtask() and start on the first one immediately.');
+
+	result.AGENT_RULES = agentRules;
+
+	// Build WORKFLOW section — dynamic step-by-step instructions
+	// This replaces the hardcoded workflow in CLAUDE.md
+	const workflow: Record<string, unknown> = {};
+
+	// Continuous work loop
+	workflow.continuous_work = {
+		description: 'After completing a task, immediately continue to the next one.',
+		steps: [
+			'complete_task(task_id, summary, session_id) — returns next_task if available',
+			'If no next_task returned: call get_next_task(project_id)',
+			'If no tasks available: call get_pending_requests(project_id) and handle any',
+			'If still nothing: call signal_idle() then start_fallback_activity(project_id, activity: "code_review")',
+		],
+		rule: 'Never ask permission. Never stop working while tasks exist.',
+	};
+
+	// Validation workflow (only if validation is enabled)
+	if (data.project?.validation_required !== false) {
+		workflow.validation = {
+			description: 'How to validate/review completed tasks. Review PRs in FIFO order (lowest PR number first).',
+			steps: [
+				'claim_validation(task_id) — returns worktree setup commands and PR info',
+				`Set up worktree from existing branch: git fetch origin feature/xxx && git worktree add ../PROJECT-PERSONA-validation feature/xxx`,
+				'Review code, run tests if applicable',
+				'Verify PR checks: gh pr view <PR> --json statusCheckRollup,mergeable',
+				'Approve: validate_task(task_id, approved: true, pr_checks_passing: true, validation_notes: "...")',
+				data.project?.auto_merge_on_approval !== false
+					? 'Merge immediately: gh pr merge <PR> --squash'
+					: 'Do NOT merge — wait for project owner to merge.',
+				'Reject: validate_task(task_id, approved: false, validation_notes: "...", create_fix_task: true)',
+				'Clean up worktree after validation',
+			],
+			handle_failures: {
+				tests_fail: 'Use create_fix_task: true in validate_task() to create a follow-up task',
+				merge_conflicts: 'Create a task: add_task(project_id, title: "Resolve merge conflicts in PR #XXX")',
+				minor_issues: 'Fix directly in the branch, push, and re-validate',
+				closed_pr: 'cancel_task(task_id, cancelled_reason: "pr_closed")',
+			},
+			rule: 'Every PR review MUST end with a clear action. Never leave PRs unmerged or unresolved.',
+		};
+
+		// Post-merge branch sync (git-flow only)
+		if (projectWorkflow === 'git-flow' && data.project) {
+			const devBranch = data.project.git_develop_branch || 'develop';
+			workflow.post_merge_sync = {
+				description: `After merging to main, sync main back to ${devBranch} to prevent divergence.`,
+				commands: [
+					`git checkout ${devBranch} && git pull origin ${devBranch}`,
+					'git merge origin/main',
+					`git push origin ${devBranch}`,
+				],
+			};
+		}
+	}
+
+	// Deployment resolution workflow
+	workflow.deployment_resolution = {
+		description: 'When a fix already exists but just needs deployment',
+		steps: [
+			'add_finding(project_id, title: "Fix exists - needs deployment", category: "other", severity: "info")',
+			'complete_task(task_id, summary: "Fix exists in [branch/commit], pending deployment", session_id)',
+			'check_deployment_status(project_id) then request_deployment(project_id) if needed',
+		],
+		rule: 'Don\'t block tasks waiting for deployment — investigation is complete when you identify the resolution.',
+	};
+
+	result.WORKFLOW = workflow;
+
 	// Add next action at end - pending requests take priority over validation, then regular tasks
 	if (hasUrgentQuestions) {
 		const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
@@ -312,9 +436,11 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		// Validation tasks take priority over new work - use next_action from API if available
 		result.next_action = data.next_action || `claim_validation(task_id: "${data.awaiting_validation[0].id}")`;
 	} else if (data.next_task) {
-		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress")`;
+		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress", session_id: "${result.session_id}")`;
 	} else if (data.project) {
-		result.next_action = `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`;
+		result.next_action = data.project.fallback_activities_enabled !== false
+			? `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`
+			: 'signal_idle() — no tasks available and fallback activities are disabled.';
 	}
 
 	return { result };

package/src/handlers/tasks.ts

@@ -77,11 +77,13 @@ const updateTaskSchema = {
 	worktree_path: { type: 'string' as const },
 	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
 	skip_worktree_requirement: { type: 'boolean' as const, default: false },
+	session_id: { type: 'string' as const },
 };
 
 const completeTaskSchema = {
 	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 	summary: { type: 'string' as const },
+	session_id: { type: 'string' as const },
 };
 
 const deleteTaskSchema = {
@@ -367,7 +369,7 @@ export const addTask: Handler = async (args, ctx) => {
 };
 
 export const updateTask: Handler = async (args, ctx) => {
-	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement, session_id: explicit_session_id } = parseArgs(args, updateTaskSchema);
 	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
 
 	// Enforce worktree creation: require git_branch when marking task as in_progress
@@ -391,7 +393,7 @@ export const updateTask: Handler = async (args, ctx) => {
 	const response = await api.updateTask(task_id, {
 		...updates,
 		progress_note,
-		session_id: ctx.session.currentSessionId || undefined,
+		session_id: explicit_session_id || ctx.session.currentSessionId || undefined,
 	});
 
 	if (!response.ok) {
@@ -514,7 +516,7 @@ export const updateTask: Handler = async (args, ctx) => {
 			message: 'If investigation reveals the fix already exists but needs deployment:',
 			steps: [
 				'1. Add finding: add_finding(project_id, title: "Fix exists, awaits deployment", category: "other", severity: "info", description: "...", related_task_id: task_id)',
-				'2. Complete task: complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment.")',
+				'2. Complete task: complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment.")',
 				'3. Check deployment: check_deployment_status(project_id)',
 				'4. Request deployment if not pending: request_deployment(project_id, notes: "Includes fix for [issue]")',
 			],
@@ -526,12 +528,12 @@ export const updateTask: Handler = async (args, ctx) => {
 };
 
 export const completeTask: Handler = async (args, ctx) => {
-	const { task_id, summary } = parseArgs(args, completeTaskSchema);
+	const { task_id, summary, session_id: explicit_session_id } = parseArgs(args, completeTaskSchema);
 
 	const api = getApiClient();
 	const response = await api.completeTask(task_id, {
 		summary,
-		session_id: ctx.session.currentSessionId || undefined,
+		session_id: explicit_session_id || ctx.session.currentSessionId || undefined,
 	});
 
 	if (!response.ok) {