@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/utils.test.ts

@@ -43,8 +43,8 @@ describe('AGENT_PERSONAS', () => {
 // ============================================================================
 
 describe('FALLBACK_ACTIVITIES', () => {
-	it('should have 11 activities', () => {
-		expect(FALLBACK_ACTIVITIES).toHaveLength(11);
+	it('should have 12 activities', () => {
+		expect(FALLBACK_ACTIVITIES).toHaveLength(12);
 	});
 
 	it('should have required fields on each activity', () => {

package/src/utils.ts

@@ -133,6 +133,23 @@ export const FALLBACK_ACTIVITIES = [
 		description: 'Review tasks completed by other agents to ensure quality.',
 		prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
 	},
+	{
+		activity: 'worktree_cleanup',
+		title: 'Clean up stale worktrees',
+		description: 'Find and remove git worktrees from completed or abandoned tasks.',
+		prompt: `Clean up stale git worktrees to reclaim disk space and prevent confusion:
+
+1. Call get_stale_worktrees(project_id) to find worktrees needing cleanup
+2. For each stale worktree returned:
+   a. Check if the worktree directory exists: ls -la <worktree_path>
+   b. If it exists, remove it: git worktree remove <worktree_path>
+   c. If removal fails (untracked files), use: git worktree remove --force <worktree_path>
+   d. Call clear_worktree_path(task_id) to mark it as cleaned up
+3. Run 'git worktree list' to verify cleanup
+4. Log any issues encountered with add_blocker if worktrees cannot be removed
+
+This prevents disk bloat from accumulated worktrees and keeps the workspace clean.`,
+	},
 ] as const;
 
 export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];

package/dist/config/tool-categories.d.ts

@@ -1,31 +0,0 @@
-/**
- * Tool Categories Configuration
- *
- * Defines the categorization of MCP tools for discovery.
- * Moved to separate config for lazy-loading optimization.
- */
-export interface ToolEntry {
-    name: string;
-    brief: string;
-}
-export interface CategoryEntry {
-    description: string;
-    tools: ToolEntry[];
-}
-export declare const TOOL_CATEGORIES: Record<string, CategoryEntry>;
-/**
- * Get list of category names
- */
-export declare function getCategoryNames(): string[];
-/**
- * Get category summary (without full tool list)
- */
-export declare function getCategorySummary(): Array<{
-    name: string;
-    description: string;
-    tool_count: number;
-}>;
-/**
- * Get tools in a specific category
- */
-export declare function getCategoryTools(category: string): CategoryEntry | undefined;

package/dist/config/tool-categories.js

@@ -1,253 +0,0 @@
-/**
- * Tool Categories Configuration
- *
- * Defines the categorization of MCP tools for discovery.
- * Moved to separate config for lazy-loading optimization.
- */
-export const TOOL_CATEGORIES = {
-    session: {
-        description: 'Session lifecycle and monitoring',
-        tools: [
-            { name: 'start_work_session', brief: 'Initialize session, get next task' },
-            { name: 'get_help', brief: 'Get workflow guidance' },
-            { name: 'get_token_usage', brief: 'View token stats' },
-            { name: 'heartbeat', brief: 'Maintain active status' },
-            { name: 'end_work_session', brief: 'End session, release tasks' },
-        ],
-    },
-    project: {
-        description: 'Project CRUD and configuration',
-        tools: [
-            { name: 'get_project_context', brief: 'Full project info' },
-            { name: 'get_git_workflow', brief: 'Git branching config' },
-            { name: 'create_project', brief: 'Create new project' },
-            { name: 'update_project', brief: 'Modify project settings' },
-            { name: 'update_project_readme', brief: 'Sync README to dashboard' },
-        ],
-    },
-    tasks: {
-        description: 'Task management and tracking',
-        tools: [
-            { name: 'get_tasks', brief: 'List project tasks' },
-            { name: 'get_next_task', brief: 'Get highest priority task' },
-            { name: 'add_task', brief: 'Create new task' },
-            { name: 'update_task', brief: 'Update task status/progress' },
-            { name: 'complete_task', brief: 'Mark task done' },
-            { name: 'delete_task', brief: 'Remove a task' },
-            { name: 'batch_update_tasks', brief: 'Update multiple tasks' },
-            { name: 'batch_complete_tasks', brief: 'Complete multiple tasks' },
-            { name: 'add_task_reference', brief: 'Add URL to task' },
-            { name: 'remove_task_reference', brief: 'Remove URL from task' },
-        ],
-    },
-    milestones: {
-        description: 'Task breakdown into steps',
-        tools: [
-            { name: 'add_milestone', brief: 'Add step to task' },
-            { name: 'update_milestone', brief: 'Update milestone' },
-            { name: 'complete_milestone', brief: 'Mark step done' },
-            { name: 'delete_milestone', brief: 'Remove milestone' },
-            { name: 'get_milestones', brief: 'List task milestones' },
-        ],
-    },
-    progress: {
-        description: 'Progress logging and activity',
-        tools: [
-            { name: 'log_progress', brief: 'Record progress update' },
-            { name: 'get_activity_feed', brief: 'Combined activity feed' },
-        ],
-    },
-    blockers: {
-        description: 'Blocker management',
-        tools: [
-            { name: 'add_blocker', brief: 'Record a blocker' },
-            { name: 'resolve_blocker', brief: 'Mark resolved' },
-            { name: 'get_blockers', brief: 'List blockers' },
-            { name: 'delete_blocker', brief: 'Remove blocker' },
-        ],
-    },
-    decisions: {
-        description: 'Architectural decisions',
-        tools: [
-            { name: 'log_decision', brief: 'Record decision' },
-            { name: 'get_decisions', brief: 'List decisions' },
-            { name: 'delete_decision', brief: 'Remove decision' },
-        ],
-    },
-    ideas: {
-        description: 'Feature ideas tracking',
-        tools: [
-            { name: 'add_idea', brief: 'Record an idea' },
-            { name: 'update_idea', brief: 'Update idea status' },
-            { name: 'get_ideas', brief: 'List ideas' },
-            { name: 'delete_idea', brief: 'Remove idea' },
-            { name: 'convert_idea_to_task', brief: 'Convert idea to task' },
-        ],
-    },
-    findings: {
-        description: 'Audit findings/knowledge base',
-        tools: [
-            { name: 'add_finding', brief: 'Record audit finding' },
-            { name: 'get_findings', brief: 'List findings' },
-            { name: 'update_finding', brief: 'Update finding status' },
-            { name: 'delete_finding', brief: 'Remove finding' },
-        ],
-    },
-    validation: {
-        description: 'Cross-agent task validation',
-        tools: [
-            { name: 'get_tasks_awaiting_validation', brief: 'Unvalidated tasks' },
-            { name: 'claim_validation', brief: 'Claim task for review' },
-            { name: 'validate_task', brief: 'Approve/reject task' },
-        ],
-    },
-    deployment: {
-        description: 'Deployment coordination',
-        tools: [
-            { name: 'request_deployment', brief: 'Request deploy' },
-            { name: 'claim_deployment_validation', brief: 'Claim for validation' },
-            { name: 'report_validation', brief: 'Report build/test results' },
-            { name: 'check_deployment_status', brief: 'Get deploy status' },
-            { name: 'start_deployment', brief: 'Begin deployment' },
-            { name: 'complete_deployment', brief: 'Mark deploy done' },
-            { name: 'cancel_deployment', brief: 'Cancel deployment' },
-            { name: 'add_deployment_requirement', brief: 'Add pre-deploy step' },
-            { name: 'complete_deployment_requirement', brief: 'Mark step done' },
-            { name: 'get_deployment_requirements', brief: 'List pre-deploy steps' },
-            { name: 'schedule_deployment', brief: 'Schedule future deployment' },
-            { name: 'get_scheduled_deployments', brief: 'List scheduled deployments' },
-            { name: 'update_scheduled_deployment', brief: 'Update schedule config' },
-            { name: 'delete_scheduled_deployment', brief: 'Delete schedule' },
-            { name: 'trigger_scheduled_deployment', brief: 'Manual trigger' },
-            { name: 'check_due_deployments', brief: 'Check due schedules' },
-        ],
-    },
-    fallback: {
-        description: 'Background activities when idle',
-        tools: [
-            { name: 'start_fallback_activity', brief: 'Start background work' },
-            { name: 'stop_fallback_activity', brief: 'Stop background work' },
-            { name: 'get_activity_history', brief: 'Activity history' },
-            { name: 'get_activity_schedules', brief: 'Activity schedules' },
-        ],
-    },
-    bodies_of_work: {
-        description: 'Group tasks into bodies of work',
-        tools: [
-            { name: 'create_body_of_work', brief: 'Create task group' },
-            { name: 'update_body_of_work', brief: 'Update settings' },
-            { name: 'get_body_of_work', brief: 'Get with tasks' },
-            { name: 'get_bodies_of_work', brief: 'List bodies of work' },
-            { name: 'delete_body_of_work', brief: 'Remove body of work' },
-            { name: 'add_task_to_body_of_work', brief: 'Add task to group' },
-            { name: 'remove_task_from_body_of_work', brief: 'Remove from group' },
-            { name: 'activate_body_of_work', brief: 'Activate for work' },
-        ],
-    },
-    requests: {
-        description: 'User request handling',
-        tools: [
-            { name: 'get_pending_requests', brief: 'Unhandled requests' },
-            { name: 'acknowledge_request', brief: 'Mark handled' },
-            { name: 'answer_question', brief: 'Answer user question' },
-        ],
-    },
-    organizations: {
-        description: 'Organization and team management',
-        tools: [
-            { name: 'list_organizations', brief: 'List user orgs' },
-            { name: 'create_organization', brief: 'Create new org' },
-            { name: 'update_organization', brief: 'Update org settings' },
-            { name: 'delete_organization', brief: 'Delete org' },
-            { name: 'list_org_members', brief: 'List org members' },
-            { name: 'invite_member', brief: 'Invite by email' },
-            { name: 'update_member_role', brief: 'Change member role' },
-            { name: 'remove_member', brief: 'Remove from org' },
-            { name: 'leave_organization', brief: 'Leave an org' },
-            { name: 'share_project_with_org', brief: 'Share project' },
-            { name: 'update_project_share', brief: 'Update share perms' },
-            { name: 'unshare_project', brief: 'Remove share' },
-            { name: 'list_project_shares', brief: 'List project shares' },
-        ],
-    },
-    cost: {
-        description: 'Cost monitoring and alerts',
-        tools: [
-            { name: 'get_cost_summary', brief: 'Cost by period' },
-            { name: 'get_cost_alerts', brief: 'List cost alerts' },
-            { name: 'add_cost_alert', brief: 'Add threshold alert' },
-            { name: 'update_cost_alert', brief: 'Update alert config' },
-            { name: 'delete_cost_alert', brief: 'Remove alert' },
-            { name: 'get_task_costs', brief: 'Cost per task' },
-        ],
-    },
-    knowledge: {
-        description: 'Queryable knowledge base from project data',
-        tools: [
-            { name: 'query_knowledge_base', brief: 'Aggregated project knowledge in one call' },
-        ],
-    },
-    subtasks: {
-        description: 'Subtask management',
-        tools: [
-            { name: 'add_subtask', brief: 'Add subtask to parent' },
-            { name: 'get_subtasks', brief: 'List subtasks' },
-        ],
-    },
-    sprints: {
-        description: 'Sprint planning and tracking',
-        tools: [
-            { name: 'create_sprint', brief: 'Create new sprint' },
-            { name: 'update_sprint', brief: 'Update sprint' },
-            { name: 'get_sprint', brief: 'Get sprint details' },
-            { name: 'get_sprints', brief: 'List sprints' },
-            { name: 'delete_sprint', brief: 'Remove sprint' },
-            { name: 'start_sprint', brief: 'Start sprint' },
-            { name: 'complete_sprint', brief: 'End sprint' },
-            { name: 'add_task_to_sprint', brief: 'Add task' },
-            { name: 'remove_task_from_sprint', brief: 'Remove task' },
-            { name: 'get_sprint_backlog', brief: 'Available tasks' },
-            { name: 'get_sprint_velocity', brief: 'Velocity metrics' },
-        ],
-    },
-    git_issues: {
-        description: 'Git issue tracking',
-        tools: [
-            { name: 'add_git_issue', brief: 'Record git issue' },
-            { name: 'resolve_git_issue', brief: 'Mark resolved' },
-            { name: 'get_git_issues', brief: 'List git issues' },
-            { name: 'delete_git_issue', brief: 'Remove issue' },
-        ],
-    },
-    dependencies: {
-        description: 'Task dependencies',
-        tools: [
-            { name: 'add_task_dependency', brief: 'Add dependency' },
-            { name: 'remove_task_dependency', brief: 'Remove dependency' },
-            { name: 'get_task_dependencies', brief: 'List dependencies' },
-            { name: 'get_next_body_of_work_task', brief: 'Next available task' },
-        ],
-    },
-};
-/**
- * Get list of category names
- */
-export function getCategoryNames() {
-    return Object.keys(TOOL_CATEGORIES);
-}
-/**
- * Get category summary (without full tool list)
- */
-export function getCategorySummary() {
-    return Object.entries(TOOL_CATEGORIES).map(([name, cat]) => ({
-        name,
-        description: cat.description,
-        tool_count: cat.tools.length,
-    }));
-}
-/**
- * Get tools in a specific category
- */
-export function getCategoryTools(category) {
-    return TOOL_CATEGORIES[category];
-}

package/dist/knowledge.d.ts

@@ -1,6 +0,0 @@
-/**
- * Knowledge Base
- *
- * Embedded help topics for on-demand agent guidance.
- */
-export declare const KNOWLEDGE_BASE: Record<string, string>;

package/dist/knowledge.js

@@ -1,218 +0,0 @@
-/**
- * Knowledge Base
- *
- * Embedded help topics for on-demand agent guidance.
- */
-export const KNOWLEDGE_BASE = {
-    getting_started: `# Getting Started
-1. Call start_work_session(git_url) to initialize
-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)
-- Priority: 1=highest, 5=lowest`,
-    validation: `# Task Validation
-Completed tasks need validation before PR merge. PRIORITIZE validation over new tasks.
-
-## Validator Workflow
-
-### 1. Claim Task
-claim_validation(task_id) → Returns worktree_setup with existing branch
-
-### 2. Set Up Worktree (EXISTING branch)
-git fetch origin feature/task-branch
-git worktree add ../PROJECT-task-ID feature/task-branch
-cd ../PROJECT-task-ID
-
-### 3. Run Tests Locally
-pnpm install && pnpm test && pnpm build
-
-### 4. Approve or Reject
-
-**APPROVE** → Validator merges PR:
-validate_task(task_id, approved: true, validation_notes: "...")
-# Response includes merge instructions with PR URL
-gh pr merge <NUMBER> --squash
-git worktree remove ../PROJECT-task-ID
-
-**REJECT** → Create fix task:
-validate_task(task_id, approved: false, validation_notes: "Issues...", create_fix_task: true)
-# Creates fix task with SAME branch/PR
-# Fix agent picks up, pushes fixes to same PR
-git worktree remove ../PROJECT-task-ID
-
-## Key Rules
-- Validators check out EXISTING branches
-- On approval: validator merges immediately
-- On rejection: use create_fix_task: true
-- Always clean up worktree after validation`,
-    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.
-
-## Workflow Types
-- **none**: No branching strategy
-- **trunk-based**: Commit directly to main, small frequent commits
-- **github-flow**: Feature branches, merge via PR after validation
-- **git-flow**: develop/release/feature branches
-
-## Lifecycle Integration
-
-### 1. Starting a Task
-When you call update_task(status: "in_progress"), the response includes:
-- **branch_name**: Suggested branch (e.g., feature/a1b2c3d4-task-title)
-- **base_branch**: Branch to branch from
-- **steps**: Git commands to create the branch
-- **reminder**: Call to update task with git_branch
-
-### 2. Completing a Task
-When you call complete_task, the response includes:
-- **steps**: Push commands
-- **pr_suggestion**: { title, body_template } - ready-to-use PR content
-- **next_step**: Reminder that merge happens AFTER validation
-
-Add the PR link via add_task_reference(task_id, url, label: "Pull Request").
-
-### 3. Validation Approved
-When validate_task(approved: true) is called, the response includes:
-- **target_branch**: Where to merge
-- **feature_branch**: Branch being merged
-- **steps**: Merge options (UI or command line)
-- **cleanup**: Branch deletion commands
-- **note**: Confirmation it's safe to merge
-
-## Multi-Agent Worktrees (CRITICAL)
-
-When multiple agents share a repository, you MUST use git worktrees to prevent conflicts.
-
-### Why Worktrees?
-- Branch switching in shared repos causes file conflicts between agents
-- Uncommitted changes from one agent block another's work
-- Worktrees provide isolated working directories with shared .git
-
-### Setup (Once Per Task)
-\`\`\`bash
-# From main repo, create worktree for your task
-git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
-
-# Work in the worktree directory
-cd ../worktree-<task-short-id>
-\`\`\`
-
-### Cleanup (After Task Merged)
-\`\`\`bash
-# Remove worktree after PR merged
-git worktree remove ../worktree-<task-short-id>
-git branch -d feature/<task-id>-<title>
-\`\`\`
-
-### Worktree Rules
-- ALWAYS create a worktree before starting work on a task
-- Each agent works in their own worktree directory
-- Never switch branches in the main repo when other agents are active
-- Commit and push frequently to avoid losing work
-
-## Handling Merge Conflicts
-
-When claim_validation detects conflicts (via GitHub API):
-1. Response includes merge_conflict with rebase_instructions
-2. Checkout the feature branch locally
-3. Rebase onto target branch: \`git rebase origin/<target>\`
-4. Resolve conflicts, then: \`git add . && git rebase --continue\`
-5. Force push: \`git push origin <branch> --force-with-lease\`
-6. Re-claim validation to verify PR is now mergeable
-
-## Key Rules
-- Create worktree + branch when starting task (multi-agent environments)
-- Push and create PR when completing task
-- Wait for validation before merging
-- Resolve merge conflicts via rebase before approval
-- Clean up worktree and branch after successful merge`,
-    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
-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
-3. stop_fallback_activity(project_id, summary: "...")`,
-    session: `# Session Management
-- start_work_session initializes and returns next_task (lite mode default)
-- Use mode:'full' for complete context when needed
-- 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
-- Trust lite mode; only use full mode for initial exploration`,
-    sprints: `# Sprints
-Sprints are time-bounded bodies of work with velocity tracking.
-
-## Lifecycle
-1. **planning**: Create sprint, add tasks with story points
-2. **active**: Sprint in progress, working on tasks
-3. **in_review**: Sprint ended, reviewing completion
-4. **retrospective**: Post-sprint reflection
-5. **completed**: Final state, velocity recorded
-
-## Workflow
-1. create_sprint(project_id, title, start_date, end_date, goal)
-2. get_sprint_backlog(project_id) - view available tasks
-3. add_task_to_sprint(sprint_id, task_id, story_points) - add tasks
-4. start_sprint(sprint_id) - locks committed_points
-5. Work on tasks normally (they're assigned to the sprint)
-6. complete_sprint(sprint_id) - calculates final velocity
-
-## Velocity Tracking
-- committed_points: Total story points at sprint start
-- velocity_points: Story points completed by sprint end
-- get_sprint_velocity(project_id) - shows history and average velocity
-
-## Auto-Deployment
-Set auto_deploy_on_completion: true when creating sprint.
-Triggers deployment when sprint completes.`,
-    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
-- sprints: Time-bounded task groupings with velocity tracking`,
-};