feat(mcp): implement taskmaestro dispatch strategy in AgentService

apps/mcp-server/src/agent/agent.service.spec.ts

@@ -578,4 +578,107 @@ describe('AgentService', () => {
       expect(result.parallelAgents).toHaveLength(1);
     });
   });
+
+  describe('dispatchAgents with taskmaestro strategy', () => {
+    it('should return taskmaestro field with assignments when strategy is taskmaestro', async () => {
+      vi.mocked(mockRulesService.getAgent!)
+        .mockResolvedValueOnce(mockSecurityAgent)
+        .mockResolvedValueOnce(mockPerformanceAgent);
+
+      const result = await service.dispatchAgents({
+        mode: 'EVAL',
+        specialists: ['security-specialist', 'performance-specialist'],
+        executionStrategy: 'taskmaestro',
+      });
+
+      expect(result.taskmaestro).toBeDefined();
+      expect(result.taskmaestro!.paneCount).toBe(2);
+      expect(result.taskmaestro!.assignments).toHaveLength(2);
+      expect(result.taskmaestro!.sessionName).toBe('eval-specialists');
+      expect(result.executionStrategy).toBe('taskmaestro');
+    });
+
+    it('should not include parallelAgents when strategy is taskmaestro', async () => {
+      vi.mocked(mockRulesService.getAgent!).mockResolvedValueOnce(mockSecurityAgent);
+
+      const result = await service.dispatchAgents({
+        mode: 'EVAL',
+        specialists: ['security-specialist'],
+        executionStrategy: 'taskmaestro',
+      });
+
+      expect(result.parallelAgents).toBeUndefined();
+      expect(result.taskmaestro).toBeDefined();
+    });
+
+    it('should include task description and target files in taskmaestro prompt', async () => {
+      vi.mocked(mockRulesService.getAgent!).mockResolvedValueOnce(mockSecurityAgent);
+
+      const result = await service.dispatchAgents({
+        mode: 'EVAL',
+        specialists: ['security-specialist'],
+        executionStrategy: 'taskmaestro',
+        taskDescription: 'Review auth flow',
+        targetFiles: ['src/auth.ts', 'src/middleware.ts'],
+      });
+
+      const prompt = result.taskmaestro!.assignments[0].prompt;
+      expect(prompt).toContain('Review auth flow');
+      expect(prompt).toContain('src/auth.ts');
+      expect(prompt).toContain('src/middleware.ts');
+    });
+
+    it('should include execution hint with correct pane count', async () => {
+      vi.mocked(mockRulesService.getAgent!)
+        .mockResolvedValueOnce(mockSecurityAgent)
+        .mockResolvedValueOnce(mockAccessibilityAgent)
+        .mockResolvedValueOnce(mockPerformanceAgent);
+
+      const result = await service.dispatchAgents({
+        mode: 'PLAN',
+        specialists: [
+          'architecture-specialist',
+          'test-strategy-specialist',
+          'integration-specialist',
+        ],
+        executionStrategy: 'taskmaestro',
+      });
+
+      expect(result.executionHint).toContain('/taskmaestro start --panes 3');
+      expect(result.executionHint).toContain('/taskmaestro assign');
+    });
+
+    it('should set sessionName based on mode', async () => {
+      vi.mocked(mockRulesService.getAgent!).mockResolvedValueOnce(mockSecurityAgent);
+      const planResult = await service.dispatchAgents({
+        mode: 'PLAN',
+        specialists: ['architecture-specialist'],
+        executionStrategy: 'taskmaestro',
+      });
+      expect(planResult.taskmaestro!.sessionName).toBe('plan-specialists');
+
+      vi.mocked(mockRulesService.getAgent!).mockResolvedValueOnce(mockSecurityAgent);
+      const actResult = await service.dispatchAgents({
+        mode: 'ACT',
+        specialists: ['code-quality-specialist'],
+        executionStrategy: 'taskmaestro',
+      });
+      expect(actResult.taskmaestro!.sessionName).toBe('act-specialists');
+    });
+
+    it('should still return subagent format when strategy is subagent', async () => {
+      vi.mocked(mockRulesService.getAgent!).mockResolvedValueOnce(mockSecurityAgent);
+
+      const result = await service.dispatchAgents({
+        mode: 'EVAL',
+        specialists: ['security-specialist'],
+        executionStrategy: 'subagent',
+        includeParallel: true,
+      });
+
+      expect(result.parallelAgents).toBeDefined();
+      expect(result.taskmaestro).toBeUndefined();
+      expect(result.executionStrategy).toBe('subagent');
+    });
+  });
 });

apps/mcp-server/src/agent/agent.service.ts

@@ -10,6 +10,7 @@ import type {
   DispatchAgentsInput,
   DispatchResult,
   DispatchedAgent,
+  TaskmaestroAssignment,
 } from './agent.types';
 import { FILE_PATTERN_SPECIALISTS } from './agent.types';
 import {
@@ -222,7 +223,31 @@ export class AgentService {
       }
     }
 
-    // Dispatch parallel agents
+    // Dispatch taskmaestro strategy
+    if (input.executionStrategy === 'taskmaestro' && input.specialists?.length) {
+      const uniqueSpecialists = Array.from(new Set(input.specialists));
+      const { agents, failedAgents } = await this.loadAgents(uniqueSpecialists, context, true);
+
+      const assignments: TaskmaestroAssignment[] = agents.map(agent => ({
+        name: agent.id,
+        displayName: agent.displayName,
+        prompt: this.buildTaskmaestroPrompt(agent, input),
+      }));
+
+      return {
+        primaryAgent: result.primaryAgent,
+        taskmaestro: {
+          sessionName: `${(input.mode ?? 'eval').toLowerCase()}-specialists`,
+          paneCount: assignments.length,
+          assignments,
+        },
+        executionStrategy: 'taskmaestro',
+        executionHint: this.buildTaskmaestroHint(assignments.length),
+        failedAgents: failedAgents.length > 0 ? failedAgents : result.failedAgents,
+      };
+    }
+
+    // Dispatch parallel agents (subagent strategy)
     if (input.includeParallel && input.specialists?.length) {
       const uniqueSpecialists = Array.from(new Set(input.specialists));
       const { agents, failedAgents } = await this.loadAgents(
@@ -251,6 +276,34 @@ export class AgentService {
       }
     }
 
+    result.executionStrategy = 'subagent';
     return result;
   }
+
+  private buildTaskmaestroPrompt(agent: PreparedAgent, input: DispatchAgentsInput): string {
+    const taskContext = input.taskDescription ? `\n\n**Task:** ${input.taskDescription}` : '';
+    const fileContext = input.targetFiles?.length
+      ? `\n\n**Target Files:**\n${input.targetFiles.map(f => '- ' + f).join('\n')}`
+      : '';
+
+    return `${agent.taskPrompt || agent.summary || ''}${taskContext}${fileContext}
+
+**Output Format:**
+- Severity: CRITICAL / HIGH / MEDIUM / LOW / INFO
+- File reference
+- Finding description
+- Recommendation
+
+When done, provide a summary of all findings.`;
+  }
+
+  private buildTaskmaestroHint(paneCount: number): string {
+    return `TaskMaestro execution:
+1. /taskmaestro start --panes ${paneCount}
+2. Wait for all panes to show Claude Code prompt
+3. For each assignment: /taskmaestro assign <pane_index> "<prompt>"
+4. /taskmaestro status — monitor progress
+5. When all panes show idle: collect results
+6. /taskmaestro stop all — cleanup`;
+  }
 }

apps/mcp-server/src/agent/agent.types.spec.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import type {
+  TaskmaestroAssignment,
+  TaskmaestroDispatch,
+  DispatchAgentsInput,
+  DispatchResult,
+} from './agent.types';
+
+describe('agent.types - TaskMaestro types', () => {
+  describe('TaskmaestroAssignment', () => {
+    it('accepts object with name, displayName, prompt', () => {
+      const assignment: TaskmaestroAssignment = {
+        name: 'frontend-dev',
+        displayName: 'Frontend Developer',
+        prompt: 'Implement the UI component',
+      };
+      expect(assignment.name).toBe('frontend-dev');
+      expect(assignment.displayName).toBe('Frontend Developer');
+      expect(assignment.prompt).toBe('Implement the UI component');
+    });
+  });
+
+  describe('TaskmaestroDispatch', () => {
+    it('accepts object with sessionName, paneCount, assignments', () => {
+      const dispatch: TaskmaestroDispatch = {
+        sessionName: 'workspace-1',
+        paneCount: 3,
+        assignments: [{ name: 'dev-1', displayName: 'Dev 1', prompt: 'Task 1' }],
+      };
+      expect(dispatch.sessionName).toBe('workspace-1');
+      expect(dispatch.paneCount).toBe(3);
+      expect(dispatch.assignments).toHaveLength(1);
+    });
+  });
+
+  describe('DispatchAgentsInput - executionStrategy', () => {
+    it('accepts executionStrategy: subagent', () => {
+      const input: DispatchAgentsInput = {
+        mode: 'PLAN',
+        executionStrategy: 'subagent',
+      };
+      expect(input.executionStrategy).toBe('subagent');
+    });
+
+    it('accepts executionStrategy: taskmaestro', () => {
+      const input: DispatchAgentsInput = {
+        mode: 'ACT',
+        executionStrategy: 'taskmaestro',
+      };
+      expect(input.executionStrategy).toBe('taskmaestro');
+    });
+
+    it('executionStrategy is optional', () => {
+      const input: DispatchAgentsInput = { mode: 'PLAN' };
+      expect(input.executionStrategy).toBeUndefined();
+    });
+  });
+
+  describe('DispatchResult - taskmaestro fields', () => {
+    it('accepts optional taskmaestro dispatch data', () => {
+      const result: DispatchResult = {
+        executionHint: 'Use taskmaestro for parallel execution',
+        taskmaestro: {
+          sessionName: 'ws-1',
+          paneCount: 2,
+          assignments: [],
+        },
+        executionStrategy: 'taskmaestro',
+      };
+      expect(result.taskmaestro?.sessionName).toBe('ws-1');
+      expect(result.executionStrategy).toBe('taskmaestro');
+    });
+
+    it('taskmaestro and executionStrategy are optional', () => {
+      const result: DispatchResult = {
+        executionHint: 'Use subagent',
+      };
+      expect(result.taskmaestro).toBeUndefined();
+      expect(result.executionStrategy).toBeUndefined();
+    });
+  });
+});

apps/mcp-server/src/agent/agent.types.ts

@@ -73,6 +73,24 @@ export interface DispatchedAgent {
   dispatchParams: DispatchParams;
 }
 
+/**
+ * A single TaskMaestro pane assignment with agent name and prompt
+ */
+export interface TaskmaestroAssignment {
+  name: string;
+  displayName: string;
+  prompt: string;
+}
+
+/**
+ * TaskMaestro dispatch configuration for parallel tmux pane execution
+ */
+export interface TaskmaestroDispatch {
+  sessionName: string;
+  paneCount: number;
+  assignments: TaskmaestroAssignment[];
+}
+
 /**
  * Result of dispatching agents for execution
  */
@@ -82,6 +100,10 @@ export interface DispatchResult {
   executionHint: string;
   /** Agents that failed to load */
   failedAgents?: FailedAgent[];
+  /** TaskMaestro dispatch data when executionStrategy is 'taskmaestro' */
+  taskmaestro?: TaskmaestroDispatch;
+  /** Execution strategy used for this dispatch */
+  executionStrategy?: string;
 }
 
 /**
@@ -94,6 +116,8 @@ export interface DispatchAgentsInput {
   specialists?: string[];
   includeParallel?: boolean;
   primaryAgent?: string;
+  /** Execution strategy: 'subagent' (default) or 'taskmaestro' */
+  executionStrategy?: 'subagent' | 'taskmaestro';
 }
 
 /**

apps/mcp-server/src/keyword/keyword.service.spec.ts

@@ -2677,4 +2677,31 @@ ${'Even more content.\n'.repeat(150)}`;
       expect(result.rules[0].content).toContain('## Section');
     });
   });
+
+  describe('taskmaestro detection', () => {
+    it('should include taskmaestro in availableStrategies when skill is available', async () => {
+      const detector = await import('./taskmaestro-detector');
+      const spy = vi.spyOn(detector, 'isTaskmaestroAvailable').mockReturnValue(true);
+
+      const result = await service.parseMode('PLAN test task', {});
+
+      expect(result.availableStrategies).toContain('subagent');
+      expect(result.availableStrategies).toContain('taskmaestro');
+      expect(result.taskmaestroInstallHint).toBeUndefined();
+
+      spy.mockRestore();
+    });
+
+    it('should return only subagent with installHint when taskmaestro not installed', async () => {
+      const detector = await import('./taskmaestro-detector');
+      const spy = vi.spyOn(detector, 'isTaskmaestroAvailable').mockReturnValue(false);
+
+      const result = await service.parseMode('PLAN test task', {});
+
+      expect(result.availableStrategies).toEqual(['subagent']);
+      expect(result.taskmaestroInstallHint).toContain('TaskMaestro skill not found');
+
+      spy.mockRestore();
+    });
+  });
 });

apps/mcp-server/src/keyword/keyword.service.ts

@@ -32,6 +32,7 @@ import { truncateSkillContent } from '../skill/skill-content.utils';
 import { createAgentSummary } from '../agent/agent-summary.utils';
 import { truncateRuleContent } from '../rules/rules-content.utils';
 import { getDefaultModeConfig } from '../shared/keyword-core';
+import { isTaskmaestroAvailable } from './taskmaestro-detector';
 import { type ClientType } from '../shared/client-type';
 
 /**
@@ -496,6 +497,14 @@ export class KeywordService {
     // 9. Auto-include primary agent system prompt (for MCP mode to force AI execution)
     await this.addIncludedAgentToResult(result, mode, options);
 
+    // 10. Add available execution strategies (subagent, taskmaestro)
+    const taskmaestroInstalled = isTaskmaestroAvailable();
+    result.availableStrategies = taskmaestroInstalled ? ['subagent', 'taskmaestro'] : ['subagent'];
+    if (!taskmaestroInstalled) {
+      result.taskmaestroInstallHint =
+        'TaskMaestro skill not found at ~/.claude/skills/taskmaestro/SKILL.md. To enable tmux-based parallel specialist execution, install the taskmaestro skill.';
+    }
+
     return result;
   }
 

apps/mcp-server/src/keyword/keyword.types.ts

@@ -440,6 +440,10 @@ export interface ParseModeResult {
    * without needing to call dispatch_agents or prepare_parallel_agents.
    */
   dispatchReady?: DispatchReady;
+  /** @apiProperty External API - do not rename. Available execution strategies (e.g. ['subagent', 'taskmaestro']) */
+  availableStrategies?: string[];
+  /** @apiProperty External API - do not rename. Hint for installing TaskMaestro when not available */
+  taskmaestroInstallHint?: string;
 }
 
 /**

apps/mcp-server/src/keyword/taskmaestro-detector.ts

@@ -0,0 +1,16 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Check if the TaskMaestro skill is installed at the expected path.
+ * @returns true if ~/.claude/skills/taskmaestro/SKILL.md exists
+ */
+export function isTaskmaestroAvailable(): boolean {
+  const skillPath = path.join(os.homedir(), '.claude', 'skills', 'taskmaestro', 'SKILL.md');
+  try {
+    return fs.existsSync(skillPath);
+  } catch {
+    return false;
+  }
+}