@vibescope/mcp-server 0.3.14 → 0.4.1

package/dist/api-client.d.ts

@@ -60,6 +60,10 @@ export declare class VibescopeApiClient {
             git_main_branch?: string;
             git_develop_branch?: string;
             git_auto_branch?: boolean;
+            validation_required?: boolean;
+            auto_merge_on_approval?: boolean;
+            fallback_activities_enabled?: boolean;
+            require_pr_for_validation?: boolean;
         };
         active_tasks?: Array<{
             id: string;

package/dist/handlers/session.js

@@ -277,23 +277,99 @@ export const startWorkSession = async (args, ctx) => {
             result.directive = `SETUP REQUIRED: This is your first time connecting as a ${data.agent_setup.agent_type} agent. Follow the agent_setup instructions before starting work.`;
         }
     }
-    // Build top-level AGENT_RULES - critical rules agents must follow
+    // Build dynamic AGENT_RULES from project settings
     const agentRules = [];
     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(`FOLLOW GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
-    }
-    agentRules.push('COMPLETE TASKS: Always call complete_task() after creating a PR. This is mandatory.');
-    agentRules.push('REVIEW REQUIRED: All tasks must be reviewed by another agent before merging.');
-    agentRules.push('STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE") whenever you start a new task, and update_task(task_id, status: "in_progress") to claim it.');
+        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") 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 = {};
+    // 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];
@@ -306,10 +382,12 @@ export const startWorkSession = async (args, ctx) => {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.3.14",
+  "version": "0.4.1",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",

package/src/api-client.ts

@@ -203,6 +203,10 @@ export class VibescopeApiClient {
 			git_main_branch?: string;
 			git_develop_branch?: string;
 			git_auto_branch?: boolean;
+			validation_required?: boolean;
+			auto_merge_on_approval?: boolean;
+			fallback_activities_enabled?: boolean;
+			require_pr_for_validation?: boolean;
 		};
 		active_tasks?: Array<{
 			id: string;

package/src/handlers/session.ts

@@ -321,7 +321,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		}
 	}
 
-	// Build top-level AGENT_RULES - critical rules agents must follow
+	// Build dynamic AGENT_RULES from project settings
 	const agentRules: string[] = [];
 	const projectWorkflow = data.project?.git_workflow;
 	const isBranching = projectWorkflow === 'git-flow' || projectWorkflow === 'github-flow';
@@ -329,18 +329,103 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		? (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(`FOLLOW GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
+		agentRules.push(`GIT WORKFLOW: This project uses ${projectWorkflow}. Branch from ${ruleBaseBranch}. Do NOT commit directly to main or develop.`);
 	}
-	agentRules.push('COMPLETE TASKS: Always call complete_task() after creating a PR. This is mandatory.');
-	agentRules.push('REVIEW REQUIRED: All tasks must be reviewed by another agent before merging.');
-	agentRules.push('STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE") whenever you start a new task, and update_task(task_id, status: "in_progress") to claim it.');
+
+	// 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") 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];
@@ -351,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 };