@vibescope/mcp-server 0.4.5 → 0.4.6

package/src/templates/agent-guidelines.ts

@@ -1,215 +1,233 @@
-/**
- * Agent Guidelines Template
- *
- * This template contains the essential CLAUDE.md content that should be included
- * in every project using Vibescope for agent tracking. These guidelines ensure
- * agents follow proper workflows and maintain visibility.
- */
-
-export const 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}
-`;
-
-/**
- * Get the agent guidelines template
- * @returns The full agent guidelines markdown template
- */
-export function getAgentGuidelinesTemplate(): string {
-	return AGENT_GUIDELINES_TEMPLATE;
-}
-
-/**
- * Get a summary of the agent guidelines for inclusion in responses
- * @returns A brief summary of key guidelines
- */
-export function getAgentGuidelinesSummary(): string {
-	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.`;
-}
+/**
+ * Agent Guidelines Template
+ *
+ * This template contains the essential CLAUDE.md content that should be included
+ * in every project using Vibescope for agent tracking. These guidelines ensure
+ * agents follow proper workflows and maintain visibility.
+ */
+
+export const 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. **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
+ * @returns The full agent guidelines markdown template
+ */
+export function getAgentGuidelinesTemplate(): string {
+	return AGENT_GUIDELINES_TEMPLATE;
+}
+
+/**
+ * Get a summary of the agent guidelines for inclusion in responses
+ * @returns A brief summary of key guidelines
+ */
+export function getAgentGuidelinesSummary(): string {
+	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.`;
+}