@vibescope/mcp-server 0.4.3 → 0.4.4

package/dist/handlers/session.js

@@ -9,11 +9,102 @@
  * - get_token_usage
  */
 import os from 'os';
+import crypto from 'crypto';
 import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
 import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
 import { normalizeGitUrl } from '../utils.js';
+/**
+ * Simple hash for content change detection.
+ */
+function simpleHash(content) {
+    return crypto.createHash('md5').update(content).digest('hex').slice(0, 12);
+}
+/**
+ * Build the full CLAUDE.md content from dynamic rules + project instructions.
+ * This is what gets persisted to .claude/CLAUDE.md by the agent.
+ */
+function buildPersistContent(agentRules, workflow, project, agentInstructions) {
+    const lines = [];
+    lines.push('<!-- hash:{{HASH}} -->');
+    lines.push('<!-- AUTO-GENERATED by Vibescope MCP. Do not edit manually — changes will be overwritten on next start_work_session. -->');
+    lines.push('');
+    lines.push('# Vibescope Agent Guidelines');
+    lines.push('');
+    // Quick start
+    lines.push('## Quick Start');
+    lines.push('');
+    lines.push('```');
+    lines.push('start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude", agent_name: "YOUR_NAME")');
+    lines.push('```');
+    lines.push('');
+    // Mandatory rules
+    lines.push('## MANDATORY Workflow Rules (NON-NEGOTIABLE)');
+    lines.push('');
+    for (const rule of agentRules) {
+        lines.push(`- ${rule}`);
+    }
+    lines.push('');
+    // Session ID reminder
+    lines.push('### Session ID');
+    lines.push('');
+    lines.push('Save the `session_id` from `start_work_session` and pass it on EVERY `update_task`, `complete_task`, and `get_next_task` call. Without it, task claiming fails and your name won\'t show on completed tasks.');
+    lines.push('');
+    // Workflow
+    const workflowContinuous = workflow.continuous_work;
+    if (workflowContinuous) {
+        lines.push('## Continuous Work Loop');
+        lines.push('');
+        if (workflowContinuous.steps) {
+            for (const step of workflowContinuous.steps) {
+                lines.push(`1. ${step}`);
+            }
+        }
+        if (workflowContinuous.rule) {
+            lines.push('');
+            lines.push(`**${workflowContinuous.rule}**`);
+        }
+        lines.push('');
+    }
+    const workflowValidation = workflow.validation;
+    if (workflowValidation?.steps) {
+        lines.push('## Validation Workflow');
+        lines.push('');
+        for (const step of workflowValidation.steps) {
+            lines.push(`1. ${step}`);
+        }
+        lines.push('');
+    }
+    // Context management
+    lines.push('## Context Management');
+    lines.push('');
+    lines.push('When context grows large or responses slow:');
+    lines.push('1. Run `/clear`');
+    lines.push('2. Call `start_work_session(...)` again immediately');
+    lines.push('3. Continue with `next_task` — do NOT ask permission');
+    lines.push('');
+    // MCP connection
+    lines.push('## MCP Connection Required');
+    lines.push('');
+    lines.push('**If MCP connection fails, end session immediately.** Never work without task tracking.');
+    lines.push('');
+    // Project-specific instructions from template
+    if (agentInstructions.trim()) {
+        lines.push('## Project-Specific Instructions');
+        lines.push('');
+        lines.push(agentInstructions.trim());
+        lines.push('');
+    }
+    // Help topics
+    lines.push('## Help Topics');
+    lines.push('');
+    lines.push('`get_help(topic)` for: `getting_started`, `tasks`, `validation`, `deployment`, `git`, `blockers`, `milestones`, `fallback`, `session`, `topics`');
+    const content = lines.join('\n');
+    // Replace hash placeholder with actual hash
+    const hash = simpleHash(content.replace('<!-- hash:{{HASH}} -->', ''));
+    return content.replace('{{HASH}}', hash);
+}
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 const VALID_MODES = ['lite', 'full'];
@@ -370,6 +461,21 @@ export const startWorkSession = async (args, ctx) => {
         rule: 'Don\'t block tasks waiting for deployment — investigation is complete when you identify the resolution.',
     };
     result.WORKFLOW = workflow;
+    // Build PERSIST_INSTRUCTIONS — tells the agent to write rules to .claude/CLAUDE.md
+    // This ensures instructions survive context clears and persist across the whole session.
+    // Content comes from: admin templates + project settings (fully customizable from dashboard).
+    const agentInstructions = data.project?.agent_instructions || '';
+    const persistContent = buildPersistContent(agentRules, workflow, data.project, agentInstructions);
+    // Extract hash from the generated content (it's embedded in the first line)
+    const hashMatch = persistContent.match(/<!-- hash:(\w+) -->/);
+    const contentHash = hashMatch?.[1] || simpleHash(persistContent);
+    result.PERSIST_INSTRUCTIONS = {
+        action: 'Write the content below to .claude/CLAUDE.md (overwrite existing). This ensures your instructions persist across context clears.',
+        path: '.claude/CLAUDE.md',
+        content: persistContent,
+        hash: contentHash,
+        skip_if_hash_matches: `Only write if the file doesn't exist or its content has changed. Check for "<!-- hash:${contentHash} -->" at the top.`,
+    };
     // 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];

package/package.json

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

package/src/handlers/session.ts

@@ -10,6 +10,7 @@
  */
 
 import os from 'os';
+import crypto from 'crypto';
 import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
 import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
@@ -17,6 +18,114 @@ import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templa
 import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
 import { normalizeGitUrl } from '../utils.js';
 
+/**
+ * Simple hash for content change detection.
+ */
+function simpleHash(content: string): string {
+	return crypto.createHash('md5').update(content).digest('hex').slice(0, 12);
+}
+
+/**
+ * Build the full CLAUDE.md content from dynamic rules + project instructions.
+ * This is what gets persisted to .claude/CLAUDE.md by the agent.
+ */
+function buildPersistContent(
+	agentRules: string[],
+	workflow: Record<string, unknown>,
+	project: Record<string, unknown> | undefined,
+	agentInstructions: string
+): string {
+	const lines: string[] = [];
+
+	lines.push('<!-- hash:{{HASH}} -->');
+	lines.push('<!-- AUTO-GENERATED by Vibescope MCP. Do not edit manually — changes will be overwritten on next start_work_session. -->');
+	lines.push('');
+	lines.push('# Vibescope Agent Guidelines');
+	lines.push('');
+
+	// Quick start
+	lines.push('## Quick Start');
+	lines.push('');
+	lines.push('```');
+	lines.push('start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus", agent_type: "claude", agent_name: "YOUR_NAME")');
+	lines.push('```');
+	lines.push('');
+
+	// Mandatory rules
+	lines.push('## MANDATORY Workflow Rules (NON-NEGOTIABLE)');
+	lines.push('');
+	for (const rule of agentRules) {
+		lines.push(`- ${rule}`);
+	}
+	lines.push('');
+
+	// Session ID reminder
+	lines.push('### Session ID');
+	lines.push('');
+	lines.push('Save the `session_id` from `start_work_session` and pass it on EVERY `update_task`, `complete_task`, and `get_next_task` call. Without it, task claiming fails and your name won\'t show on completed tasks.');
+	lines.push('');
+
+	// Workflow
+	const workflowContinuous = workflow.continuous_work as { steps?: string[]; rule?: string } | undefined;
+	if (workflowContinuous) {
+		lines.push('## Continuous Work Loop');
+		lines.push('');
+		if (workflowContinuous.steps) {
+			for (const step of workflowContinuous.steps) {
+				lines.push(`1. ${step}`);
+			}
+		}
+		if (workflowContinuous.rule) {
+			lines.push('');
+			lines.push(`**${workflowContinuous.rule}**`);
+		}
+		lines.push('');
+	}
+
+	const workflowValidation = workflow.validation as { steps?: string[] } | undefined;
+	if (workflowValidation?.steps) {
+		lines.push('## Validation Workflow');
+		lines.push('');
+		for (const step of workflowValidation.steps) {
+			lines.push(`1. ${step}`);
+		}
+		lines.push('');
+	}
+
+	// Context management
+	lines.push('## Context Management');
+	lines.push('');
+	lines.push('When context grows large or responses slow:');
+	lines.push('1. Run `/clear`');
+	lines.push('2. Call `start_work_session(...)` again immediately');
+	lines.push('3. Continue with `next_task` — do NOT ask permission');
+	lines.push('');
+
+	// MCP connection
+	lines.push('## MCP Connection Required');
+	lines.push('');
+	lines.push('**If MCP connection fails, end session immediately.** Never work without task tracking.');
+	lines.push('');
+
+	// Project-specific instructions from template
+	if (agentInstructions.trim()) {
+		lines.push('## Project-Specific Instructions');
+		lines.push('');
+		lines.push(agentInstructions.trim());
+		lines.push('');
+	}
+
+	// Help topics
+	lines.push('## Help Topics');
+	lines.push('');
+	lines.push('`get_help(topic)` for: `getting_started`, `tasks`, `validation`, `deployment`, `git`, `blockers`, `milestones`, `fallback`, `session`, `topics`');
+
+	const content = lines.join('\n');
+	// Replace hash placeholder with actual hash
+	const hash = simpleHash(content.replace('<!-- hash:{{HASH}} -->', ''));
+	return content.replace('{{HASH}}', hash);
+}
+
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 
@@ -426,6 +535,23 @@ export const startWorkSession: Handler = async (args, ctx) => {
 
 	result.WORKFLOW = workflow;
 
+	// Build PERSIST_INSTRUCTIONS — tells the agent to write rules to .claude/CLAUDE.md
+	// This ensures instructions survive context clears and persist across the whole session.
+	// Content comes from: admin templates + project settings (fully customizable from dashboard).
+	const agentInstructions = data.project?.agent_instructions || '';
+	const persistContent = buildPersistContent(agentRules, workflow, data.project as Record<string, unknown> | undefined, agentInstructions);
+	// Extract hash from the generated content (it's embedded in the first line)
+	const hashMatch = persistContent.match(/<!-- hash:(\w+) -->/);
+	const contentHash = hashMatch?.[1] || simpleHash(persistContent);
+
+	result.PERSIST_INSTRUCTIONS = {
+		action: 'Write the content below to .claude/CLAUDE.md (overwrite existing). This ensures your instructions persist across context clears.',
+		path: '.claude/CLAUDE.md',
+		content: persistContent,
+		hash: contentHash,
+		skip_if_hash_matches: `Only write if the file doesn't exist or its content has changed. Check for "<!-- hash:${contentHash} -->" at the top.`,
+	};
+
 	// 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];