@vibescope/mcp-server 0.4.4 → 0.4.6

package/dist/index.js

@@ -43,89 +43,89 @@ const handlerRegistry = buildHandlerRegistry();
 // Embedded Knowledge Base (on-demand help topics)
 // ============================================================================
 const KNOWLEDGE_BASE = {
-    getting_started: `# Getting Started
-1. Call start_work_session(git_url, model: "your-model-name") to initialize
-   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
-   - Check your system prompt for "You are powered by the model named..." to find it
-2. Response includes next_task - start working on it immediately
-3. Use update_task to mark in_progress and track progress
-4. Call complete_task when done - it returns your next task
+    getting_started: `# Getting Started
+1. Call start_work_session(git_url, model: "your-model-name") to initialize
+   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
+   - Check your system prompt for "You are powered by the model named..." to find it
+2. Response includes next_task - start working on it immediately
+3. Use update_task to mark in_progress and track progress
+4. Call complete_task when done - it returns your next task
 5. Use get_help(topic) when you need guidance on specific workflows`,
-    tasks: `# Task Workflow
-- Mark task in_progress with update_task before starting
-- Update progress_percentage regularly (every 15-20% progress)
-- Include progress_note to auto-log milestones
-- One task at a time - complete current before starting another
-- complete_task returns next_task and context counts (validation, blockers, deployment)
+    tasks: `# Task Workflow
+- Mark task in_progress with update_task before starting
+- Update progress_percentage regularly (every 15-20% progress)
+- Include progress_note to auto-log milestones
+- One task at a time - complete current before starting another
+- complete_task returns next_task and context counts (validation, blockers, deployment)
 - Priority: 1=highest, 5=lowest`,
-    validation: `# Task Validation
-Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
-1. Check: get_tasks_awaiting_validation(project_id)
-2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
-3. Review code changes and run tests
-4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
+    validation: `# Task Validation
+Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
+1. Check: get_tasks_awaiting_validation(project_id)
+2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
+3. Review code changes and run tests
+4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
 Self-validation allowed when single-agent or to unblock deployment.`,
-    deployment: `# Deployment Workflow
-1. Ensure all completed tasks are validated first
-2. request_deployment(project_id, environment: "production")
-3. claim_deployment_validation(project_id) - claim for validation
-4. Run: pnpm build && pnpm test
-5. report_validation(project_id, build_passed: true, tests_passed: true)
-6. start_deployment(project_id) - returns project's deployment_instructions
-7. Follow the instructions (e.g., push to main, run deploy command)
+    deployment: `# Deployment Workflow
+1. Ensure all completed tasks are validated first
+2. request_deployment(project_id, environment: "production")
+3. claim_deployment_validation(project_id) - claim for validation
+4. Run: pnpm build && pnpm test
+5. report_validation(project_id, build_passed: true, tests_passed: true)
+6. start_deployment(project_id) - returns project's deployment_instructions
+7. Follow the instructions (e.g., push to main, run deploy command)
 8. complete_deployment(project_id, success: true, summary: "...")`,
-    git: `# Git Workflow
-Call get_git_workflow(project_id) for project-specific config.
-Workflows: none, trunk-based, github-flow, git-flow
-- trunk-based: commit directly to main
-- github-flow: feature branches, merge via PR
-- git-flow: develop/release branches
+    git: `# Git Workflow
+Call get_git_workflow(project_id) for project-specific config.
+Workflows: none, trunk-based, github-flow, git-flow
+- trunk-based: commit directly to main
+- github-flow: feature branches, merge via PR
+- git-flow: develop/release branches
 Update task git_branch when working on a branch.`,
-    blockers: `# Working with Blockers
-When stuck and need human input:
-1. add_blocker(project_id, description: "What's blocking")
-2. Ask your question to the user
-3. resolve_blocker(blocker_id, resolution_note: "How resolved")
+    blockers: `# Working with Blockers
+When stuck and need human input:
+1. add_blocker(project_id, description: "What's blocking")
+2. Ask your question to the user
+3. resolve_blocker(blocker_id, resolution_note: "How resolved")
 Only use for genuine blockers requiring decisions - not routine questions.`,
-    milestones: `# Task Milestones
-For complex tasks, break into milestones:
-1. add_milestone(task_id, title: "Design schema")
-2. add_milestone(task_id, title: "Implement API")
-3. Update with complete_milestone(milestone_id) as you go
+    milestones: `# Task Milestones
+For complex tasks, break into milestones:
+1. add_milestone(task_id, title: "Design schema")
+2. add_milestone(task_id, title: "Implement API")
+3. Update with complete_milestone(milestone_id) as you go
 Dashboard shows progress bar with completed/total.`,
-    fallback: `# Fallback Activities
-When no tasks available, get_next_task suggests activities:
-- feature_ideation, code_review, performance_audit
-- security_review, test_coverage, documentation_review
-1. start_fallback_activity(project_id, activity: "code_review")
-2. Do the work, use add_finding for issues, add_idea for improvements
+    fallback: `# Fallback Activities
+When no tasks available, get_next_task suggests activities:
+- feature_ideation, code_review, performance_audit
+- security_review, test_coverage, documentation_review
+1. start_fallback_activity(project_id, activity: "code_review")
+2. Do the work, use add_finding for issues, add_idea for improvements
 3. stop_fallback_activity(project_id, summary: "...")`,
-    session: `# Session Management
-- start_work_session(git_url, model) initializes and returns next_task
-- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
-- Use mode:'lite' (default) or mode:'full' for complete context
-- heartbeat every 30-60 seconds maintains active status
-- end_work_session releases claimed tasks and returns summary
-- NEVER STOP: After completing a task, immediately start the next one
-- When context grows large: /clear then start_work_session to continue fresh
+    session: `# Session Management
+- start_work_session(git_url, model) initializes and returns next_task
+- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
+- Use mode:'lite' (default) or mode:'full' for complete context
+- heartbeat every 30-60 seconds maintains active status
+- end_work_session releases claimed tasks and returns summary
+- NEVER STOP: After completing a task, immediately start the next one
+- When context grows large: /clear then start_work_session to continue fresh
 - Your progress is saved to the dashboard - nothing is lost on /clear`,
-    tokens: `# Token Efficiency
-Be mindful of token costs - every tool call has a cost.
-- Use mode:'lite' (default) - saves ~85% vs full mode
-- Call get_token_usage() to check consumption
-- /compact when context grows large
-- Batch related updates when possible
+    tokens: `# Token Efficiency
+Be mindful of token costs - every tool call has a cost.
+- Use mode:'lite' (default) - saves ~85% vs full mode
+- Call get_token_usage() to check consumption
+- /compact when context grows large
+- Batch related updates when possible
 - Trust lite mode; only use full mode for initial exploration`,
-    topics: `# Available Help Topics
-- 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: `# Available Help Topics
+- 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
 - tokens: Token efficiency tips`,
 };
 // ============================================================================

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

@@ -7,7 +7,7 @@
  */
 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";
+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. **Post key milestones** \u2192 `post_progress(project_id, message, type)` - Keep humans informed!\n6. **Complete task** \u2192 `complete_task(task_id, summary: \"...\")` - **MANDATORY, see below!**\n7. **Clean up** \u2192 Remove worktree, then start next task immediately\n\n## Progress Updates via post_progress\n\nUse `post_progress(project_id, message, type)` to keep the team informed at key moments.\n\n| Type | When to use |\n|------|-------------|\n| `info` | General status update (started exploration, found issue, etc.) |\n| `milestone` | Key achievement reached (PR created, implementation complete, etc.) |\n| `blocker` | Something is blocking progress (missing context, dependency, error) |\n| `question` | Need human input or a decision |\n\n**Call `post_progress` when:**\n- Starting work on a task: `post_progress(project_id, \"Starting work on [task title]\", \"info\")`\n- Creating a PR: `post_progress(project_id, \"PR created: [url]\", \"milestone\")`\n- Hitting a blocker: `post_progress(project_id, \"[description of blocker]\", \"blocker\")`\n- Completing a task: `post_progress(project_id, \"Task complete: [brief summary]\", \"milestone\")`\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

@@ -7,185 +7,203 @@
  */
 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
-
-\`\`\`
-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
-${VIBESCOPE_SECTION_END}
+export const AGENT_GUIDELINES_TEMPLATE = `${VIBESCOPE_SECTION_START}
+# 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. **Post key milestones** → \`post_progress(project_id, message, type)\` - Keep humans informed!
+6. **Complete task** → \`complete_task(task_id, summary: "...")\` - **MANDATORY, see below!**
+7. **Clean up** → Remove worktree, then start next task immediately
+
+## Progress Updates via post_progress
+
+Use \`post_progress(project_id, message, type)\` to keep the team informed at key moments.
+
+| Type | When to use |
+|------|-------------|
+| \`info\` | General status update (started exploration, found issue, etc.) |
+| \`milestone\` | Key achievement reached (PR created, implementation complete, etc.) |
+| \`blocker\` | Something is blocking progress (missing context, dependency, error) |
+| \`question\` | Need human input or a decision |
+
+**Call \`post_progress\` when:**
+- Starting work on a task: \`post_progress(project_id, "Starting work on [task title]", "info")\`
+- Creating a PR: \`post_progress(project_id, "PR created: [url]", "milestone")\`
+- Hitting a blocker: \`post_progress(project_id, "[description of blocker]", "blocker")\`
+- Completing a task: \`post_progress(project_id, "Task complete: [brief summary]", "milestone")\`
+
+## 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
+${VIBESCOPE_SECTION_END}
 `;
 /**
  * Get the agent guidelines template
@@ -199,13 +217,13 @@ export function getAgentGuidelinesTemplate() {
  * @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
-
+    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.`;
 }