@vibescope/mcp-server 0.2.2 → 0.2.4

package/dist/handlers/tasks.js

@@ -2,7 +2,11 @@
  * Task Handlers (Migrated to API Client)
  *
  * Handles task CRUD and management:
- * - get_tasks
+ * - get_task (single task by ID)
+ * - search_tasks (text search)
+ * - get_tasks_by_priority (priority filter)
+ * - get_recent_tasks (by date)
+ * - get_task_stats (aggregate counts)
  * - get_next_task
  * - add_task
  * - update_task
@@ -15,8 +19,11 @@
  * - add_subtask
  * - get_subtasks
  */
+import os from 'os';
 import { parseArgs, uuidValidator, taskStatusValidator, priorityValidator, progressValidator, minutesValidator, createEnumValidator, ValidationError, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
 // Valid task types
 const VALID_TASK_TYPES = [
     'frontend', 'backend', 'database', 'feature', 'bugfix',
@@ -25,15 +32,6 @@ const VALID_TASK_TYPES = [
 // ============================================================================
 // Argument Schemas
 // ============================================================================
-const getTasksSchema = {
-    project_id: { type: 'string', required: true, validate: uuidValidator },
-    status: { type: 'string', validate: taskStatusValidator },
-    limit: { type: 'number', default: 50 },
-    offset: { type: 'number', default: 0 },
-    search_query: { type: 'string' },
-    include_subtasks: { type: 'boolean', default: false },
-    include_metadata: { type: 'boolean', default: false },
-};
 const getNextTaskSchema = {
     project_id: { type: 'string', required: true, validate: uuidValidator },
 };
@@ -92,6 +90,41 @@ const addSubtaskSchema = {
 const getSubtasksSchema = {
     parent_task_id: { type: 'string', required: true, validate: uuidValidator },
     status: { type: 'string', validate: taskStatusValidator },
+    limit: { type: 'number', default: 20 },
+    offset: { type: 'number', default: 0 },
+};
+// ============================================================================
+// New Targeted Task Query Schemas
+// ============================================================================
+const getTaskSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+    include_subtasks: { type: 'boolean', default: false },
+    include_milestones: { type: 'boolean', default: false },
+};
+const searchTasksSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    query: { type: 'string', required: true },
+    status: { type: 'array' },
+    limit: { type: 'number', default: 10 },
+    offset: { type: 'number', default: 0 },
+};
+const getTasksByPrioritySchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    priority: { type: 'number', validate: priorityValidator },
+    priority_max: { type: 'number', validate: priorityValidator },
+    status: { type: 'string', validate: taskStatusValidator },
+    limit: { type: 'number', default: 10 },
+    offset: { type: 'number', default: 0 },
+};
+const getRecentTasksSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    order: { type: 'string', validate: createEnumValidator(['newest', 'oldest']) },
+    status: { type: 'string', validate: taskStatusValidator },
+    limit: { type: 'number', default: 10 },
+    offset: { type: 'number', default: 0 },
+};
+const getTaskStatsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
 };
 function getTaskCompleteGitInstructions(gitWorkflow, gitMainBranch, gitDevelopBranch, taskBranch, taskTitle, taskId) {
     if (gitWorkflow === 'none') {
@@ -143,28 +176,6 @@ export function getValidationApprovedGitInstructions(config, taskBranch) {
 // ============================================================================
 // Task Handlers - Using API Client
 // ============================================================================
-export const getTasks = async (args, ctx) => {
-    const { project_id, status, limit, offset, search_query, include_subtasks, include_metadata } = parseArgs(args, getTasksSchema);
-    const api = getApiClient();
-    const response = await api.getTasks(project_id, {
-        status,
-        limit: Math.min(limit ?? 50, 200),
-        offset,
-        include_subtasks,
-        search_query,
-        include_metadata,
-    });
-    if (!response.ok) {
-        return { result: { error: response.error || 'Failed to fetch tasks' }, isError: true };
-    }
-    return {
-        result: {
-            tasks: response.data?.tasks || [],
-            total_count: response.data?.total_count || 0,
-            has_more: response.data?.has_more || false,
-        },
-    };
-};
 export const getNextTask = async (args, ctx) => {
     const { project_id } = parseArgs(args, getNextTaskSchema);
     const api = getApiClient();
@@ -310,6 +321,16 @@ export const updateTask = async (args, ctx) => {
     if (data?.next_step) {
         result.next_step = data.next_step;
     }
+    // Add test reminder when starting work on a task
+    if (status === 'in_progress') {
+        result.test_reminder = {
+            message: 'Remember to write tests for this task before marking it complete.',
+            minimum_expectation: 'Basic tests that validate the task requirements are met',
+            ideal: 'Tests that also cover edge cases and error handling',
+            test_patterns: ['*.test.ts', '*.spec.ts', '*.test.js', '*.spec.js', '__tests__/*'],
+            note: 'Validators will check for test file changes during review. Documentation-only or config changes may not require tests.',
+        };
+    }
     return { result };
 };
 export const completeTask = async (args, ctx) => {
@@ -496,18 +517,178 @@ export const getSubtasks = async (args, ctx) => {
     };
 };
 // ============================================================================
+// New Targeted Task Query Handlers
+// ============================================================================
+/**
+ * Get a single task by ID with optional subtasks and milestones
+ */
+export const getTask = async (args, ctx) => {
+    const { task_id, include_subtasks, include_milestones } = parseArgs(args, getTaskSchema);
+    const api = getApiClient();
+    const response = await api.getTaskById(task_id, {
+        include_subtasks,
+        include_milestones,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to fetch task' }, isError: true };
+    }
+    const result = {
+        task: response.data?.task,
+    };
+    if (include_subtasks && response.data?.subtasks) {
+        result.subtasks = response.data.subtasks;
+    }
+    if (include_milestones && response.data?.milestones) {
+        result.milestones = response.data.milestones;
+    }
+    return { result };
+};
+/**
+ * Search tasks by text query with pagination
+ */
+export const searchTasks = async (args, ctx) => {
+    const { project_id, query, status, limit, offset } = parseArgs(args, searchTasksSchema);
+    // Validate query length
+    if (query.length < 2) {
+        return {
+            result: {
+                error: 'query_too_short',
+                message: 'Search query must be at least 2 characters',
+            },
+        };
+    }
+    // Cap limit at 20, safe offset
+    const cappedLimit = Math.min(limit ?? 10, 20);
+    const safeOffset = Math.max(0, offset ?? 0);
+    const api = getApiClient();
+    const response = await api.searchTasks(project_id, {
+        query,
+        status: status,
+        limit: cappedLimit,
+        offset: safeOffset,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to search tasks' }, isError: true };
+    }
+    const tasks = response.data?.tasks || [];
+    const totalMatches = response.data?.total_matches || 0;
+    return {
+        result: {
+            tasks,
+            total_matches: totalMatches,
+            has_more: safeOffset + tasks.length < totalMatches,
+            offset: safeOffset,
+            limit: cappedLimit,
+        },
+    };
+};
+/**
+ * Get tasks filtered by priority with pagination
+ */
+export const getTasksByPriority = async (args, ctx) => {
+    const { project_id, priority, priority_max, status, limit, offset } = parseArgs(args, getTasksByPrioritySchema);
+    // Cap limit at 20, safe offset
+    const cappedLimit = Math.min(limit ?? 10, 20);
+    const safeOffset = Math.max(0, offset ?? 0);
+    const api = getApiClient();
+    const response = await api.getTasksByPriority(project_id, {
+        priority,
+        priority_max,
+        status,
+        limit: cappedLimit,
+        offset: safeOffset,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to fetch tasks by priority' }, isError: true };
+    }
+    const tasks = response.data?.tasks || [];
+    const totalCount = response.data?.total_count || 0;
+    return {
+        result: {
+            tasks,
+            total_count: totalCount,
+            has_more: safeOffset + tasks.length < totalCount,
+            offset: safeOffset,
+            limit: cappedLimit,
+        },
+    };
+};
+/**
+ * Get recent tasks (newest or oldest) with pagination
+ */
+export const getRecentTasks = async (args, ctx) => {
+    const { project_id, order, status, limit, offset } = parseArgs(args, getRecentTasksSchema);
+    // Cap limit at 20, safe offset
+    const cappedLimit = Math.min(limit ?? 10, 20);
+    const safeOffset = Math.max(0, offset ?? 0);
+    const api = getApiClient();
+    const response = await api.getRecentTasks(project_id, {
+        order: order,
+        status,
+        limit: cappedLimit,
+        offset: safeOffset,
+    });
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to fetch recent tasks' }, isError: true };
+    }
+    const tasks = response.data?.tasks || [];
+    const totalCount = response.data?.total_count || 0;
+    return {
+        result: {
+            tasks,
+            total_count: totalCount,
+            has_more: safeOffset + tasks.length < totalCount,
+            offset: safeOffset,
+            limit: cappedLimit,
+        },
+    };
+};
+/**
+ * Get task statistics for a project (aggregate counts only, minimal tokens)
+ */
+export const getTaskStats = async (args, ctx) => {
+    const { project_id } = parseArgs(args, getTaskStatsSchema);
+    const api = getApiClient();
+    const response = await api.getTaskStats(project_id);
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to fetch task stats' }, isError: true };
+    }
+    return {
+        result: {
+            total: response.data?.total || 0,
+            by_status: response.data?.by_status || {
+                backlog: 0,
+                pending: 0,
+                in_progress: 0,
+                completed: 0,
+                cancelled: 0,
+            },
+            by_priority: response.data?.by_priority || { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 },
+            awaiting_validation: response.data?.awaiting_validation || 0,
+            oldest_pending_days: response.data?.oldest_pending_days ?? null,
+        },
+    };
+};
+// ============================================================================
 // Worktree Cleanup Handlers
 // ============================================================================
 const getStaleWorktreesSchema = {
     project_id: { type: 'string', required: true, validate: uuidValidator },
+    hostname: { type: 'string' }, // Machine hostname to filter worktrees
+    limit: { type: 'number', default: 20 },
+    offset: { type: 'number', default: 0 },
 };
 const clearWorktreePathSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
 };
 export const getStaleWorktrees = async (args, ctx) => {
-    const { project_id } = parseArgs(args, getStaleWorktreesSchema);
+    const { project_id, hostname: providedHostname, limit, offset } = parseArgs(args, getStaleWorktreesSchema);
+    // Use auto-detected hostname if not provided - filters to only worktrees on THIS machine
+    const hostname = providedHostname || MACHINE_HOSTNAME;
+    // Cap limit to prevent context bloating
+    const cappedLimit = Math.min(limit ?? 20, 50);
     const api = getApiClient();
-    const response = await api.getStaleWorktrees(project_id);
+    const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
     if (!response.ok) {
         return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
     }
@@ -516,9 +697,15 @@ export const getStaleWorktrees = async (args, ctx) => {
         result: {
             project_id: data?.project_id,
             project_name: data?.project_name,
+            hostname_filter: data?.hostname_filter,
             stale_worktrees: data?.stale_worktrees || [],
             count: data?.count || 0,
+            local_count: data?.local_count || 0,
+            remote_count: data?.remote_count || 0,
+            total_count: data?.total_count || 0,
+            has_more: data?.has_more || false,
             cleanup_instructions: data?.cleanup_instructions,
+            remote_worktree_note: data?.remote_worktree_note,
         },
     };
 };
@@ -541,7 +728,13 @@ export const clearWorktreePath = async (args, ctx) => {
  * Task handlers registry
  */
 export const taskHandlers = {
-    get_tasks: getTasks,
+    // Targeted task query endpoints (token-efficient)
+    get_task: getTask,
+    search_tasks: searchTasks,
+    get_tasks_by_priority: getTasksByPriority,
+    get_recent_tasks: getRecentTasks,
+    get_task_stats: getTaskStats,
+    // Core task operations
     get_next_task: getNextTask,
     add_task: addTask,
     update_task: updateTask,

package/dist/handlers/tool-docs.js

@@ -81,13 +81,69 @@ Sync README content to the dashboard.
 **Parameters:**
 - project_id (required): Project UUID
 - readme_content (required): Markdown content`,
-    get_tasks: `# get_tasks
-Get tasks for a project.
+    get_task: `# get_task
+Get a single task by ID with optional subtasks and milestones.
+
+**Parameters:**
+- task_id (required): Task UUID
+- include_subtasks (optional): Include subtasks array (default: false)
+- include_milestones (optional): Include milestones array (default: false)`,
+    search_tasks: `# search_tasks
+Search tasks by text query. Supports pagination.
+
+**Parameters:**
+- project_id (required): Project UUID
+- query (required): Search query (min 2 chars)
+- status (optional): Array of statuses to filter
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_matches: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+    get_tasks_by_priority: `# get_tasks_by_priority
+Get tasks filtered by priority. Supports pagination.
+
+**Parameters:**
+- project_id (required): Project UUID
+- priority (optional): Exact priority (1-5)
+- priority_max (optional): Max priority for range query
+- status (optional): Filter by status (default: pending)
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_count: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+    get_recent_tasks: `# get_recent_tasks
+Get tasks ordered by creation date. Supports pagination.
 
 **Parameters:**
 - project_id (required): Project UUID
-- status (optional): pending, in_progress, completed, cancelled
-- limit (optional): Max tasks (default 50)`,
+- order (optional): 'newest' or 'oldest' (default: newest)
+- status (optional): Filter by status
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_count: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+    get_task_stats: `# get_task_stats
+Get aggregate task statistics. Most token-efficient way to understand project state.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Counts by status and priority, no task data`,
     get_next_task: `# get_next_task
 Get highest priority pending task not claimed by another agent.
 
@@ -128,6 +184,17 @@ Delete a task.
 
 **Parameters:**
 - task_id (required): Task UUID`,
+    cancel_task: `# cancel_task
+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.
+
+**Parameters:**
+- task_id (required): Task UUID
+- cancelled_reason (optional): One of: pr_closed, superseded, user_cancelled, validation_failed, obsolete, blocked
+- cancellation_note (optional): Additional context about the cancellation
+
+**Returns:** task_id, cancelled_reason, message, sprint info (if auto-completed)
+
+**Example:** cancel_task(task_id: "abc", cancelled_reason: "pr_closed", cancellation_note: "PR was closed without merging")`,
     batch_update_tasks: `# batch_update_tasks
 Update multiple tasks at once.
 
@@ -898,7 +965,7 @@ Query aggregated project knowledge in a single call. Reduces token usage by comb
 - stats: counts for each category, findings by severity
 - Category data based on selection
 
-**Token savings:** Replaces up to 6 separate tool calls (get_findings, get_decisions, get_tasks, get_blockers, etc.) with one call.
+**Token savings:** Replaces multiple tool calls (get_findings, get_decisions, get_blockers, etc.) with one call.
 
 **Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
 };

package/dist/templates/agent-guidelines.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agent Guidelines Template
+ *
+ * This template contains the essential CLAUDE.md content that should be included
+ * in every project using Vibescope for agent tracking. These guidelines ensure
+ * agents follow proper workflows and maintain visibility.
+ */
+export declare const AGENT_GUIDELINES_TEMPLATE = "# Vibescope Agent Guidelines\n\n## Quick Start\n\n```\nstart_work_session(git_url: \"https://github.com/YOUR/REPO\", model: \"opus\")\n```\n\n**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for \"You are powered by the model named...\" to determine your model.\n\nThis returns your persona, project info, and `next_task`. Start working immediately.\n\n## CRITICAL: MCP Connection Required\n\n**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**\n\n### Why This Is Non-Negotiable\n\nWorking without MCP connection causes:\n- **No progress visibility** - Humans can't see what you're doing\n- **Lost work tracking** - Tasks aren't tracked, time is wasted\n- **Workflow violations** - Other agents may conflict with your work\n- **Dashboard confusion** - Project state becomes inconsistent\n\n### Connection Failure Handling\n\n**If `start_work_session` fails or returns an error:**\n\n1. **Do NOT proceed with any work**\n2. **Inform the user** that MCP connection failed\n3. **End the session** - do not attempt workarounds\n4. **Provide troubleshooting steps:**\n   - Check if MCP server is configured: `claude mcp list`\n   - Verify API key is set: check `.mcp.json` or environment\n   - Restart Claude Code after fixing configuration\n\n**Example error responses you might see:**\n```\nError: Failed to start session\nError: VIBESCOPE_API_KEY not set\nError: Network error connecting to Vibescope API\nError: MCP server 'vibescope' not found\n```\n\n### Recovery Steps\n\nIf MCP connection fails, tell the user:\n\n```\nMCP connection to Vibescope failed. I cannot proceed without task tracking.\n\nTo fix:\n1. Run: claude mcp list (verify vibescope is configured)\n2. Check API key: ensure VIBESCOPE_API_KEY is set\n3. Restart Claude Code\n4. Try again with: start_work_session(git_url: \"...\")\n\nI am ending this session to prevent untracked work.\n```\n\n**Never \"work around\" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.\n\n## Core Workflow\n\n1. **Start session** \u2192 `start_work_session(git_url, model)` - Always include your model!\n2. **Mark task in progress** \u2192 `update_task(task_id, status: \"in_progress\")` - Returns git workflow instructions!\n3. **Set up worktree** \u2192 Create isolated worktree for this task (see Git Workflow below)\n4. **Update progress** \u2192 `update_task(task_id, progress_percentage: 50, progress_note: \"...\")`\n5. **Complete task** \u2192 `complete_task(task_id, summary: \"...\")` - **MANDATORY, see below!**\n6. **Clean up** \u2192 Remove worktree, then start next task immediately\n\n## CRITICAL: Always Call complete_task (MANDATORY)\n\n**You MUST call `complete_task()` when you finish a task.** This is not optional.\n\n### When to Call complete_task\n\nCall `complete_task()` immediately after:\n- \u2705 Creating and pushing a PR\n- \u2705 Merging changes (for trunk-based workflow)\n- \u2705 Finishing any unit of work, even if no code changes\n\n**Do NOT wait for:**\n- \u274C PR to be reviewed/merged (that's what validation is for)\n- \u274C User confirmation\n- \u274C \"Perfect\" summary - a brief summary is fine\n\n### The Rule\n\n```\nPR created + pushed \u2192 complete_task() \u2192 THEN worry about next steps\n```\n\n**If you create a PR and don't call `complete_task()`, you have failed the workflow.**\n\n## CRITICAL: Git Worktrees for Multi-Agent\n\nWhen multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.\n\n**Before starting ANY task:**\n```bash\n# For git-flow: ensure you're on develop first, then create worktree\ngit checkout develop\ngit pull origin develop\ngit worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>\ncd ../worktree-<task-short-id>\n```\n\n**After task is merged:**\n```bash\ngit worktree remove ../worktree-<task-short-id>\n```\n\n**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.\n\nRun `get_help(\"git\")` for full worktree documentation.\n\n## CRITICAL: Never Ask Permission\n\n**You must NEVER:**\n- Ask \"Should I continue to the next task?\" \u2192 Just continue\n- Ask \"Should I clear my context?\" \u2192 Just clear it\n- Ask \"What should I do next?\" \u2192 Check `next_task` or use fallback activities\n- Say \"All tasks are done, let me know what to do\" \u2192 Use `get_next_task` or start fallback activity\n- Wait for confirmation before clearing context \u2192 Just do it\n\n**You must ALWAYS:**\n- Call `complete_task()` immediately after creating/pushing a PR - this is non-negotiable\n- Immediately start the next task after completing one\n- Clear context and restart session automatically when needed\n- Keep working until there are genuinely no tasks and no fallback activities\n\n## Continuous Work\n\n**IMPORTANT: Never stop working!** When you complete a task:\n1. `complete_task` returns `next_task` \u2192 Start it immediately\n2. No `next_task`? \u2192 Call `get_next_task(project_id)`\n3. Still no tasks? \u2192 Start a `fallback_activity` (code_review, security_review, etc.)\n\n**When context grows large or responses slow down:**\n1. Run `/clear` to reset conversation\n2. Immediately call `start_work_session(git_url, model)` to reload context\n3. Continue with `next_task` from the response\n\n**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.\n\n## Need Help?\n\nUse `get_help(topic)` for detailed guidance:\n\n| Topic | Description |\n|-------|-------------|\n| `getting_started` | Basic workflow overview |\n| `tasks` | Working on tasks, progress tracking |\n| `validation` | Cross-agent task validation |\n| `deployment` | Deployment coordination |\n| `git` | Git workflow configuration |\n| `blockers` | Handling blockers |\n| `milestones` | Breaking down complex tasks |\n| `fallback` | Background activities when idle |\n| `session` | Session management |\n| `topics` | List all available topics |\n\n## MCP Server Not Connected?\n\n### Quick Setup (Claude Code)\n\n```bash\nclaude mcp add vibescope npx @vibescope/mcp-server@latest \\\n  --env VIBESCOPE_API_KEY=your_key\n```\n\n### Manual Setup\n\n1. Copy `.mcp.json.example` to `.mcp.json`\n2. Get `VIBESCOPE_API_KEY` from https://vibescope.dev/dashboard/settings\n3. Restart Claude Code\n";
+/**
+ * Get the agent guidelines template
+ * @returns The full agent guidelines markdown template
+ */
+export declare function getAgentGuidelinesTemplate(): string;
+/**
+ * Get a summary of the agent guidelines for inclusion in responses
+ * @returns A brief summary of key guidelines
+ */
+export declare function getAgentGuidelinesSummary(): string;

package/dist/templates/agent-guidelines.js

@@ -0,0 +1,207 @@
+/**
+ * Agent Guidelines Template
+ *
+ * This template contains the essential CLAUDE.md content that should be included
+ * in every project using Vibescope for agent tracking. These guidelines ensure
+ * agents follow proper workflows and maintain visibility.
+ */
+export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
+
+## Quick Start
+
+\`\`\`
+start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus")
+\`\`\`
+
+**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for "You are powered by the model named..." to determine your model.
+
+This returns your persona, project info, and \`next_task\`. Start working immediately.
+
+## CRITICAL: MCP Connection Required
+
+**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**
+
+### Why This Is Non-Negotiable
+
+Working without MCP connection causes:
+- **No progress visibility** - Humans can't see what you're doing
+- **Lost work tracking** - Tasks aren't tracked, time is wasted
+- **Workflow violations** - Other agents may conflict with your work
+- **Dashboard confusion** - Project state becomes inconsistent
+
+### Connection Failure Handling
+
+**If \`start_work_session\` fails or returns an error:**
+
+1. **Do NOT proceed with any work**
+2. **Inform the user** that MCP connection failed
+3. **End the session** - do not attempt workarounds
+4. **Provide troubleshooting steps:**
+   - Check if MCP server is configured: \`claude mcp list\`
+   - Verify API key is set: check \`.mcp.json\` or environment
+   - Restart Claude Code after fixing configuration
+
+**Example error responses you might see:**
+\`\`\`
+Error: Failed to start session
+Error: VIBESCOPE_API_KEY not set
+Error: Network error connecting to Vibescope API
+Error: MCP server 'vibescope' not found
+\`\`\`
+
+### Recovery Steps
+
+If MCP connection fails, tell the user:
+
+\`\`\`
+MCP connection to Vibescope failed. I cannot proceed without task tracking.
+
+To fix:
+1. Run: claude mcp list (verify vibescope is configured)
+2. Check API key: ensure VIBESCOPE_API_KEY is set
+3. Restart Claude Code
+4. Try again with: start_work_session(git_url: "...")
+
+I am ending this session to prevent untracked work.
+\`\`\`
+
+**Never "work around" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.
+
+## Core Workflow
+
+1. **Start session** → \`start_work_session(git_url, model)\` - Always include your model!
+2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\` - Returns git workflow instructions!
+3. **Set up worktree** → Create isolated worktree for this task (see Git Workflow below)
+4. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
+5. **Complete task** → \`complete_task(task_id, summary: "...")\` - **MANDATORY, see below!**
+6. **Clean up** → Remove worktree, then start next task immediately
+
+## CRITICAL: Always Call complete_task (MANDATORY)
+
+**You MUST call \`complete_task()\` when you finish a task.** This is not optional.
+
+### When to Call complete_task
+
+Call \`complete_task()\` immediately after:
+- ✅ Creating and pushing a PR
+- ✅ Merging changes (for trunk-based workflow)
+- ✅ Finishing any unit of work, even if no code changes
+
+**Do NOT wait for:**
+- ❌ PR to be reviewed/merged (that's what validation is for)
+- ❌ User confirmation
+- ❌ "Perfect" summary - a brief summary is fine
+
+### The Rule
+
+\`\`\`
+PR created + pushed → complete_task() → THEN worry about next steps
+\`\`\`
+
+**If you create a PR and don't call \`complete_task()\`, you have failed the workflow.**
+
+## CRITICAL: Git Worktrees for Multi-Agent
+
+When multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.
+
+**Before starting ANY task:**
+\`\`\`bash
+# For git-flow: ensure you're on develop first, then create worktree
+git checkout develop
+git pull origin develop
+git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
+cd ../worktree-<task-short-id>
+\`\`\`
+
+**After task is merged:**
+\`\`\`bash
+git worktree remove ../worktree-<task-short-id>
+\`\`\`
+
+**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.
+
+Run \`get_help("git")\` for full worktree documentation.
+
+## CRITICAL: Never Ask Permission
+
+**You must NEVER:**
+- Ask "Should I continue to the next task?" → Just continue
+- Ask "Should I clear my context?" → Just clear it
+- Ask "What should I do next?" → Check \`next_task\` or use fallback activities
+- Say "All tasks are done, let me know what to do" → Use \`get_next_task\` or start fallback activity
+- Wait for confirmation before clearing context → Just do it
+
+**You must ALWAYS:**
+- Call \`complete_task()\` immediately after creating/pushing a PR - this is non-negotiable
+- Immediately start the next task after completing one
+- Clear context and restart session automatically when needed
+- Keep working until there are genuinely no tasks and no fallback activities
+
+## Continuous Work
+
+**IMPORTANT: Never stop working!** When you complete a task:
+1. \`complete_task\` returns \`next_task\` → Start it immediately
+2. No \`next_task\`? → Call \`get_next_task(project_id)\`
+3. Still no tasks? → Start a \`fallback_activity\` (code_review, security_review, etc.)
+
+**When context grows large or responses slow down:**
+1. Run \`/clear\` to reset conversation
+2. Immediately call \`start_work_session(git_url, model)\` to reload context
+3. Continue with \`next_task\` from the response
+
+**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.
+
+## Need Help?
+
+Use \`get_help(topic)\` for detailed guidance:
+
+| Topic | Description |
+|-------|-------------|
+| \`getting_started\` | Basic workflow overview |
+| \`tasks\` | Working on tasks, progress tracking |
+| \`validation\` | Cross-agent task validation |
+| \`deployment\` | Deployment coordination |
+| \`git\` | Git workflow configuration |
+| \`blockers\` | Handling blockers |
+| \`milestones\` | Breaking down complex tasks |
+| \`fallback\` | Background activities when idle |
+| \`session\` | Session management |
+| \`topics\` | List all available topics |
+
+## MCP Server Not Connected?
+
+### Quick Setup (Claude Code)
+
+\`\`\`bash
+claude mcp add vibescope npx @vibescope/mcp-server@latest \\
+  --env VIBESCOPE_API_KEY=your_key
+\`\`\`
+
+### Manual Setup
+
+1. Copy \`.mcp.json.example\` to \`.mcp.json\`
+2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
+3. Restart Claude Code
+`;
+/**
+ * Get the agent guidelines template
+ * @returns The full agent guidelines markdown template
+ */
+export function getAgentGuidelinesTemplate() {
+    return AGENT_GUIDELINES_TEMPLATE;
+}
+/**
+ * Get a summary of the agent guidelines for inclusion in responses
+ * @returns A brief summary of key guidelines
+ */
+export function getAgentGuidelinesSummary() {
+    return `## Essential Agent Guidelines
+
+1. **MCP Connection Required** - If start_work_session fails, END SESSION IMMEDIATELY
+2. **Always call complete_task()** - After creating a PR, call complete_task() right away
+3. **Use git worktrees** - Create worktrees for each task to avoid conflicts
+4. **Never ask permission** - Just continue working, clear context when needed
+5. **Continuous work** - Never stop; use get_next_task or fallback activities
+
+For full guidelines, create a \`.claude/CLAUDE.md\` file in your project with the agent guidelines template.`;
+}