@vibescope/mcp-server 0.3.11 → 0.3.13

package/dist/api-client/findings.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Findings API Methods
+ *
+ * Methods for audit findings and knowledge base management:
+ * - getFindings: List findings for a project
+ * - getFinding: Get a specific finding
+ * - addFinding: Create a new finding
+ * - updateFinding: Update an existing finding
+ * - deleteFinding: Delete a finding
+ * - getFindingsStats: Get findings statistics
+ * - queryKnowledgeBase: Search findings as knowledge base
+ */
+import type { ApiResponse, RequestFn } from './types.js';
+export interface FindingsMethods {
+    getFindings(projectId: string, params?: {
+        category?: string;
+        severity?: string;
+        status?: string;
+        summary_only?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        findings: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            category: string;
+            severity: string;
+            status: string;
+            created_at: string;
+            updated_at?: string;
+            related_task_id?: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    getFinding(findingId: string): Promise<ApiResponse<{
+        id: string;
+        title: string;
+        description?: string;
+        category: string;
+        severity: string;
+        status: string;
+        created_at: string;
+        updated_at?: string;
+        related_task_id?: string;
+    }>>;
+    addFinding(params: {
+        project_id: string;
+        title: string;
+        description?: string;
+        category?: string;
+        severity?: string;
+        related_task_id?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    updateFinding(findingId: string, params: {
+        title?: string;
+        description?: string;
+        category?: string;
+        severity?: string;
+        status?: string;
+        related_task_id?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    deleteFinding(findingId: string): Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    getFindingsStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+        by_severity: Record<string, number>;
+        by_category: Record<string, number>;
+        by_status: Record<string, number>;
+    }>>;
+    queryKnowledgeBase(projectId: string, params: {
+        query: string;
+        category?: string;
+        severity?: string;
+        limit?: number;
+    }): Promise<ApiResponse<{
+        findings: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            category: string;
+            severity: string;
+            relevance_score?: number;
+        }>;
+        total_count: number;
+    }>>;
+}
+export declare function createFindingsMethods(request: RequestFn): FindingsMethods;

package/dist/api-client/findings.js

@@ -0,0 +1,55 @@
+/**
+ * Findings API Methods
+ *
+ * Methods for audit findings and knowledge base management:
+ * - getFindings: List findings for a project
+ * - getFinding: Get a specific finding
+ * - addFinding: Create a new finding
+ * - updateFinding: Update an existing finding
+ * - deleteFinding: Delete a finding
+ * - getFindingsStats: Get findings statistics
+ * - queryKnowledgeBase: Search findings as knowledge base
+ */
+export function createFindingsMethods(request) {
+    return {
+        async getFindings(projectId, params) {
+            return request('/api/mcp/projects/{id}/findings', 'GET', {
+                path: { id: projectId },
+                query: params,
+            });
+        },
+        async getFinding(findingId) {
+            return request('/api/mcp/findings/{id}', 'GET', {
+                path: { id: findingId },
+            });
+        },
+        async addFinding(params) {
+            return request('/api/mcp/projects/{id}/findings', 'POST', {
+                path: { id: params.project_id },
+                body: params,
+            });
+        },
+        async updateFinding(findingId, params) {
+            return request('/api/mcp/findings/{id}', 'PATCH', {
+                path: { id: findingId },
+                body: params,
+            });
+        },
+        async deleteFinding(findingId) {
+            return request('/api/mcp/findings/{id}', 'DELETE', {
+                path: { id: findingId },
+            });
+        },
+        async getFindingsStats(projectId) {
+            return request('/api/mcp/projects/{id}/findings/stats', 'GET', {
+                path: { id: projectId },
+            });
+        },
+        async queryKnowledgeBase(projectId, params) {
+            return request('/api/mcp/projects/{id}/findings/query', 'POST', {
+                path: { id: projectId },
+                body: params,
+            });
+        },
+    };
+}

package/dist/api-client/index.d.ts

@@ -16,6 +16,8 @@ import { type DiscoveryMethods } from './discovery.js';
 import { type DecisionsMethods } from './decisions.js';
 import { type IdeasMethods } from './ideas.js';
 import { type TasksMethods } from './tasks.js';
+import { type FindingsMethods } from './findings.js';
+import { type MilestonesMethods } from './milestones.js';
 export type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
 export type { SessionMethods } from './session.js';
 export type { ProjectMethods } from './project.js';
@@ -26,10 +28,12 @@ export type { DiscoveryMethods } from './discovery.js';
 export type { DecisionsMethods } from './decisions.js';
 export type { IdeasMethods } from './ideas.js';
 export type { TasksMethods } from './tasks.js';
+export type { FindingsMethods } from './findings.js';
+export type { MilestonesMethods } from './milestones.js';
 /**
  * Combined interface for all API methods
  */
-export interface VibescopeApiClientMethods extends SessionMethods, ProjectMethods, BlockersMethods, CostMethods, WorktreesMethods, DiscoveryMethods, DecisionsMethods, IdeasMethods, TasksMethods {
+export interface VibescopeApiClientMethods extends SessionMethods, ProjectMethods, BlockersMethods, CostMethods, WorktreesMethods, DiscoveryMethods, DecisionsMethods, IdeasMethods, TasksMethods, Omit<FindingsMethods, 'queryKnowledgeBase'>, MilestonesMethods {
 }
 export declare class VibescopeApiClient implements VibescopeApiClientMethods {
     private apiKey;
@@ -44,6 +48,8 @@ export declare class VibescopeApiClient implements VibescopeApiClientMethods {
     private decisionsMethods;
     private ideasMethods;
     private tasksMethods;
+    private findingsMethods;
+    private milestonesMethods;
     constructor(config: ApiClientConfig);
     private request;
     /**
@@ -568,7 +574,11 @@ export declare class VibescopeApiClient implements VibescopeApiClientMethods {
             estimated_minutes?: number;
             started_at?: string;
             completed_at?: string;
-            git_branch?: string;
+            git_branch
+            /**
+             * Combined interface for all API methods
+             */
+            ?: string;
             blocking?: boolean;
             references?: Array<{
                 url: string;
@@ -744,6 +754,80 @@ export declare class VibescopeApiClient implements VibescopeApiClientMethods {
             error?: string;
         }>;
     }>>;
+    getFindings: (projectId: string, params?: Parameters<FindingsMethods["getFindings"]>[1]) => Promise<ApiResponse<{
+        findings: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            category: string;
+            severity: string;
+            status: string;
+            created_at: string;
+            updated_at?: string;
+            related_task_id?: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    getFinding: (findingId: string) => Promise<ApiResponse<{
+        id: string;
+        title: string;
+        description?: string;
+        category: string;
+        severity: string;
+        status: string;
+        created_at: string;
+        updated_at?: string;
+        related_task_id?: string;
+    }>>;
+    addFinding: (params: Parameters<FindingsMethods["addFinding"]>[0]) => Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    updateFinding: (findingId: string, params: Parameters<FindingsMethods["updateFinding"]>[1]) => Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    deleteFinding: (findingId: string) => Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    getFindingsStats: (projectId: string) => Promise<ApiResponse<{
+        total: number;
+        by_severity: Record<string, number>;
+        by_category: Record<string, number>;
+        by_status: Record<string, number>;
+    }>>;
+    getMilestones: (projectId: string, params?: Parameters<MilestonesMethods["getMilestones"]>[1]) => Promise<ApiResponse<{
+        milestones: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            due_date?: string;
+            status: string;
+            created_at: string;
+            completed_at?: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    addMilestone: (params: Parameters<MilestonesMethods["addMilestone"]>[0]) => Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+    updateMilestone: (milestoneId: string, params: Parameters<MilestonesMethods["updateMilestone"]>[1]) => Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+    completeMilestone: (milestoneId: string, params?: Parameters<MilestonesMethods["completeMilestone"]>[1]) => Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+        completed_at: string;
+    }>>;
+    deleteMilestone: (milestoneId: string) => Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
 }
 export declare function getApiClient(): VibescopeApiClient;
 export declare function initApiClient(config: ApiClientConfig): VibescopeApiClient;

package/dist/api-client/index.js

@@ -15,6 +15,8 @@ import { createDiscoveryMethods } from './discovery.js';
 import { createDecisionsMethods } from './decisions.js';
 import { createIdeasMethods } from './ideas.js';
 import { createTasksMethods } from './tasks.js';
+import { createFindingsMethods } from './findings.js';
+import { createMilestonesMethods } from './milestones.js';
 const DEFAULT_API_URL = 'https://vibescope.dev';
 // Retry configuration defaults
 const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
@@ -52,6 +54,8 @@ export class VibescopeApiClient {
     decisionsMethods;
     ideasMethods;
     tasksMethods;
+    findingsMethods;
+    milestonesMethods;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
@@ -75,6 +79,8 @@ export class VibescopeApiClient {
         this.decisionsMethods = createDecisionsMethods(proxy);
         this.ideasMethods = createIdeasMethods(proxy);
         this.tasksMethods = createTasksMethods(request, proxy);
+        this.findingsMethods = createFindingsMethods(request);
+        this.milestonesMethods = createMilestonesMethods(request);
     }
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
@@ -242,6 +248,24 @@ export class VibescopeApiClient {
     removeTaskReference = (taskId, url) => this.tasksMethods.removeTaskReference(taskId, url);
     batchUpdateTasks = (updates) => this.tasksMethods.batchUpdateTasks(updates);
     batchCompleteTasks = (completions) => this.tasksMethods.batchCompleteTasks(completions);
+    // ============================================================================
+    // Findings methods (delegated)
+    // ============================================================================
+    getFindings = (projectId, params) => this.findingsMethods.getFindings(projectId, params);
+    getFinding = (findingId) => this.findingsMethods.getFinding(findingId);
+    addFinding = (params) => this.findingsMethods.addFinding(params);
+    updateFinding = (findingId, params) => this.findingsMethods.updateFinding(findingId, params);
+    deleteFinding = (findingId) => this.findingsMethods.deleteFinding(findingId);
+    getFindingsStats = (projectId) => this.findingsMethods.getFindingsStats(projectId);
+    // queryKnowledgeBase from FindingsMethods removed - duplicates DiscoveryMethods.queryKnowledgeBase (delegated above)
+    // ============================================================================
+    // Milestones methods (delegated)
+    // ============================================================================
+    getMilestones = (projectId, params) => this.milestonesMethods.getMilestones(projectId, params);
+    addMilestone = (params) => this.milestonesMethods.addMilestone(params);
+    updateMilestone = (milestoneId, params) => this.milestonesMethods.updateMilestone(milestoneId, params);
+    completeMilestone = (milestoneId, params) => this.milestonesMethods.completeMilestone(milestoneId, params);
+    deleteMilestone = (milestoneId) => this.milestonesMethods.deleteMilestone(milestoneId);
 }
 // Singleton instance
 let apiClient = null;

package/dist/api-client/milestones.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Milestones API Methods
+ *
+ * Methods for milestone management:
+ * - getMilestones: List milestones for a project
+ * - addMilestone: Create a new milestone
+ * - updateMilestone: Update an existing milestone
+ * - completeMilestone: Mark milestone as completed
+ * - deleteMilestone: Delete a milestone
+ */
+import type { ApiResponse, RequestFn } from './types.js';
+export interface MilestonesMethods {
+    getMilestones(projectId: string, params?: {
+        status?: 'pending' | 'completed';
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        milestones: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            due_date?: string;
+            status: string;
+            created_at: string;
+            completed_at?: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    addMilestone(params: {
+        project_id: string;
+        title: string;
+        description?: string;
+        due_date?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+    updateMilestone(milestoneId: string, params: {
+        title?: string;
+        description?: string;
+        due_date?: string;
+        status?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+    completeMilestone(milestoneId: string, params?: {
+        completion_note?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+        completed_at: string;
+    }>>;
+    deleteMilestone(milestoneId: string): Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+}
+export declare function createMilestonesMethods(request: RequestFn): MilestonesMethods;

package/dist/api-client/milestones.js

@@ -0,0 +1,43 @@
+/**
+ * Milestones API Methods
+ *
+ * Methods for milestone management:
+ * - getMilestones: List milestones for a project
+ * - addMilestone: Create a new milestone
+ * - updateMilestone: Update an existing milestone
+ * - completeMilestone: Mark milestone as completed
+ * - deleteMilestone: Delete a milestone
+ */
+export function createMilestonesMethods(request) {
+    return {
+        async getMilestones(projectId, params) {
+            return request('/api/mcp/projects/{id}/milestones', 'GET', {
+                path: { id: projectId },
+                query: params,
+            });
+        },
+        async addMilestone(params) {
+            return request('/api/mcp/projects/{id}/milestones', 'POST', {
+                path: { id: params.project_id },
+                body: params,
+            });
+        },
+        async updateMilestone(milestoneId, params) {
+            return request('/api/mcp/milestones/{id}', 'PATCH', {
+                path: { id: milestoneId },
+                body: params,
+            });
+        },
+        async completeMilestone(milestoneId, params) {
+            return request('/api/mcp/milestones/{id}/complete', 'POST', {
+                path: { id: milestoneId },
+                body: params,
+            });
+        },
+        async deleteMilestone(milestoneId) {
+            return request('/api/mcp/milestones/{id}', 'DELETE', {
+                path: { id: milestoneId },
+            });
+        },
+    };
+}

package/dist/cli-init.js

@@ -7,6 +7,7 @@
  * Detects installed AI agents, configures MCP, and stores credentials.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { getAgentGuidelinesTemplate, VIBESCOPE_SECTION_START, VIBESCOPE_SECTION_END } from './templates/agent-guidelines.js';
 import { homedir, platform } from 'node:os';
 import { join, dirname } from 'node:path';
 import { exec, execSync } from 'node:child_process';
@@ -408,6 +409,49 @@ ${c.dim}  AI project tracking for vibe coders${c.reset}
             console.log(`  ${icon.cross} Failed to configure ${agent.name}: ${err instanceof Error ? err.message : 'unknown error'}`);
         }
     }
+    // Step 5: Generate or update .claude/CLAUDE.md
+    const claudeMdPath = join(process.cwd(), '.claude', 'CLAUDE.md');
+    const claudeDir = join(process.cwd(), '.claude');
+    if (!existsSync(claudeDir)) {
+        mkdirSync(claudeDir, { recursive: true });
+    }
+    const vibescopeGuidelines = getAgentGuidelinesTemplate();
+    if (existsSync(claudeMdPath)) {
+        const existing = readFileSync(claudeMdPath, 'utf-8');
+        const hasVibescopeSection = existing.includes(VIBESCOPE_SECTION_START);
+        if (hasVibescopeSection) {
+            // Replace existing Vibescope section
+            const update = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} already has Vibescope guidelines. Update them?`, true);
+            if (update) {
+                const startIdx = existing.indexOf(VIBESCOPE_SECTION_START);
+                const endIdx = existing.indexOf(VIBESCOPE_SECTION_END);
+                if (startIdx !== -1 && endIdx !== -1) {
+                    const updated = existing.substring(0, startIdx) + vibescopeGuidelines + existing.substring(endIdx + VIBESCOPE_SECTION_END.length);
+                    writeFileSync(claudeMdPath, updated);
+                    console.log(`  ${icon.check} Updated Vibescope section in ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+                }
+            }
+            else {
+                console.log(`  ${icon.dot} Skipped CLAUDE.md update`);
+            }
+        }
+        else {
+            // Append Vibescope guidelines to existing file
+            const append = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} exists. Append Vibescope guidelines?`, true);
+            if (append) {
+                const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+                writeFileSync(claudeMdPath, existing + separator + vibescopeGuidelines);
+                console.log(`  ${icon.check} Appended Vibescope guidelines to ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+            }
+            else {
+                console.log(`  ${icon.dot} Skipped CLAUDE.md`);
+            }
+        }
+    }
+    else {
+        writeFileSync(claudeMdPath, vibescopeGuidelines);
+        console.log(`  ${icon.check} Created ${c.cyan}.claude/CLAUDE.md${c.reset} with agent guidelines`);
+    }
     // Done!
     console.log(`
 ${c.green}${c.bold}Setup complete!${c.reset}

package/dist/handlers/session.js

@@ -148,6 +148,7 @@ export const startWorkSession = async (args, ctx) => {
     result.auto_continue = true;
     // 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;
@@ -276,6 +277,22 @@ 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
+    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');
+    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}`);
+    }
+    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.');
+    result.AGENT_RULES = agentRules;
     // 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/dist/handlers/tasks.js

@@ -418,7 +418,7 @@ export const updateTask = 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]")',
             ],

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

@@ -5,7 +5,9 @@
  * 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";
+export declare const VIBESCOPE_SECTION_START = "<!-- vibescope:start -->";
+export declare const VIBESCOPE_SECTION_END = "<!-- vibescope:end -->";
+export declare const AGENT_GUIDELINES_TEMPLATE = "<!-- vibescope:start -->\n# 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<!-- vibescope:end -->\n";
 /**
  * Get the agent guidelines template
  * @returns The full agent guidelines markdown template

package/dist/templates/agent-guidelines.js

@@ -5,7 +5,10 @@
  * 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
+export const VIBESCOPE_SECTION_START = '<!-- vibescope:start -->';
+export const VIBESCOPE_SECTION_END = '<!-- vibescope:end -->';
+export const AGENT_GUIDELINES_TEMPLATE = `${VIBESCOPE_SECTION_START}
+# Vibescope Agent Guidelines
 
 ## Quick Start
 
@@ -182,6 +185,7 @@ claude mcp add vibescope npx @vibescope/mcp-server@latest \\
 1. Copy \`.mcp.json.example\` to \`.mcp.json\`
 2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
 3. Restart Claude Code
+${VIBESCOPE_SECTION_END}
 `;
 /**
  * Get the agent guidelines template

package/dist/templates/help-content.js

@@ -214,14 +214,14 @@ add_finding(
   title: "Fix exists but awaits deployment",
   category: "other",
   severity: "info",
-  description: "The fix for [issue] was implemented in PR #XXX but hasn't been deployed yet.",
+  description: "The fix for [issue] was implemented in PR #{pr_number} but hasn't been deployed yet.",
   related_task_id: task_id
 )
 \`\`\`
 
 2. **Complete the task** (investigation is done):
 \`\`\`
-complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment to production.")
+complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment to production.")
 \`\`\`
 
 3. **Request deployment** if not already pending:

package/docs/TOOLS.md

@@ -2,7 +2,7 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-02-15
+> Generated: 2026-02-18
 >
 > Total tools: 159
 
@@ -416,6 +416,7 @@ For projects without git branching (trunk-based or none), use skip_worktree_requ
 | `worktree_hostname` | `string` | No | Machine hostname where worktree was created (os.hostname()). Required with worktree_path to enable machine-aware cleanup. |
 | `model_capability` | `"haiku" | "sonnet" | "opus"` | No | Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning) |
 | `skip_worktree_requirement` | `boolean` | No | Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false |
+| `session_id` | `string` | No | Session ID from start_work_session. Required for cloud agents using mcporter (session context is not preserved between calls). Links the task to your agent on the dashboard. |
 
 ---
 
@@ -447,6 +448,7 @@ The auto_continue: true flag in the response means you are expected to continue
 |-----------|------|----------|-------------|
 | `task_id` | `string` | Yes | Task UUID |
 | `summary` | `string` | No | Brief summary of what was done. This is stored on the task as completion_summary and displayed when reviewing completed tasks. |
+| `session_id` | `string` | No | Session ID from start_work_session. Required for cloud agents using mcporter. |
 
 ---
 

package/package.json

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

package/src/api-client/findings.ts

@@ -0,0 +1,154 @@
+/**
+ * Findings API Methods
+ *
+ * Methods for audit findings and knowledge base management:
+ * - getFindings: List findings for a project
+ * - getFinding: Get a specific finding
+ * - addFinding: Create a new finding
+ * - updateFinding: Update an existing finding
+ * - deleteFinding: Delete a finding
+ * - getFindingsStats: Get findings statistics
+ * - queryKnowledgeBase: Search findings as knowledge base
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface FindingsMethods {
+	getFindings(projectId: string, params?: {
+		category?: string;
+		severity?: string;
+		status?: string;
+		summary_only?: boolean;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		findings: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			category: string;
+			severity: string;
+			status: string;
+			created_at: string;
+			updated_at?: string;
+			related_task_id?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>>;
+
+	getFinding(findingId: string): Promise<ApiResponse<{
+		id: string;
+		title: string;
+		description?: string;
+		category: string;
+		severity: string;
+		status: string;
+		created_at: string;
+		updated_at?: string;
+		related_task_id?: string;
+	}>>;
+
+	addFinding(params: {
+		project_id: string;
+		title: string;
+		description?: string;
+		category?: string;
+		severity?: string;
+		related_task_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>>;
+
+	updateFinding(findingId: string, params: {
+		title?: string;
+		description?: string;
+		category?: string;
+		severity?: string;
+		status?: string;
+		related_task_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>>;
+
+	deleteFinding(findingId: string): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>>;
+
+	getFindingsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_severity: Record<string, number>;
+		by_category: Record<string, number>;
+		by_status: Record<string, number>;
+	}>>;
+
+	queryKnowledgeBase(projectId: string, params: {
+		query: string;
+		category?: string;
+		severity?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		findings: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			category: string;
+			severity: string;
+			relevance_score?: number;
+		}>;
+		total_count: number;
+	}>>;
+}
+
+export function createFindingsMethods(request: RequestFn): FindingsMethods {
+	return {
+		async getFindings(projectId, params) {
+			return request('/api/mcp/projects/{id}/findings', 'GET', {
+				path: { id: projectId },
+				query: params,
+			});
+		},
+
+		async getFinding(findingId) {
+			return request('/api/mcp/findings/{id}', 'GET', {
+				path: { id: findingId },
+			});
+		},
+
+		async addFinding(params) {
+			return request('/api/mcp/projects/{id}/findings', 'POST', {
+				path: { id: params.project_id },
+				body: params,
+			});
+		},
+
+		async updateFinding(findingId, params) {
+			return request('/api/mcp/findings/{id}', 'PATCH', {
+				path: { id: findingId },
+				body: params,
+			});
+		},
+
+		async deleteFinding(findingId) {
+			return request('/api/mcp/findings/{id}', 'DELETE', {
+				path: { id: findingId },
+			});
+		},
+
+		async getFindingsStats(projectId) {
+			return request('/api/mcp/projects/{id}/findings/stats', 'GET', {
+				path: { id: projectId },
+			});
+		},
+
+		async queryKnowledgeBase(projectId, params) {
+			return request('/api/mcp/projects/{id}/findings/query', 'POST', {
+				path: { id: projectId },
+				body: params,
+			});
+		},
+	};
+}

package/src/api-client/index.ts

@@ -17,6 +17,8 @@ import { createDiscoveryMethods, type DiscoveryMethods } from './discovery.js';
 import { createDecisionsMethods, type DecisionsMethods } from './decisions.js';
 import { createIdeasMethods, type IdeasMethods } from './ideas.js';
 import { createTasksMethods, type TasksMethods } from './tasks.js';
+import { createFindingsMethods, type FindingsMethods } from './findings.js';
+import { createMilestonesMethods, type MilestonesMethods } from './milestones.js';
 
 // Re-export types
 export type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
@@ -29,6 +31,8 @@ export type { DiscoveryMethods } from './discovery.js';
 export type { DecisionsMethods } from './decisions.js';
 export type { IdeasMethods } from './ideas.js';
 export type { TasksMethods } from './tasks.js';
+export type { FindingsMethods } from './findings.js';
+export type { MilestonesMethods } from './milestones.js';
 
 const DEFAULT_API_URL = 'https://vibescope.dev';
 
@@ -74,7 +78,9 @@ export interface VibescopeApiClientMethods
 		DiscoveryMethods,
 		DecisionsMethods,
 		IdeasMethods,
-		TasksMethods {}
+		TasksMethods,
+		Omit<FindingsMethods, 'queryKnowledgeBase'>,
+		MilestonesMethods {}
 
 export class VibescopeApiClient implements VibescopeApiClientMethods {
 	private apiKey: string;
@@ -91,6 +97,8 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 	private decisionsMethods: DecisionsMethods;
 	private ideasMethods: IdeasMethods;
 	private tasksMethods: TasksMethods;
+	private findingsMethods: FindingsMethods;
+	private milestonesMethods: MilestonesMethods;
 
 	constructor(config: ApiClientConfig) {
 		this.apiKey = config.apiKey;
@@ -117,6 +125,8 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 		this.decisionsMethods = createDecisionsMethods(proxy);
 		this.ideasMethods = createIdeasMethods(proxy);
 		this.tasksMethods = createTasksMethods(request, proxy);
+		this.findingsMethods = createFindingsMethods(request);
+		this.milestonesMethods = createMilestonesMethods(request);
 	}
 
 	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
@@ -304,11 +314,29 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 	batchUpdateTasks = (updates: Parameters<TasksMethods['batchUpdateTasks']>[0]) => this.tasksMethods.batchUpdateTasks(updates);
 	batchCompleteTasks = (completions: Parameters<TasksMethods['batchCompleteTasks']>[0]) => this.tasksMethods.batchCompleteTasks(completions);
 
+	// ============================================================================
+	// Findings methods (delegated)
+	// ============================================================================
+	getFindings = (projectId: string, params?: Parameters<FindingsMethods['getFindings']>[1]) => this.findingsMethods.getFindings(projectId, params);
+	getFinding = (findingId: string) => this.findingsMethods.getFinding(findingId);
+	addFinding = (params: Parameters<FindingsMethods['addFinding']>[0]) => this.findingsMethods.addFinding(params);
+	updateFinding = (findingId: string, params: Parameters<FindingsMethods['updateFinding']>[1]) => this.findingsMethods.updateFinding(findingId, params);
+	deleteFinding = (findingId: string) => this.findingsMethods.deleteFinding(findingId);
+	getFindingsStats = (projectId: string) => this.findingsMethods.getFindingsStats(projectId);
+	// queryKnowledgeBase from FindingsMethods removed - duplicates DiscoveryMethods.queryKnowledgeBase (delegated above)
+
+	// ============================================================================
+	// Milestones methods (delegated)
+	// ============================================================================
+	getMilestones = (projectId: string, params?: Parameters<MilestonesMethods['getMilestones']>[1]) => this.milestonesMethods.getMilestones(projectId, params);
+	addMilestone = (params: Parameters<MilestonesMethods['addMilestone']>[0]) => this.milestonesMethods.addMilestone(params);
+	updateMilestone = (milestoneId: string, params: Parameters<MilestonesMethods['updateMilestone']>[1]) => this.milestonesMethods.updateMilestone(milestoneId, params);
+	completeMilestone = (milestoneId: string, params?: Parameters<MilestonesMethods['completeMilestone']>[1]) => this.milestonesMethods.completeMilestone(milestoneId, params);
+	deleteMilestone = (milestoneId: string) => this.milestonesMethods.deleteMilestone(milestoneId);
+
 	// ============================================================================
 	// TODO: Additional methods to be migrated from original api-client.ts
 	// The following domains need to be split into separate files:
-	// - findings.ts (getFindings, addFinding, etc.)
-	// - milestones.ts (getMilestones, addMilestone, etc.)
 	// - requests.ts (getPendingRequests, answerQuestion, etc.)
 	// - validation.ts (getTasksAwaitingValidation, validateTask, etc.)
 	// - fallback.ts (startFallbackActivity, stopFallbackActivity)

package/src/api-client/milestones.ts

@@ -0,0 +1,103 @@
+/**
+ * Milestones API Methods
+ *
+ * Methods for milestone management:
+ * - getMilestones: List milestones for a project
+ * - addMilestone: Create a new milestone
+ * - updateMilestone: Update an existing milestone
+ * - completeMilestone: Mark milestone as completed
+ * - deleteMilestone: Delete a milestone
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface MilestonesMethods {
+	getMilestones(projectId: string, params?: {
+		status?: 'pending' | 'completed';
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		milestones: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			due_date?: string;
+			status: string;
+			created_at: string;
+			completed_at?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>>;
+
+	addMilestone(params: {
+		project_id: string;
+		title: string;
+		description?: string;
+		due_date?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+	}>>;
+
+	updateMilestone(milestoneId: string, params: {
+		title?: string;
+		description?: string;
+		due_date?: string;
+		status?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+	}>>;
+
+	completeMilestone(milestoneId: string, params?: {
+		completion_note?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+		completed_at: string;
+	}>>;
+
+	deleteMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+	}>>;
+}
+
+export function createMilestonesMethods(request: RequestFn): MilestonesMethods {
+	return {
+		async getMilestones(projectId, params) {
+			return request('/api/mcp/projects/{id}/milestones', 'GET', {
+				path: { id: projectId },
+				query: params,
+			});
+		},
+
+		async addMilestone(params) {
+			return request('/api/mcp/projects/{id}/milestones', 'POST', {
+				path: { id: params.project_id },
+				body: params,
+			});
+		},
+
+		async updateMilestone(milestoneId, params) {
+			return request('/api/mcp/milestones/{id}', 'PATCH', {
+				path: { id: milestoneId },
+				body: params,
+			});
+		},
+
+		async completeMilestone(milestoneId, params) {
+			return request('/api/mcp/milestones/{id}/complete', 'POST', {
+				path: { id: milestoneId },
+				body: params,
+			});
+		},
+
+		async deleteMilestone(milestoneId) {
+			return request('/api/mcp/milestones/{id}', 'DELETE', {
+				path: { id: milestoneId },
+			});
+		},
+	};
+}

package/src/cli-init.ts

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { getAgentGuidelinesTemplate, VIBESCOPE_SECTION_START, VIBESCOPE_SECTION_END } from './templates/agent-guidelines.js';
 import { homedir, platform } from 'node:os';
 import { join, dirname } from 'node:path';
 import { exec, execSync } from 'node:child_process';
@@ -466,6 +467,49 @@ ${c.dim}  AI project tracking for vibe coders${c.reset}
 		}
 	}
 
+	// Step 5: Generate or update .claude/CLAUDE.md
+	const claudeMdPath = join(process.cwd(), '.claude', 'CLAUDE.md');
+	const claudeDir = join(process.cwd(), '.claude');
+	if (!existsSync(claudeDir)) {
+		mkdirSync(claudeDir, { recursive: true });
+	}
+
+	const vibescopeGuidelines = getAgentGuidelinesTemplate();
+
+	if (existsSync(claudeMdPath)) {
+		const existing = readFileSync(claudeMdPath, 'utf-8');
+		const hasVibescopeSection = existing.includes(VIBESCOPE_SECTION_START);
+
+		if (hasVibescopeSection) {
+			// Replace existing Vibescope section
+			const update = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} already has Vibescope guidelines. Update them?`, true);
+			if (update) {
+				const startIdx = existing.indexOf(VIBESCOPE_SECTION_START);
+				const endIdx = existing.indexOf(VIBESCOPE_SECTION_END);
+				if (startIdx !== -1 && endIdx !== -1) {
+					const updated = existing.substring(0, startIdx) + vibescopeGuidelines + existing.substring(endIdx + VIBESCOPE_SECTION_END.length);
+					writeFileSync(claudeMdPath, updated);
+					console.log(`  ${icon.check} Updated Vibescope section in ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+				}
+			} else {
+				console.log(`  ${icon.dot} Skipped CLAUDE.md update`);
+			}
+		} else {
+			// Append Vibescope guidelines to existing file
+			const append = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} exists. Append Vibescope guidelines?`, true);
+			if (append) {
+				const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+				writeFileSync(claudeMdPath, existing + separator + vibescopeGuidelines);
+				console.log(`  ${icon.check} Appended Vibescope guidelines to ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+			} else {
+				console.log(`  ${icon.dot} Skipped CLAUDE.md`);
+			}
+		}
+	} else {
+		writeFileSync(claudeMdPath, vibescopeGuidelines);
+		console.log(`  ${icon.check} Created ${c.cyan}.claude/CLAUDE.md${c.reset} with agent guidelines`);
+	}
+
 	// Done!
 	console.log(`
 ${c.green}${c.bold}Setup complete!${c.reset}

package/src/handlers/session.ts

@@ -179,6 +179,7 @@ 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;
@@ -320,6 +321,25 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		}
 	}
 
+	// Build top-level AGENT_RULES - critical rules agents must follow
+	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');
+
+	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}`);
+	}
+	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.');
+
+	result.AGENT_RULES = agentRules;
+
 	// 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/src/handlers/tasks.ts

@@ -516,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]")',
 			],

package/src/templates/agent-guidelines.ts

@@ -6,7 +6,11 @@
  * agents follow proper workflows and maintain visibility.
  */
 
-export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
+export const VIBESCOPE_SECTION_START = '<!-- vibescope:start -->';
+export const VIBESCOPE_SECTION_END = '<!-- vibescope:end -->';
+
+export const AGENT_GUIDELINES_TEMPLATE = `${VIBESCOPE_SECTION_START}
+# Vibescope Agent Guidelines
 
 ## Quick Start
 
@@ -183,6 +187,7 @@ claude mcp add vibescope npx @vibescope/mcp-server@latest \\
 1. Copy \`.mcp.json.example\` to \`.mcp.json\`
 2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
 3. Restart Claude Code
+${VIBESCOPE_SECTION_END}
 `;
 
 /**

package/src/templates/help-content.ts

@@ -217,14 +217,14 @@ add_finding(
   title: "Fix exists but awaits deployment",
   category: "other",
   severity: "info",
-  description: "The fix for [issue] was implemented in PR #XXX but hasn't been deployed yet.",
+  description: "The fix for [issue] was implemented in PR #{pr_number} but hasn't been deployed yet.",
   related_task_id: task_id
 )
 \`\`\`
 
 2. **Complete the task** (investigation is done):
 \`\`\`
-complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment to production.")
+complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment to production.")
 \`\`\`
 
 3. **Request deployment** if not already pending: